[Python-checkins] [3.6] Clarify nature of parse_args 'args' argument. (GH-3292) (GH-3325)

[Mariatta]

https://github.com/python/cpython/commit/f8693229f5650e464a5c112ad28fd4e14d55a7bd
commit: f8693229f5650e464a5c112ad28fd4e14d55a7bd
branch: 3.6
author: R. David Murray <rdmurray at bitdance.com>
committer: Mariatta <Mariatta at users.noreply.github.com>
date: 2017-09-09T22:54:05-07:00
summary:

[3.6] Clarify nature of parse_args 'args' argument. (GH-3292) (GH-3325)

Patch by Paul.j3.  Includes an unrelated but useful addition to the
optparse porting section.
(cherry picked from commit 0c7983e4adf9604d0ac93757a45d14be06c27696)

files:
M Doc/library/argparse.rst

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 9411bbd4ac5..27c7ba55820 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -900,6 +900,8 @@ values are:
      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::
@@ -1326,8 +1328,11 @@ The parse_args() method
    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
@@ -1469,6 +1474,7 @@ unambiguous (the prefix matches a unique option)::
 An error is produced for arguments that could produce more than one options.
 This feature can be disabled by setting :ref:`allow_abbrev` to ``False``.
 
+.. _args:
 
 Beyond ``sys.argv``
 ^^^^^^^^^^^^^^^^^^^
@@ -1490,6 +1496,7 @@ interactive prompt::
    >>> parser.parse_args(['1', '2', '3', '4', '--sum'])
    Namespace(accumulate=<built-in function sum>, integers=[1, 2, 3, 4])
 
+.. _namespace:
 
 The Namespace object
 ^^^^^^^^^^^^^^^^^^^^
@@ -2010,7 +2017,12 @@ A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
 * 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.