https://github.com/python/cpython/commit/b4040c41ac943edf1f242c0945e2fe50ce5dab4f
commit: b4040c41ac943edf1f242c0945e2fe50ce5dab4f
branch: 3.12
author: Serhiy Storchaka <[email protected]>
committer: serhiy-storchaka <[email protected]>
date: 2024-10-30T09:10:10Z
summary:
[3.12] gh-126071: Improve formatting of the argparse documentation (GH-126073)
(GH-126174)
* 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 2ab377a47c8290f8bf52c8ffb5d7fc4c45452611)
files:
M Doc/library/argparse.rst
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index f72bd14d56fe0d..b142135f6e635b 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -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
----------------------
@@ -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
@@ -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')
@@ -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
@@ -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.
@@ -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::
@@ -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:
@@ -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`::
@@ -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')
@@ -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
@@ -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`.
@@ -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
@@ -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`.
@@ -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::
@@ -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,
@@ -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:
@@ -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
@@ -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
@@ -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')
@@ -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::
@@ -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::
@@ -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.
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
