mirror of
https://github.com/python/cpython.git
synced 2024-11-24 00:38:00 +01:00
* 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
GitHub
parent
00e5ec0d35
commit
2ab377a47c
@ -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,10 +784,12 @@ 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
|
||||
|
||||
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
|
||||
>>> parser = argparse.ArgumentParser()
|
||||
@ -795,11 +797,11 @@ is available in ``argparse`` and adds support for boolean actions such as
|
||||
>>> parser.parse_args(['--no-foo'])
|
||||
Namespace(foo=False)
|
||||
|
||||
.. versionadded:: 3.9
|
||||
.. 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user