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

Mark the optparse module as soft deprecated.

diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 931360370d084c402b387c5c173282a2678f6173..a4650a6c3efa225df17a4e8feb8e58be552d9b83 100644 (file)
--- 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 0cff38174523644b73fcfe5fe7384acf5ff837cb..01177a04ab434d177a607a944c8fbb9a5ac06f80 100644 (file)
--- 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.
 
 --------------