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

95
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)
.. 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
----------------------
@ -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
@ -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')
@ -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
@ -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.
@ -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.
@ -784,9 +784,11 @@ 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
.. class:: BooleanOptionalAction
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``::
>>> import argparse
@ -798,8 +800,8 @@ is available in ``argparse`` and adds support for boolean actions such as
.. 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::
@ -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:
@ -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`::
@ -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')
@ -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
@ -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`.
@ -1327,21 +1329,24 @@ 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__`.
Action instances should be callable, so subclasses must override the
``__call__`` method, which should accept four parameters:
.. method:: __call__(parser, namespace, values, option_string=None)
* *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:
* *parser* - The :class:`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
@ -1355,10 +1360,12 @@ this API may be passed as the ``action`` parameter to
The ``option_string`` argument is optional, and will be absent if the action
is associated with a positional argument.
The ``__call__`` method may perform arbitrary actions, but will typically set
The :meth:`!__call__` method may perform arbitrary actions, but will typically set
attributes on the ``namespace`` based on ``dest`` and ``values``.
Action subclasses can define a ``format_usage`` method that takes no argument
.. 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.
@ -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`.
@ -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::
@ -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,
@ -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:
@ -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
@ -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
@ -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')
@ -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::
@ -1915,7 +1922,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::
@ -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.