[Python-checkins] gh-106535: Document PEP 387 Soft Deprecation (#106536)

[vstinner]

https://github.com/python/cpython/commit/d524b6f61f0b9fe4c359373185bf08bab423a218
commit: d524b6f61f0b9fe4c359373185bf08bab423a218
branch: main
author: Victor Stinner <vstinner at python.org>
committer: vstinner <vstinner at python.org>
date: 2023-07-08T00:03:51+02:00
summary:

gh-106535: Document PEP 387 Soft Deprecation (#106536)

Mark the optparse module as soft deprecated.

files:
M Doc/glossary.rst
M Doc/library/optparse.rst

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 931360370d084..a4650a6c3efa2 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -1107,6 +1107,21 @@ Glossary
       when several are given, such as in ``variable_name[1:3:5]``.  The bracket
       (subscript) notation uses :class:`slice` objects internally.
 
+   soft deprecated
+      A soft deprecation can be used when using an API which should no longer
+      be used to write new code, but it remains safe to continue using it in
+      existing code. The API remains documented and tested, but will not be
+      developed further (no enhancement).
+
+      The main difference between a "soft" and a (regular) "hard" deprecation
+      is that the soft deprecation does not imply scheduling the removal of the
+      deprecated API.
+
+      Another difference is that a soft deprecation does not issue a warning.
+
+      See `PEP 387: Soft Deprecation
+      <https://peps.python.org/pep-0387/#soft-deprecation>`_.
+
    special method
       .. index:: pair: special; method
 
diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index 0cff381745236..01177a04ab434 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -11,8 +11,9 @@
 **Source code:** :source:`Lib/optparse.py`
 
 .. deprecated:: 3.2
-   The :mod:`optparse` module is deprecated and will not be developed further;
-   development will continue with the :mod:`argparse` module.
+   The :mod:`optparse` module is :term:`soft deprecated` and will not be
+   developed further; development will continue with the :mod:`argparse`
+   module.
 
 --------------