Skip to content

gh-126071: Improve formatting of the argparse documentation #126073

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 2 commits into from
Oct 30, 2024
Merged

gh-126071: Improve formatting of the argparse documentation #126073

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c52e8cd
gh-126071: Improve formatting of the argparse documentation
serhiy-storchaka Oct 28, 2024
2cbaf6f
Update Doc/library/argparse.rst
serhiy-storchaka Oct 30, 2024
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
137 changes: 72 additions & 65 deletions Doc/library/argparse.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,8 +50,8 @@ the extracted data in a :class:`argparse.Namespace` object::
print(args.filename, args.count, args.verbose)

.. note::
If you're looking a guide about how to upgrade optparse code
to argparse, see :ref:`Upgrading Optparse Code <upgrading-optparse-code>`.
If you're looking for a guide about how to upgrade :mod:`optparse` code
to :mod:`!argparse`, see :ref:`Upgrading Optparse Code <upgrading-optparse-code>`.

ArgumentParser objects
----------------------
Expand Down Expand Up @@ -101,7 +101,7 @@ ArgumentParser objects
* allow_abbrev_ - Allows long options to be abbreviated if the
abbreviation is unambiguous. (default: ``True``)

* exit_on_error_ - Determines whether or not ArgumentParser exits with
* exit_on_error_ - Determines whether or not :class:`!ArgumentParser` exits with
error info when an error occurs. (default: ``True``)

* suggest_on_error_ - Enables suggestions for mistyped argument choices
Expand Down Expand Up @@ -381,7 +381,7 @@ Most command-line options will use ``-`` as the prefix, e.g. ``-f/--foo``.
Parsers that need to support different or additional prefix
characters, e.g. for options
like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument
to the ArgumentParser constructor::
to the :class:`ArgumentParser` constructor::

>>> parser = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f')
Expand Down Expand Up @@ -512,9 +512,9 @@ string was overridden.
add_help
^^^^^^^^

By default, ArgumentParser objects add an option which simply displays
By default, :class:`ArgumentParser` objects add an option which simply displays
the parser's help message. If ``-h`` or ``--help`` is supplied at the command
line, the ArgumentParser help will be printed.
line, the :class:`!ArgumentParser` help will be printed.

Occasionally, it may be useful to disable the addition of this help option.
This can be achieved by passing ``False`` as the ``add_help=`` argument to
Expand Down Expand Up @@ -589,15 +589,15 @@ are strings::
The add_argument() method
-------------------------

.. method:: ArgumentParser.add_argument(name or flags..., [action], [nargs], \
.. method:: ArgumentParser.add_argument(name or flags..., *, [action], [nargs], \
[const], [default], [type], [choices], [required], \
[help], [metavar], [dest], [deprecated])

Define how a single command-line argument should be parsed. Each parameter
has its own more detailed description below, but in short they are:

* `name or flags`_ - Either a name or a list of option strings, e.g. ``foo``
or ``-f, --foo``.
* `name or flags`_ - Either a name or a list of option strings, e.g. ``'foo'``
or ``'-f', '--foo'``.

* action_ - The basic type of action to be taken when this argument is
encountered at the command line.
Expand Down Expand Up @@ -662,7 +662,7 @@ be positional::
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar

By default, argparse automatically handles the internal naming and
By default, :mod:`!argparse` automatically handles the internal naming and
display names of arguments, simplifying the process without requiring
additional configuration.
As such, you do not need to specify the dest_ and metavar_ parameters.
Expand Down Expand Up @@ -784,22 +784,24 @@ how the command-line arguments should be handled. The supplied actions are:
Only actions that consume command-line arguments (e.g. ``'store'``,
``'append'`` or ``'extend'``) can be used with positional arguments.

You may also specify an arbitrary action by passing an Action subclass or
other object that implements the same interface. The ``BooleanOptionalAction``
is available in ``argparse`` and adds support for boolean actions such as
``--foo`` and ``--no-foo``::
.. class:: BooleanOptionalAction

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)
You may also specify an arbitrary action by passing an :class:`Action` subclass or
other object that implements the same interface. The :class:`!BooleanOptionalAction`
is available in :mod:`!argparse` and adds support for boolean actions such as
``--foo`` and ``--no-foo``::

.. versionadded:: 3.9
>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction)
>>> parser.parse_args(['--no-foo'])
Namespace(foo=False)

.. versionadded:: 3.9

The recommended way to create a custom action is to extend :class:`Action`,
overriding the ``__call__`` method and optionally the ``__init__`` and
``format_usage`` methods.
overriding the :meth:`!__call__` method and optionally the :meth:`!__init__` and
:meth:`!format_usage` methods.

An example of a custom action::

Expand Down Expand Up @@ -829,7 +831,7 @@ For more details, see :class:`Action`.
nargs
^^^^^

