From c52e8cd100b7eeb540db6c55bfb528b38084e3f6 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 28 Oct 2024 12:19:07 +0200 Subject: [PATCH 1/2] gh-126071: Improve formatting of the argparse documentation * 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. --- Doc/library/argparse.rst | 137 ++++++++++++++++++++------------------- 1 file changed, 72 insertions(+), 65 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 940698218534e0..f13c34dfb71396 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 `. + If you're looking a guide about how to upgrade :mod:`optparse` code + to :mod:`!argparse`, see :ref:`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,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'``, ``'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:: @@ -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,40 +1329,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 @@ -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:: @@ -1906,8 +1913,8 @@ Argument groups will be removed in the future. .. deprecated:: 3.14 - Passing prefix_chars_ to :meth:`add_argument_group` - is now deprecated. + Passing prefix_chars_ to :meth:`add_argument_group` + is now deprecated. Mutual exclusion @@ -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. From 2cbaf6f1fe0d50ce95cd1e9f8abc6bae520e67eb Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 30 Oct 2024 10:02:21 +0200 Subject: [PATCH 2/2] Update Doc/library/argparse.rst Co-authored-by: Carol Willing --- Doc/library/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index f13c34dfb71396..7638798ca2552f 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -50,7 +50,7 @@ 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 :mod:`optparse` code + If you're looking for a guide about how to upgrade :mod:`optparse` code to :mod:`!argparse`, see :ref:`Upgrading Optparse Code `. ArgumentParser objects