From 29283f345b358bc0a21b7ce434c4ddb8d771e20a Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 5 Apr 2023 22:09:26 +0300 Subject: [PATCH 1/7] Fix Sphinx warnings in argparse module --- Doc/howto/argparse.rst | 14 ++++++++------ Doc/library/argparse.rst | 22 ++++++++++++++++++---- Doc/library/optparse.rst | 28 ++++++++++++++++++++++++++++ Doc/tools/.nitignore | 2 -- 4 files changed, 54 insertions(+), 12 deletions(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index f682587488a227..4c3913d6ba87f2 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -6,13 +6,15 @@ Argparse Tutorial .. _argparse-tutorial: +.. currentmodule:: argparse + This tutorial is intended to be a gentle introduction to :mod:`argparse`, the recommended command-line parsing module in the Python standard library. .. note:: There are two other modules that fulfill the same task, namely - :mod:`getopt` (an equivalent for :c:func:`getopt` from the C + :mod:`getopt` (an equivalent for ``getopt()`` from the C language) and the deprecated :mod:`optparse`. Note also that :mod:`argparse` is based on :mod:`optparse`, and therefore very similar in terms of usage. @@ -137,13 +139,13 @@ And running the code: Here is what's happening: -* We've added the :meth:`add_argument` method, which is what we use to specify +* We've added the :meth:`~ArgumentParser.add_argument` method, which is what we use to specify which command-line options the program is willing to accept. In this case, I've named it ``echo`` so that it's in line with its function. * Calling our program now requires us to specify an option. -* The :meth:`parse_args` method actually returns some data from the +* The :meth:`~ArgumentParser.parse_args` method actually returns some data from the options specified, in this case, ``echo``. * The variable is some form of 'magic' that :mod:`argparse` performs for free @@ -256,7 +258,7 @@ Here is what is happening: * To show that the option is actually optional, there is no error when running the program without it. Note that by default, if an optional argument isn't - used, the relevant variable, in this case :attr:`args.verbosity`, is + used, the relevant variable, in this case :attr:`!args.verbosity`, is given ``None`` as a value, which is the reason it fails the truth test of the :keyword:`if` statement. @@ -299,7 +301,7 @@ Here is what is happening: We even changed the name of the option to match that idea. Note that we now specify a new keyword, ``action``, and give it the value ``"store_true"``. This means that, if the option is specified, - assign the value ``True`` to :data:`args.verbose`. + assign the value ``True`` to :data:`!args.verbose`. Not specifying it implies ``False``. * It complains when you specify a value, in true spirit of what flags @@ -698,7 +700,7 @@ Conflicting options So far, we have been working with two methods of an :class:`argparse.ArgumentParser` instance. Let's introduce a third one, -:meth:`add_mutually_exclusive_group`. It allows for us to specify options that +:meth:`~ArgumentParser.add_mutually_exclusive_group`. It allows for us to specify options that conflict with each other. Let's also change the rest of the program so that the new functionality makes more sense: we'll introduce the ``--quiet`` option, diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index ee68ac58d3de75..409c91e5a22313 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -585,7 +585,7 @@ arguments will never be treated as file references. .. versionchanged:: 3.12 :class:`ArgumentParser` changed encoding and errors to read arguments files - from default (e.g. :func:`locale.getpreferredencoding(False)` and + from default (e.g. :func:`locale.getpreferredencoding(False) ` and ``"strict"``) to :term:`filesystem encoding and error handler`. Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows. @@ -1191,7 +1191,7 @@ done downstream after the arguments are parsed. For example, JSON or YAML conversions have complex error cases that require better reporting than can be given by the ``type`` keyword. A :exc:`~json.JSONDecodeError` would not be well formatted and a -:exc:`FileNotFound` exception would not be handled at all. +:exc:`FileNotFoundError` exception would not be handled at all. Even :class:`~argparse.FileType` has its limitations for use with the ``type`` keyword. If one argument uses *FileType* and then a subsequent argument fails, @@ -1445,7 +1445,7 @@ Action classes 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:`add_argument`. +:meth:`~ArgumentParser.add_argument`. .. class:: Action(option_strings, dest, nargs=None, const=None, default=None, \ type=None, choices=None, required=False, help=None, \ @@ -2157,7 +2157,7 @@ the populated namespace and the list of remaining argument strings. .. warning:: :ref:`Prefix matching ` rules apply to - :meth:`parse_known_args`. The parser may consume an option even if it's just + :meth:`~ArgumentParser.parse_known_args`. The parser may consume an option even if it's just a prefix of one of its known options, instead of leaving it in the remaining arguments list. @@ -2295,3 +2295,17 @@ A partial upgrade path from :mod:`optparse` to :mod:`argparse`: * Replace the OptionParser constructor ``version`` argument with a call to ``parser.add_argument('--version', action='version', version='')``. + +Exceptions +---------- + +.. exception:: ArgumentError + + An error from creating or using an argument (optional or positional). + + The string value of this exception is the message, augmented with + information about the argument that caused it. + +.. exception:: ArgumentTypeError + + An error from trying to convert a command line string to a type. diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index 3e29fed0175e04..2966b5a303851d 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -952,6 +952,8 @@ The canonical way to create an :class:`Option` instance is with the you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option attributes; see :ref:`optparse-standard-option-actions`.) +.. class:: Values + As you can see, most actions involve storing or updating a value somewhere. :mod:`optparse` always creates a special object for this, conventionally called ``options`` (it happens to be an instance of :class:`optparse.Values`). Option @@ -991,6 +993,8 @@ one that makes sense for *all* options. Option attributes ^^^^^^^^^^^^^^^^^ +.. class:: Option + The following option attributes may be passed as keyword arguments to :meth:`OptionParser.add_option`. If you pass an option attribute that is not relevant to a particular option, or fail to pass a required option attribute, @@ -2035,3 +2039,27 @@ Features of note: about setting a default value for the option destinations in question; they can just leave the default as ``None`` and :meth:`ensure_value` will take care of getting it right when it's needed. + +Exceptions +---------- + +.. exception:: OptionError + + Raised if an :class:`Option` instance is created with invalid or + inconsistent arguments. + +.. exception:: OptionConflictError + + Raised if conflicting options are added to an :class:`OptionParser`. + +.. exception:: OptionValueError + + Raised if an invalid option value is encountered on the command line. + +.. exception:: BadOptionError + + Raised if an invalid option is seen on the command line. + +.. exception:: AmbiguousOptionError + + Raised if an ambiguous option is seen on the command line. diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index f6fe8df97810ff..e77da1c12eba1c 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -59,7 +59,6 @@ Doc/faq/gui.rst Doc/faq/library.rst Doc/faq/programming.rst Doc/glossary.rst -Doc/howto/argparse.rst Doc/howto/curses.rst Doc/howto/descriptor.rst Doc/howto/enum.rst @@ -78,7 +77,6 @@ Doc/library/__future__.rst Doc/library/_thread.rst Doc/library/abc.rst Doc/library/aifc.rst -Doc/library/argparse.rst Doc/library/ast.rst Doc/library/asyncio-dev.rst Doc/library/asyncio-eventloop.rst From c2c299786d9938cfbaa2876cfb1c31483346f235 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 7 Apr 2023 16:25:31 +0300 Subject: [PATCH 2/7] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach Co-authored-by: Ezio Melotti --- Doc/howto/argparse.rst | 4 ++-- Doc/library/argparse.rst | 4 ++-- Doc/library/optparse.rst | 23 ++++++++++++++++++----- 3 files changed, 22 insertions(+), 9 deletions(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 4c3913d6ba87f2..100210a6c28d8c 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -258,7 +258,7 @@ Here is what is happening: * To show that the option is actually optional, there is no error when running the program without it. Note that by default, if an optional argument isn't - used, the relevant variable, in this case :attr:`!args.verbosity`, is + used, the relevant variable, in this case ``args.verbosity``, is given ``None`` as a value, which is the reason it fails the truth test of the :keyword:`if` statement. @@ -301,7 +301,7 @@ Here is what is happening: We even changed the name of the option to match that idea. Note that we now specify a new keyword, ``action``, and give it the value ``"store_true"``. This means that, if the option is specified, - assign the value ``True`` to :data:`!args.verbose`. + assign the value ``True`` to ``args.verbose``. Not specifying it implies ``False``. * It complains when you specify a value, in true spirit of what flags diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 409c91e5a22313..e8a5aae450190b 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -585,7 +585,7 @@ arguments will never be treated as file references. .. versionchanged:: 3.12 :class:`ArgumentParser` changed encoding and errors to read arguments files - from default (e.g. :func:`locale.getpreferredencoding(False) ` and + from default (e.g. :func:`locale.getpreferredencoding(False) ` and ``"strict"``) to :term:`filesystem encoding and error handler`. Arguments file should be encoded in UTF-8 instead of ANSI Codepage on Windows. @@ -2308,4 +2308,4 @@ Exceptions .. exception:: ArgumentTypeError - An error from trying to convert a command line string to a type. + Raised when something goes wrong converting a command line string to a type. diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index 2966b5a303851d..cc1a12766c4525 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -952,11 +952,18 @@ The canonical way to create an :class:`Option` instance is with the you may also supply :attr:`~Option.type` and :attr:`~Option.dest` option attributes; see :ref:`optparse-standard-option-actions`.) -.. class:: Values - As you can see, most actions involve storing or updating a value somewhere. :mod:`optparse` always creates a special object for this, conventionally called -``options`` (it happens to be an instance of :class:`optparse.Values`). Option +``options``, which is an instance of :class:`optparse.Values`. + +.. class:: Values + + An object holding parsed argument names and values as attributes. + Normally created by calling when calling :meth:`OptionParser.parse_args`, + and can be overridden by a custom subclass passed to the *values* argument of + :meth:`OptionParser.parse_args` (as described in :ref:`optparse-parsing-arguments`). + +Option arguments (and various other values) are stored as attributes of this object, according to the :attr:`~Option.dest` (destination) option attribute. @@ -995,6 +1002,12 @@ Option attributes .. class:: Option + A single command line argument, + with various attributes passed by keyword to the constructor. + Normally created with :meth:`OptionParser.add_option` rather than directly, + and can be overridden by a custom class via the *option_class* argument + to :class:`OptionParser`. + The following option attributes may be passed as keyword arguments to :meth:`OptionParser.add_option`. If you pass an option attribute that is not relevant to a particular option, or fail to pass a required option attribute, @@ -2058,8 +2071,8 @@ Exceptions .. exception:: BadOptionError - Raised if an invalid option is seen on the command line. + Raised if an invalid option is passed on the command line. .. exception:: AmbiguousOptionError - Raised if an ambiguous option is seen on the command line. + Raised if an ambiguous option is passed on the command line. From 79665ee6aee80c2fd07fe4997a08b3db3bc6bf0d Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 7 Apr 2023 16:28:21 +0300 Subject: [PATCH 3/7] Fix ref label and currentmodule positions --- Doc/howto/argparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 100210a6c28d8c..52e98fa9620194 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -1,11 +1,11 @@ +.. _argparse-tutorial: + ***************** Argparse Tutorial ***************** :author: Tshepang Mbambo -.. _argparse-tutorial: - .. currentmodule:: argparse This tutorial is intended to be a gentle introduction to :mod:`argparse`, the From d474195b4903b57d46e705f75eb400358b3f547b Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 7 Apr 2023 16:32:34 +0300 Subject: [PATCH 4/7] Suppress warnings for add_parser --- Doc/library/argparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index e8a5aae450190b..a503316da20ccd 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1723,7 +1723,7 @@ Sub-commands :class:`ArgumentParser` supports the creation of such sub-commands with the :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:`~ArgumentParser.add_parser`, which takes a + has a single method, :meth:`!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. @@ -1789,7 +1789,7 @@ Sub-commands for that particular parser will be printed. The help message will not include parent parser or sibling parser messages. (A help message for each subparser command, however, can be given by supplying the ``help=`` argument - to :meth:`add_parser` as above.) + to :meth:`!add_parser` as above.) :: From d6fa9552200354966cde605b821f995e6e38d7a6 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Fri, 7 Apr 2023 16:36:11 +0300 Subject: [PATCH 5/7] Trim trailing whitespace --- Doc/library/optparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index cc1a12766c4525..d80d174567a95b 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -960,9 +960,9 @@ As you can see, most actions involve storing or updating a value somewhere. An object holding parsed argument names and values as attributes. Normally created by calling when calling :meth:`OptionParser.parse_args`, - and can be overridden by a custom subclass passed to the *values* argument of + and can be overridden by a custom subclass passed to the *values* argument of :meth:`OptionParser.parse_args` (as described in :ref:`optparse-parsing-arguments`). - + Option arguments (and various other values) are stored as attributes of this object, according to the :attr:`~Option.dest` (destination) option attribute. From 328a896a1693954f0a6cc19a5cd15e22857079b1 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 24 Apr 2023 15:19:56 -0600 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/argparse.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index a503316da20ccd..14fed488571afa 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1723,7 +1723,7 @@ Sub-commands :class:`ArgumentParser` supports the creation of such sub-commands with the :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:`!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 returns an :class:`ArgumentParser` object that can be modified as usual. @@ -1789,7 +1789,7 @@ Sub-commands for that particular parser will be printed. The help message will not include parent parser or sibling parser messages. (A help message for each subparser command, however, can be given by supplying the ``help=`` argument - to :meth:`!add_parser` as above.) + to :meth:`~_SubParsersAction.add_parser` as above.) :: From 466589361c248031f5a7a29e4cc1dcdf112b385f Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 24 Apr 2023 15:25:07 -0600 Subject: [PATCH 7/7] Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot be resolved --- Doc/conf.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/conf.py b/Doc/conf.py index 29fb63cbcc8614..a5292bac3ca8ee 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -74,6 +74,13 @@ if venvdir is not None: exclude_patterns.append(venvdir + '/*') +nitpick_ignore = [ + # Do not error nit-picky mode builds when _SubParsersAction.add_parser cannot + # be resolved, as the method is currently undocumented. For context, see + # https://github.com/python/cpython/pull/103289. + ('py:meth', '_SubParsersAction.add_parser'), +] + # Disable Docutils smartquotes for several translations smartquotes_excludes = { 'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'], 'builders': ['man', 'text'],