[Python-checkins] gh-101100: Fix Sphinx warnings in `argparse` module (#103289)
hugovk
webhook-mailer at python.org
Mon Apr 24 17:36:40 EDT 2023
https://github.com/python/cpython/commit/79ae019164eeb6b94118bc17bc1e937405684c75
commit: 79ae019164eeb6b94118bc17bc1e937405684c75
branch: main
author: Hugo van Kemenade <hugovk at users.noreply.github.com>
committer: hugovk <hugovk at users.noreply.github.com>
date: 2023-04-24T15:36:32-06:00
summary:
gh-101100: Fix Sphinx warnings in `argparse` module (#103289)
Co-authored-by: C.A.M. Gerlach <CAM.Gerlach at Gerlach.CAM>
Co-authored-by: Ezio Melotti <ezio.melotti at gmail.com>
files:
M Doc/conf.py
M Doc/howto/argparse.rst
M Doc/library/argparse.rst
M Doc/library/optparse.rst
M Doc/tools/.nitignore
diff --git a/Doc/conf.py b/Doc/conf.py
index 4c120bee64dd..42c23bf77c70 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -76,6 +76,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'],
diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index f682587488a2..52e98fa96201 100644
--- a/Doc/howto/argparse.rst
+++ b/Doc/howto/argparse.rst
@@ -1,10 +1,12 @@
+.. _argparse-tutorial:
+
*****************
Argparse Tutorial
*****************
:author: Tshepang Mbambo
-.. _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.
@@ -12,7 +14,7 @@ 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 ``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 ``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 dd59181a3070..33e367f3ccda 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) <locale.getpreferredencoding>` 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, \
@@ -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:`~_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.)
::
@@ -2157,7 +2157,7 @@ the populated namespace and the list of remaining argument strings.
.. warning::
:ref:`Prefix matching <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='<the 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
+
+ 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 468c3efbe011..5c02d8bc8835 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -954,7 +954,16 @@ The canonical way to create an :class:`Option` instance is with the
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.
@@ -991,6 +1000,14 @@ one that makes sense for *all* options.
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,
@@ -2035,3 +2052,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 passed on the command line.
+
+.. exception:: AmbiguousOptionError
+
+ Raised if an ambiguous option is passed on the command line.
diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
index f6fe8df97810..e77da1c12eba 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
More information about the Python-checkins
mailing list