Skip to content

Commit

Permalink
[3.12] pythongh-126071: Improve formatting of the argparse documentat…
Browse files Browse the repository at this point in the history 
…ion (pythonGH-126073)

* Use appropriate roles for ArgumentParser, Action, etc.
* Remove superfluous repeated links.
* Explicitly document signatures and add index entries for some methods
  and classes.
* Make it more clear that some parameters are keyword-only.
* Fix some minor errors.
(cherry picked from commit 2ab377a)

Co-authored-by: Serhiy Storchaka <[email protected]>
  • Loading branch information
@serhiy-storchaka
serhiy-storchaka committed Oct 30, 2024
1 parent 5df3c88 commit 183c2da
Showing 1 changed file with 69 additions and 62 deletions.
131 changes: 69 additions & 62 deletions Doc/library/argparse.rst
View file
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 @@ -100,7 +100,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``)

.. versionchanged:: 3.5
Expand Down Expand Up @@ -372,7 +372,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 @@ -503,9 +503,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 @@ -559,15 +559,15 @@ If the user would like to catch errors manually, the feature can be enabled by s
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])

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 @@ -733,22 +733,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 @@ -778,7 +780,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 @@ -1067,7 +1069,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 @@ -1120,7 +1122,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 @@ -1138,7 +1140,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 @@ -1242,7 +1244,7 @@ behavior::
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 @@ -1251,40 +1253,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 @@ -1297,7 +1304,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 @@ -1453,7 +1460,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 @@ -1511,9 +1518,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 @@ -1522,11 +1529,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 @@ -1542,7 +1549,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 @@ -1708,7 +1715,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 @@ -1751,7 +1758,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 @@ -1768,7 +1775,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 @@ -1810,7 +1817,7 @@ 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 @@ -2023,7 +2030,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

0 comments on commit 183c2da

Please sign in to comment.