Skip to content

gh-106535: Soft deprecate the getopt module #105735

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 8, 2023
Merged

gh-106535: Soft deprecate the getopt module #105735

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 13 additions & 8 deletions Doc/library/getopt.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,23 @@

**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
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.
Comment on lines +18 to 21
Copy link
Member

@CAM-Gerlach CAM-Gerlach Jun 14, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
designed to be familiar to users of the C :c:func:`!getopt` function.
Using the :mod:`argparse` module is encouraged instead,
as it offers better help and error messages while writing less code.

Tweaked this a bit to account to nudge users more toward argparse rather than just naming specific categories of users that should "consider using" it instead, as well as be more concise and less duplicative/repetitive.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note that I still think these changes (or perhaps a revised version) would be a good idea if we decide not to actually deprecate it, to make this clearer, more concise and a bit more of a nudge.


--------------

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
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.
Expand All @@ -33,11 +38,11 @@ exception:
be parsed, without the leading reference to the running program. Typically, this
means ``sys.argv[1:]``. *shortopts* is the string of option letters that the
script wants to recognize, with options that require an argument followed by a
colon (``':'``; i.e., the same format that Unix :c:func:`getopt` uses).
colon (``':'``; i.e., the same format that Unix :c:func:`!getopt` uses).

.. note::

Unlike GNU :c:func:`getopt`, after a non-option argument, all further
Unlike GNU :c:func:`!getopt`, after a non-option argument, all further
arguments are considered also non-options. This is similar to the way
non-GNU Unix systems work.

Expand Down Expand Up @@ -71,7 +76,7 @@ exception:
non-option argument is encountered.

If the first character of the option string is ``'+'``, or if the environment
variable :envvar:`POSIXLY_CORRECT` is set, then option processing stops as
variable :envvar:`!POSIXLY_CORRECT` is set, then option processing stops as
soon as a non-option argument is encountered.


Expand All @@ -81,9 +86,9 @@ exception:
an option requiring an argument is given none. The argument to the exception is
a string indicating the cause of the error. For long options, an argument given
to an option which does not require one will also cause this exception to be
raised. The attributes :attr:`msg` and :attr:`opt` give the error message and
raised. The attributes :attr:`!msg` and :attr:`!opt` give the error message and
related option; if there is no specific option to which the exception relates,
:attr:`opt` is an empty string.
:attr:`!opt` is an empty string.

.. XXX deprecated?
.. exception:: error
Expand Down