[2.7] Clarify nature of parse_args 'args' argument. (GH-3292) (GH-3328)
Patch by Paul.j3. Includes an unrelated but useful addition to the
optparse porting section.
(cherry picked from commit 0c7983e4adf9604d0ac93757a45d14be06c27696)
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index c8a5941..7993360 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -854,6 +854,8 @@
usage: PROG [-h] foo [foo ...]
PROG: error: too few arguments
+.. _`argparse.REMAINDER`:
+
* ``argparse.REMAINDER``. All the remaining command-line arguments are gathered
into a list. This is commonly useful for command line utilities that dispatch
to other command line utilities::
@@ -1275,8 +1277,11 @@
created and how they are assigned. See the documentation for
:meth:`add_argument` for details.
- By default, the argument strings are taken from :data:`sys.argv`, and a new empty
- :class:`Namespace` object is created for the attributes.
+ * args_ - List of strings to parse. The default is taken from
+ :data:`sys.argv`.
+
+ * namespace_ - An object to take the attributes. The default is a new empty
+ :class:`Namespace` object.
Option value syntax
@@ -1417,6 +1422,7 @@
An error is produced for arguments that could produce more than one options.
+.. _args:
Beyond ``sys.argv``
^^^^^^^^^^^^^^^^^^^
@@ -1438,6 +1444,7 @@
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
+.. _namespace:
The Namespace object
^^^^^^^^^^^^^^^^^^^^
@@ -1943,7 +1950,12 @@
* Replace ``(options, args) = parser.parse_args()`` with ``args =
parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
calls for the positional arguments. Keep in mind that what was previously
- called ``options``, now in :mod:`argparse` context is called ``args``.
+ called ``options``, now in the :mod:`argparse` context is called ``args``.
+
+* Replace :meth:`optparse.OptionParser.disable_interspersed_args`
+ by setting ``nargs`` of a positional argument to `argparse.REMAINDER`_, or
+ use :meth:`~ArgumentParser.parse_known_args` to collect unparsed argument
+ strings in a separate list.
* Replace callback actions and the ``callback_*`` keyword arguments with
``type`` or ``action`` arguments.