mirrors/cpython
mirrors/cpython
0
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2024-11-24 00:38:00 +01:00
Code Issues Releases Activity

gh-126071: Improve formatting of the argparse documentation (GH-126073)

Browse Source 
* 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.
This commit is contained in:
Serhiy Storchaka 2024-10-30 10:50:12 +02:00 committed by GitHub
parent 00e5ec0d35
commit 2ab377a47c
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 72 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

137
Doc/library/argparse.rst
View File

@ -50,8 +50,8 @@ the extracted data in a :class:`argparse.Namespace` object::
print(args.filename, args.count, args.verbose) print(args.filename, args.count, args.verbose)
.. note:: .. note::
If you're looking a guide about how to upgrade optparse code If you're looking for a guide about how to upgrade :mod:`optparse` code
to argparse, see :ref:`Upgrading Optparse Code <upgrading-optparse-code>`. to :mod:`!argparse`, see :ref:`Upgrading Optparse Code <upgrading-optparse-code>`.
ArgumentParser objects ArgumentParser objects
---------------------- ----------------------
@ -101,7 +101,7 @@ ArgumentParser objects
* allow_abbrev_ - Allows long options to be abbreviated if the * allow_abbrev_ - Allows long options to be abbreviated if the
abbreviation is unambiguous. (default: ``True``) 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``) error info when an error occurs. (default: ``True``)
* suggest_on_error_ - Enables suggestions for mistyped argument choices * suggest_on_error_ - Enables suggestions for mistyped argument choices
@ -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 Parsers that need to support different or additional prefix
characters, e.g. for options characters, e.g. for options
like ``+f`` or ``/foo``, may specify them using the ``prefix_chars=`` argument 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 = argparse.ArgumentParser(prog='PROG', prefix_chars='-+')
>>> parser.add_argument('+f') >>> parser.add_argument('+f')
@ -512,9 +512,9 @@ string was overridden.
add_help 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 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. 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 This can be achieved by passing ``False`` as the ``add_help=`` argument to
@ -589,15 +589,15 @@ are strings::
The add_argument() method 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], \ [const], [default], [type], [choices], [required], \
[help], [metavar], [dest], [deprecated]) [help], [metavar], [dest], [deprecated])
Define how a single command-line argument should be parsed. Each parameter Define how a single command-line argument should be parsed. Each parameter
has its own more detailed description below, but in short they are: 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`` * `name or flags`_ - Either a name or a list of option strings, e.g. ``'foo'``
or ``-f, --foo``. or ``'-f', '--foo'``.
* action_ - The basic type of action to be taken when this argument is * action_ - The basic type of action to be taken when this argument is
encountered at the command line. encountered at the command line.
@ -662,7 +662,7 @@ be positional::
usage: PROG [-h] [-f FOO] bar usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: 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 display names of arguments, simplifying the process without requiring
additional configuration. additional configuration.
As such, you do not need to specify the dest_ and metavar_ parameters. As such, you do not need to specify the dest_ and metavar_ parameters.
@ -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'``, Only actions that consume command-line arguments (e.g. ``'store'``,
``'append'`` or ``'extend'``) can be used with positional arguments. ``'append'`` or ``'extend'``) can be used with positional arguments.
You may also specify an arbitrary action by passing an Action subclass or .. class:: BooleanOptionalAction
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``::
>>> import argparse You may also specify an arbitrary action by passing an :class:`Action` subclass or
>>> parser = argparse.ArgumentParser() other object that implements the same interface. The :class:`!BooleanOptionalAction`
>>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction) is available in :mod:`!argparse` and adds support for boolean actions such as
>>> parser.parse_args(['--no-foo']) ``--foo`` and ``--no-foo``::
Namespace(foo=False)
.. 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`, The recommended way to create a custom action is to extend :class:`Action`,
overriding the ``__call__`` method and optionally the ``__init__`` and overriding the :meth:`!__call__` method and optionally the :meth:`!__init__` and
``format_usage`` methods. :meth:`!format_usage` methods.
An example of a custom action:: An example of a custom action::
@ -829,7 +831,7 @@ For more details, see :class:`Action`.
nargs 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 single action to be taken. The ``nargs`` keyword argument associates a
different number of command-line arguments with a single action. different number of command-line arguments with a single action.
See also :ref:`specifying-ambiguous-arguments`. The supported values are: See also :ref:`specifying-ambiguous-arguments`. The supported values are:
@ -1115,7 +1117,7 @@ many choices), just specify an explicit metavar_.
required 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. indicate *optional* arguments, which can always be omitted at the command line.
To make an option *required*, ``True`` can be specified for the ``required=`` To make an option *required*, ``True`` can be specified for the ``required=``
keyword argument to :meth:`~ArgumentParser.add_argument`:: keyword argument to :meth:`~ArgumentParser.add_argument`::
@ -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 As the help string supports %-formatting, if you want a literal ``%`` to appear
in the help string, you must escape it as ``%%``. 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``:: setting the ``help`` value to ``argparse.SUPPRESS``::
>>> parser = argparse.ArgumentParser(prog='frobble') >>> parser = argparse.ArgumentParser(prog='frobble')
@ -1186,7 +1188,7 @@ metavar
^^^^^^^ ^^^^^^^
When :class:`ArgumentParser` generates help messages, it needs some way to refer 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 value as the "name" of each object. By default, for positional argument
actions, the dest_ value is used directly, and for optional argument actions, actions, the dest_ value is used directly, and for optional argument actions,
the dest_ value is uppercased. So, a single positional argument with the dest_ value is uppercased. So, a single positional argument with
@ -1318,7 +1320,7 @@ printed to :data:`sys.stderr` when the argument is used::
Action classes 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 which processes arguments from the command-line. Any object which follows
this API may be passed as the ``action`` parameter to this API may be passed as the ``action`` parameter to
:meth:`~ArgumentParser.add_argument`. :meth:`~ArgumentParser.add_argument`.
@ -1327,40 +1329,45 @@ this API may be passed as the ``action`` parameter to
type=None, choices=None, required=False, help=None, \ type=None, choices=None, required=False, help=None, \
metavar=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 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` plus any keyword arguments passed to :meth:`ArgumentParser.add_argument`
except for the ``action`` itself. except for the ``action`` itself.
Instances of Action (or return value of any callable to the ``action`` Instances of :class:`!Action` (or return value of any callable to the
parameter) should have attributes "dest", "option_strings", "default", "type", ``action`` parameter) should have attributes :attr:`!dest`,
"required", "help", etc. defined. The easiest way to ensure these attributes :attr:`!option_strings`, :attr:`!default`, :attr:`!type`, :attr:`!required`,
are defined is to call ``Action.__init__``. :attr:`!help`, etc. defined. The easiest way to ensure these attributes
are defined is to call :meth:`!Action.__init__`.
Action instances should be callable, so subclasses must override the .. method:: __call__(parser, namespace, values, option_string=None)
``__call__`` method, which should accept four parameters:
* *parser* - The ArgumentParser object which contains this action. :class:`!Action` instances should be callable, so subclasses must override the
:meth:`!__call__` method, which should accept four parameters:
* *namespace* - The :class:`Namespace` object that will be returned by * *parser* - The :class:`ArgumentParser` object which contains this action.
: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 * *namespace* - The :class:`Namespace` object that will be returned by
applied. Type conversions are specified with the type_ keyword argument to :meth:`~ArgumentParser.parse_args`. Most actions add an attribute to this
:meth:`~ArgumentParser.add_argument`. object using :func:`setattr`.
* *option_string* - The option string that was used to invoke this action. * *values* - The associated command-line arguments, with any type conversions
The ``option_string`` argument is optional, and will be absent if the action applied. Type conversions are specified with the type_ keyword argument to
is associated with a positional argument. :meth:`~ArgumentParser.add_argument`.
The ``__call__`` method may perform arbitrary actions, but will typically set * *option_string* - The option string that was used to invoke this action.
attributes on the ``namespace`` based on ``dest`` and ``values``. The ``option_string`` argument is optional, and will be absent if the action
is associated with a positional argument.
Action subclasses can define a ``format_usage`` method that takes no argument The :meth:`!__call__` method may perform arbitrary actions, but will typically set
and return a string which will be used when printing the usage of the program. attributes on the ``namespace`` based on ``dest`` and ``values``.
If such method is not provided, a sensible default will be used.
.. method:: format_usage()
: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 The parse_args() method
@ -1373,7 +1380,7 @@ The parse_args() method
Previous calls to :meth:`add_argument` determine exactly what objects are Previous calls to :meth:`add_argument` determine exactly what objects are
created and how they are assigned. See the documentation for 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 * args_ - List of strings to parse. The default is taken from
:data:`sys.argv`. :data:`sys.argv`.
@ -1529,7 +1536,7 @@ This feature can be disabled by setting :ref:`allow_abbrev` to ``False``.
Beyond ``sys.argv`` 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 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 :meth:`~ArgumentParser.parse_args`. This is useful for testing at the
interactive prompt:: interactive prompt::
@ -1587,9 +1594,9 @@ Other utilities
Sub-commands Sub-commands
^^^^^^^^^^^^ ^^^^^^^^^^^^
.. method:: ArgumentParser.add_subparsers([title], [description], [prog], \ .. method:: ArgumentParser.add_subparsers(*, [title], [description], [prog], \
[parser_class], [action], \ [parser_class], [action], \
[option_strings], [dest], [required], \ [dest], [required], \
[help], [metavar]) [help], [metavar])
Many programs split up their functionality into a number of subcommands, Many programs split up their functionality into a number of subcommands,
@ -1598,11 +1605,11 @@ Sub-commands
this way can be a particularly good idea when a program performs several this way can be a particularly good idea when a program performs several
different functions which require different kinds of command-line arguments. different functions which require different kinds of command-line arguments.
:class:`ArgumentParser` supports the creation of such subcommands with the :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 called with no arguments and returns a special action object. This object
has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a
command name and any :class:`ArgumentParser` constructor arguments, and command name and any :class:`!ArgumentParser` constructor arguments, and
returns an :class:`ArgumentParser` object that can be modified as usual. returns an :class:`!ArgumentParser` object that can be modified as usual.
Description of parameters: Description of parameters:
@ -1618,7 +1625,7 @@ Sub-commands
subparser argument subparser argument
* *parser_class* - class which will be used to create sub-parser instances, by * *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 * action_ - the basic type of action to be taken when this argument is
encountered at the command line encountered at the command line
@ -1799,7 +1806,7 @@ Sub-commands
Namespace(subparser_name='2', y='frobble') Namespace(subparser_name='2', y='frobble')
.. versionchanged:: 3.7 .. versionchanged:: 3.7
New *required* keyword argument. New *required* keyword-only parameter.
FileType objects FileType objects
@ -1852,7 +1859,7 @@ Argument groups
"positional arguments" and "options" when displaying help "positional arguments" and "options" when displaying help
messages. When there is a better conceptual grouping of arguments than this messages. When there is a better conceptual grouping of arguments than this
default one, appropriate groups can be created using the 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) >>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
>>> group = parser.add_argument_group('group') >>> group = parser.add_argument_group('group')
@ -1869,7 +1876,7 @@ Argument groups
has an :meth:`~ArgumentParser.add_argument` method just like a regular has an :meth:`~ArgumentParser.add_argument` method just like a regular
:class:`ArgumentParser`. When an argument is added to the group, the parser :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 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 accepts *title* and *description* arguments which can be used to
customize this display:: customize this display::
@ -1906,8 +1913,8 @@ Argument groups
will be removed in the future. will be removed in the future.
.. deprecated:: 3.14 .. deprecated:: 3.14
Passing prefix_chars_ to :meth:`add_argument_group` Passing prefix_chars_ to :meth:`add_argument_group`
is now deprecated. is now deprecated.
Mutual exclusion Mutual exclusion
@ -1915,7 +1922,7 @@ Mutual exclusion
.. method:: ArgumentParser.add_mutually_exclusive_group(required=False) .. 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 one of the arguments in the mutually exclusive group was present on the
command line:: command line::
@ -2128,7 +2135,7 @@ Intermixed parsing
and :meth:`~ArgumentParser.parse_known_intermixed_args` methods and :meth:`~ArgumentParser.parse_known_intermixed_args` methods
support this parsing style. 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, exceptions if unsupported features are used. In particular, subparsers,
and mutually exclusive groups that include both and mutually exclusive groups that include both
optionals and positionals are not supported. optionals and positionals are not supported.