ArgumentParser objects usually associate a single command-line argument with a
:class:`ArgumentParser` objects usually associate a single command-line argument with a
single action to be taken. The ``nargs`` keyword argument associates a
different number of command-line arguments with a single action.
See also :ref:`specifying-ambiguous-arguments`. The supported values are:
Expand Down Expand Up @@ -1115,7 +1117,7 @@ many choices), just specify an explicit metavar_.
required
^^^^^^^^

In general, the :mod:`argparse` module assumes that flags like ``-f`` and ``--bar``
In general, the :mod:`!argparse` module assumes that flags like ``-f`` and ``--bar``
indicate *optional* arguments, which can always be omitted at the command line.
To make an option *required*, ``True`` can be specified for the ``required=``
keyword argument to :meth:`~ArgumentParser.add_argument`::
Expand Down Expand Up @@ -1168,7 +1170,7 @@ specifiers include the program name, ``%(prog)s`` and most keyword arguments to
As the help string supports %-formatting, if you want a literal ``%`` to appear
in the help string, you must escape it as ``%%``.

:mod:`argparse` supports silencing the help entry for certain options, by
:mod:`!argparse` supports silencing the help entry for certain options, by
setting the ``help`` value to ``argparse.SUPPRESS``::

>>> parser = argparse.ArgumentParser(prog='frobble')
Expand All @@ -1186,7 +1188,7 @@ metavar
^^^^^^^

When :class:`ArgumentParser` generates help messages, it needs some way to refer
to each expected argument. By default, ArgumentParser objects use the dest_
to each expected argument. By default, :class:`!ArgumentParser` objects use the dest_
value as the "name" of each object. By default, for positional argument
actions, the dest_ value is used directly, and for optional argument actions,
the dest_ value is uppercased. So, a single positional argument with
Expand Down Expand Up @@ -1318,7 +1320,7 @@ printed to :data:`sys.stderr` when the argument is used::
Action classes
^^^^^^^^^^^^^^

Action classes implement the Action API, a callable which returns a callable
:class:`!Action` classes implement the Action API, a callable which returns a callable
which processes arguments from the command-line. Any object which follows
this API may be passed as the ``action`` parameter to
:meth:`~ArgumentParser.add_argument`.
Expand All @@ -1327,40 +1329,45 @@ this API may be passed as the ``action`` parameter to
type=None, choices=None, required=False, help=None, \
metavar=None)

Action objects are used by an ArgumentParser to represent the information
:class:`!Action` objects are used by an :class:`ArgumentParser` to represent the information
needed to parse a single argument from one or more strings from the
command line. The Action class must accept the two positional arguments
command line. The :class:`!Action` class must accept the two positional arguments
plus any keyword arguments passed to :meth:`ArgumentParser.add_argument`
except for the ``action`` itself.

Instances of Action (or return value of any callable to the ``action``
parameter) should have attributes "dest", "option_strings", "default", "type",
"required", "help", etc. defined. The easiest way to ensure these attributes
are defined is to call ``Action.__init__``.
Instances of :class:`!Action` (or return value of any callable to the
``action`` parameter) should have attributes :attr:`!dest`,
:attr:`!option_strings`, :attr:`!default`, :attr:`!type`, :attr:`!required`,
:attr:`!help`, etc. defined. The easiest way to ensure these attributes
are defined is to call :meth:`!Action.__init__`.

.. method:: __call__(parser, namespace, values, option_string=None)

:class:`!Action` instances should be callable, so subclasses must override the
:meth:`!__call__` method, which should accept four parameters:

Action instances should be callable, so subclasses must override the
``__call__`` method, which should accept four parameters:
* *parser* - The :class:`ArgumentParser` object which contains this action.

* *parser* - The ArgumentParser object which contains this action.
* *namespace* - The :class:`Namespace` object that will be returned by
:meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this
object using :func:`setattr`.

* *namespace* - The :class:`Namespace` object that will be returned by
:meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this
object using :func:`setattr`.
* *values* - The associated command-line arguments, with any type conversions
applied. Type conversions are specified with the type_ keyword argument to
:meth:`~ArgumentParser.add_argument`.

* *values* - The associated command-line arguments, with any type conversions
applied. Type conversions are specified with the type_ keyword argument to
:meth:`~ArgumentParser.add_argument`.
* *option_string* - The option string that was used to invoke this action.
The ``option_string`` argument is optional, and will be absent if the action
is associated with a positional argument.

* *option_string* - The option string that was used to invoke this action.
The ``option_string`` argument is optional, and will be absent if the action
is associated with a positional argument.
The :meth:`!__call__` method may perform arbitrary actions, but will typically set
attributes on the ``namespace`` based on ``dest`` and ``values``.

The ``__call__`` method may perform arbitrary actions, but will typically set
attributes on the ``namespace`` based on ``dest`` and ``values``.
.. method:: format_usage()

