From 507bdfca832f96866ac1efe41b20d8766a896c1b Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 30 Oct 2024 16:57:39 +0200 Subject: [PATCH] gh-126180: Undeprecate the optparse and getopt modules --- Doc/library/allos.rst | 2 + Doc/library/argparse.rst | 6 +++ Doc/library/getopt.rst | 44 +++++++++++-------- Doc/library/optparse.rst | 10 +---- Doc/library/superseded.rst | 2 - Doc/whatsnew/3.13.rst | 8 ---- Doc/whatsnew/3.14.rst | 2 + ...-10-30-16-56-54.gh-issue-126180.CQ-bA4.rst | 1 + 8 files changed, 37 insertions(+), 38 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2024-10-30-16-56-54.gh-issue-126180.CQ-bA4.rst diff --git a/Doc/library/allos.rst b/Doc/library/allos.rst index 0223c1054ea5d86..a7d88025ac546f6 100644 --- a/Doc/library/allos.rst +++ b/Doc/library/allos.rst @@ -15,7 +15,9 @@ but they are available on most other systems as well. Here's an overview: os.rst io.rst time.rst + optparse.rst argparse.rst + getopt.rst logging.rst logging.config.rst logging.handlers.rst diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 940698218534e06..9a507701bf3331f 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -25,6 +25,12 @@ will figure out how to parse those out of :data:`sys.argv`. The :mod:`!argparse module also automatically generates help and usage messages. The module will also issue errors when users give the program invalid arguments. +.. note:: + Fine details of the command-line interface built with using the + :mod:`!argparse` module differ from common Unix and Linux programs. + If you want to implement more compatible interface, consider using + the :mod:`optparse` or :mod:`getopt` modules. + The :mod:`!argparse` module's support for command-line interfaces is built around an instance of :class:`argparse.ArgumentParser`. It is a container for argument specifications and has options that apply to the parser as whole:: diff --git a/Doc/library/getopt.rst b/Doc/library/getopt.rst index d43d3250732306b..42ab153bb2cc8b4 100644 --- a/Doc/library/getopt.rst +++ b/Doc/library/getopt.rst @@ -7,27 +7,18 @@ **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 - designed to be familiar to users of the C :c:func:`!getopt` function. Users who - are unfamiliar with the C :c:func:`!getopt` function or who would like to write - less code and get better help and error messages should consider using the - :mod:`argparse` module instead. - --------------- - This module helps scripts to parse the command line arguments in ``sys.argv``. It supports the same conventions as the Unix :c:func:`!getopt` function (including the special meanings of arguments of the form '``-``' and '``--``'). Long options similar to those supported by GNU software may be used as well via an optional third argument. +The :mod:`getopt` module is a parser for command line options whose API is +designed to be familiar to users of the C :c:func:`!getopt` function. Users who +are unfamiliar with the C :c:func:`!getopt` function or who would like to write +less code and get better help and error messages should consider using the +:mod:`optparse` or :mod:`argparse` module instead. + This module provides two functions and an exception: @@ -144,13 +135,25 @@ In a script, typical usage is something like this:: output = a else: assert False, "unhandled option" - # ... + process(args, output=output, verbose=verbose) if __name__ == "__main__": main() Note that an equivalent command line interface could be produced with less code -and more informative help and error messages by using the :mod:`argparse` module:: +and more informative help and error messages by using the :mod:`optparse` module:: + + import optparse + + if __name__ == '__main__': + parser = optparse.OptionParser() + parser.add_option('-o', '--output') + parser.add_option('-v', dest='verbose', action='store_true') + opts, args = parser.parse_args() + process(args, output=opts.output, verbose=opts.verbose) + +A roughtly equivalent command line interface could also be produced by using +the :mod:`argparse` module:: import argparse @@ -158,12 +161,15 @@ and more informative help and error messages by using the :mod:`argparse` module parser = argparse.ArgumentParser() parser.add_argument('-o', '--output') parser.add_argument('-v', dest='verbose', action='store_true') + parser.add_argument('rest', nargs='*') args = parser.parse_args() - # ... do something with args.output ... - # ... do something with args.verbose .. + process(args.rest, output=args.output, verbose=args.verbose) .. seealso:: + Module :mod:`optparse` + More object-oriented command line option parsing. + Module :mod:`argparse` Alternative command line option and argument parsing library. diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index 74a49a8fb33666d..e0f9a4af5ec0849 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -3,22 +3,14 @@ .. module:: optparse :synopsis: Command-line option parsing library. - :deprecated: .. moduleauthor:: Greg Ward .. sectionauthor:: Greg Ward **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. - --------------- - :mod:`optparse` is a more convenient, flexible, and powerful library for parsing -command-line options than the old :mod:`getopt` module. :mod:`optparse` uses a +command-line options than the simple :mod:`getopt` module. :mod:`optparse` uses a more declarative style of command-line parsing: you create an instance of :class:`OptionParser`, populate it with options, and parse the command line. :mod:`optparse` allows users to specify options in the conventional diff --git a/Doc/library/superseded.rst b/Doc/library/superseded.rst index 17bfa66f0433022..046207011daee13 100644 --- a/Doc/library/superseded.rst +++ b/Doc/library/superseded.rst @@ -11,5 +11,3 @@ backwards compatibility. They have been superseded by other modules. .. toctree:: :maxdepth: 1 - getopt.rst - optparse.rst diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst index de4c7fd4c0486ba..4e045a79f46120b 100644 --- a/Doc/whatsnew/3.13.rst +++ b/Doc/whatsnew/3.13.rst @@ -1787,14 +1787,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/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index a6f595ccf08bf47..6cb637b16fc0b84 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -463,6 +463,8 @@ asyncio Deprecated ========== +The :mod:`optparse` and :mod:`getopt` modules are no longer considered deprecated. + * :mod:`argparse`: Passing the undocumented keyword argument *prefix_chars* to :meth:`~argparse.ArgumentParser.add_argument_group` is now diff --git a/Misc/NEWS.d/next/Library/2024-10-30-16-56-54.gh-issue-126180.CQ-bA4.rst b/Misc/NEWS.d/next/Library/2024-10-30-16-56-54.gh-issue-126180.CQ-bA4.rst new file mode 100644 index 000000000000000..575e3bdbe5c2a36 --- /dev/null +++ b/Misc/NEWS.d/next/Library/2024-10-30-16-56-54.gh-issue-126180.CQ-bA4.rst @@ -0,0 +1 @@ +The :mod:`optparse` and :mod:`getopt` modules are no longer deprecated.