Remove getopt and optparse deprecation notices

python · ncoghlan · Dec 23, 2024 · Oct 31, 2024 · Oct 31, 2024 · Oct 31, 2024
commit a560986a7f8cb3c0095bfb77d04d4cbaad0e2034
diff --git a/Doc/library/allos.rst b/Doc/library/allos.rst
@@ -15,14 +15,9 @@ but they are available on most other systems as well.  Here's an overview:
    os.rst
    io.rst
    time.rst
-   argparse.rst
    logging.rst
    logging.config.rst
    logging.handlers.rst
-   getpass.rst
-   curses.rst
-   curses.ascii.rst
-   curses.panel.rst
    platform.rst
    errno.rst
    ctypes.rst
@@ -11,6 +11,14 @@
 
 **Source code:** :source:`Lib/argparse.py`
 
+.. note::
+
+   While :mod:`argparse` is the recommended standard library module for
+   *implementing* command line applications, authors of third party
+   command line argument processing libraries may find that the
+   simpler :mod:`optparse` module serves as a better foundation for
+   that use case.
+
 --------------
 
 .. sidebar:: Tutorial

diff --git a/Doc/library/cmdlinelibs.rst b/Doc/library/cmdlinelibs.rst
@@ -0,0 +1,19 @@
+.. _cmdlinelibs:
+
+**************************************
+Command Line Implementation Libraries
+**************************************
+
+The modules described in this chapter provide interfaces that assist with
+implementing command line applications.  Here's an overview:
+
+.. toctree::
+   :maxdepth: 1
+
+   argparse.rst
+   optparse.rst
+   getopt.rst
+   getpass.rst
+   curses.rst
+   curses.ascii.rst
+   curses.panel.rst
diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst
@@ -7,11 +7,6 @@
 
 **Source code:** :source:`Lib/getopt.py`
 
-.. deprecated:: 3.13
-   The :mod:`getopt` module is :term:`soft deprecated` and will not be
-   developed further; development will continue with the :mod:`argparse`
-   module.
-
 .. note::
 
    The :mod:`getopt` module is a parser for command line options whose API is

diff --git a/Doc/library/index.rst b/Doc/library/index.rst
@@ -55,6 +55,7 @@ the `Python Package Index <https://pypi.org>`_.
    fileformats.rst
    crypto.rst
    allos.rst
+   cmdlinelibs.rst
    concurrency.rst
    ipc.rst
    netdata.rst

diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
@@ -10,10 +10,38 @@
 
 **Source code:** :source:`Lib/optparse.py`
 
-.. deprecated:: 3.2
-   The :mod:`optparse` module is :term:`soft deprecated` and will not be
-   developed further; development will continue with the :mod:`argparse`
-   module.
+.. note::
+
+   :mod:`argparse` (rather than this module) is the recommended standard
+   library module for implementing command line applications unless one
+   of the following caveats applies:
+
+   * the application requires additional control over the way options and
+     positional parameters are interleaved on the command line (including
+     the ability to disable the interleaving feature completely)
+   * the application requires additional control over the incremental parsing
+     of command line elements (while ``argparse`` does support this, the
+     exact way it will work in practice is sometimes unpredictable)
+   * the application requires additional control over the handling of options
+     which accept parameter values that may start with ``-`` (such as delegated
+     options to be passed to invoked subprocesses).
+
+   These ``argparse`` caveats also mean that :mod:`optparse` is likely to
+   provide a better foundation for library authors *writing* third party
+   command line argument processing libraries.
+
+.. seealso::
+
+    The :pypi:`"click" package <click>` is an ``optparse`` based third party
+    argument processing library which allows command line applications to be
+    developed as a set of appropriately decorated command implementation
+    functions.
+
+.. seealso::
+
+    The :pypi:`"Typer" package <click>` is a ``click`` based third party
+    argument processing library which allows the use of annotated Python
+    type hints to define an application's command line interface.
 
 --------------
 

diff --git a/Doc/library/superseded.rst b/Doc/library/superseded.rst
@@ -7,9 +7,5 @@ Superseded Modules
 The modules described in this chapter are deprecated or :term:`soft deprecated` and only kept for
 backwards compatibility. They have been superseded by other modules.
 
-
-.. toctree::
-   :maxdepth: 1
-
-   getopt.rst
-   optparse.rst
+With the removal of various obsolete modules through :pep:`594`, there are currently no modules
+in this category.
@@ -1648,6 +1648,18 @@ opcode
   (Contributed by Irit Katriel in :gh:`105481`.)
 
 
+optparse
+--------
+
+* This module is no longer considered :term:`soft deprecated`.
+  While :mod:`argparse` remains preferred for new projects that
+  aren't using a third party command line argument processing
+  library, there are aspects of the way ``argparse`` works that
+  means ``optparse`` may provide a better foundation for *writing*
+  argument processing libraries.
+  (Contributed by Alyssa Coghlan in :gh:`126225`.)
+
+
 pathlib
 -------
 
@@ -1787,14 +1799,6 @@ New Deprecations
     Check membership in :data:`~dis.hasarg` instead.
     (Contributed by Irit Katriel in :gh:`109319`.)
 
-* :mod:`getopt` and :mod:`optparse`:
-
-  * Both modules are now :term:`soft deprecated`,
-    with :mod:`argparse` preferred for new projects.
-    This is a new soft-deprecation for the :mod:`!getopt` module,
-    whereas the :mod:`!optparse` module was already *de facto* soft deprecated.
-    (Contributed by Victor Stinner in :gh:`106535`.)
-
 * :mod:`gettext`:
 
   * Deprecate non-integer numbers as arguments to functions and methods

diff --git a/Misc/NEWS.d/next/Library/2024-10-31-14-31-36.gh-issue-126225.vTxGXm.rst b/Misc/NEWS.d/next/Library/2024-10-31-14-31-36.gh-issue-126225.vTxGXm.rst
@@ -0,0 +1,6 @@
+:mod:`getopt` and :mod:`optparse` are no longer marked as deprecated.
+There are legitimate reasons to use one of these modules in preference to
+:mod:`argparse`, and none of these modules are at risk of being removed
+from the standard library. Of the three, ``argparse`` remains the
+recommended default choice, *unless* one of the concerns noted at the top of
+the module documentation applies.