Action subclasses can define a ``format_usage`` method that takes no argument
and return a string which will be used when printing the usage of the program.
If such method is not provided, a sensible default will be used.
:class:`!Action` subclasses can define a :meth:`!format_usage` method that takes no argument
and return a string which will be used when printing the usage of the program.
If such method is not provided, a sensible default will be used.


The parse_args() method
Expand All @@ -1373,7 +1380,7 @@ The parse_args() method

Previous calls to :meth:`add_argument` determine exactly what objects are
created and how they are assigned. See the documentation for
:meth:`add_argument` for details.
:meth:`!add_argument` for details.

* args_ - List of strings to parse. The default is taken from
:data:`sys.argv`.
Expand Down Expand Up @@ -1529,7 +1536,7 @@ This feature can be disabled by setting :ref:`allow_abbrev` to ``False``.
Beyond ``sys.argv``
^^^^^^^^^^^^^^^^^^^

Sometimes it may be useful to have an ArgumentParser parse arguments other than those
Sometimes it may be useful to have an :class:`ArgumentParser` parse arguments other than those
of :data:`sys.argv`. This can be accomplished by passing a list of strings to
:meth:`~ArgumentParser.parse_args`. This is useful for testing at the
interactive prompt::
Expand Down Expand Up @@ -1587,9 +1594,9 @@ Other utilities
Sub-commands
^^^^^^^^^^^^

.. method:: ArgumentParser.add_subparsers([title], [description], [prog], \
.. method:: ArgumentParser.add_subparsers(*, [title], [description], [prog], \
[parser_class], [action], \
[option_strings], [dest], [required], \
[dest], [required], \
[help], [metavar])

Many programs split up their functionality into a number of subcommands,
Expand All @@ -1598,11 +1605,11 @@ Sub-commands
this way can be a particularly good idea when a program performs several
different functions which require different kinds of command-line arguments.
:class:`ArgumentParser` supports the creation of such subcommands with the
:meth:`add_subparsers` method. The :meth:`add_subparsers` method is normally
:meth:`!add_subparsers` method. The :meth:`!add_subparsers` method is normally
called with no arguments and returns a special action object. This object
has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a
command name and any :class:`ArgumentParser` constructor arguments, and
returns an :class:`ArgumentParser` object that can be modified as usual.
command name and any :class:`!ArgumentParser` constructor arguments, and
returns an :class:`!ArgumentParser` object that can be modified as usual.

Description of parameters:

Expand All @@ -1618,7 +1625,7 @@ Sub-commands
subparser argument

* *parser_class* - class which will be used to create sub-parser instances, by
default the class of the current parser (e.g. ArgumentParser)
default the class of the current parser (e.g. :class:`ArgumentParser`)

* action_ - the basic type of action to be taken when this argument is
encountered at the command line
Expand Down Expand Up @@ -1799,7 +1806,7 @@ Sub-commands
Namespace(subparser_name='2', y='frobble')

.. versionchanged:: 3.7
New *required* keyword argument.
New *required* keyword-only parameter.


FileType objects
Expand Down Expand Up @@ -1852,7 +1859,7 @@ Argument groups
"positional arguments" and "options" when displaying help
messages. When there is a better conceptual grouping of arguments than this
default one, appropriate groups can be created using the
:meth:`add_argument_group` method::
:meth:`!add_argument_group` method::

>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group')
Expand All @@ -1869,7 +1876,7 @@ Argument groups
has an :meth:`~ArgumentParser.add_argument` method just like a regular
:class:`ArgumentParser`. When an argument is added to the group, the parser
treats it just like a normal argument, but displays the argument in a
separate group for help messages. The :meth:`add_argument_group` method
separate group for help messages. The :meth:`!add_argument_group` method
accepts *title* and *description* arguments which can be used to
customize this display::

Expand Down Expand Up @@ -1906,16 +1913,16 @@ Argument groups
will be removed in the future.

.. deprecated:: 3.14
Passing prefix_chars_ to :meth:`add_argument_group`
is now deprecated.
Passing prefix_chars_ to :meth:`add_argument_group`
is now deprecated.


Mutual exclusion
^^^^^^^^^^^^^^^^

.. method:: ArgumentParser.add_mutually_exclusive_group(required=False)

Create a mutually exclusive group. :mod:`argparse` will make sure that only
Create a mutually exclusive group. :mod:`!argparse` will make sure that only
one of the arguments in the mutually exclusive group was present on the
command line::

Expand Down Expand Up @@ -2128,7 +2135,7 @@ Intermixed parsing
and :meth:`~ArgumentParser.parse_known_intermixed_args` methods
support this parsing style.

These parsers do not support all the argparse features, and will raise
These parsers do not support all the :mod:`!argparse` features, and will raise
exceptions if unsupported features are used. In particular, subparsers,
and mutually exclusive groups that include both
optionals and positionals are not supported.
Expand Down
Loading