[Python-checkins] bpo-9182: Add a section on specifying positional arguments (#31810)

rhettinger webhook-mailer at python.org
Fri May 13 10:17:15 EDT 2022


https://github.com/python/cpython/commit/3e3e8976b8096ae1c52432bd3be15784ea82d956
commit: 3e3e8976b8096ae1c52432bd3be15784ea82d956
branch: main
author: slateny <46876382+slateny at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2022-05-13T09:17:07-05:00
summary:

bpo-9182: Add a section on specifying positional arguments (#31810)

files:
M Doc/howto/argparse.rst
M Doc/library/argparse.rst

diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index a97d10cfe6bb6..3075b0142d16d 100644
--- a/Doc/howto/argparse.rst
+++ b/Doc/howto/argparse.rst
@@ -664,6 +664,35 @@ Output:
    4^2 == 16
 
 
+.. _specifying-ambiguous-arguments:
+
+Specifying ambiguous arguments
+------------------------------
+
+When there is ambiguity in deciding whether an argument is positional or for an
+argument, ``--`` can be used to tell :meth:`~ArgumentParser.parse_args` that
+everything after that is a positional argument::
+
+   >>> parser = argparse.ArgumentParser(prog='PROG')
+   >>> parser.add_argument('-n', nargs='+')
+   >>> parser.add_argument('args', nargs='*')
+
+   >>> # ambiguous, so parse_args assumes it's an option
+   >>> parser.parse_args(['-f'])
+   usage: PROG [-h] [-n N [N ...]] [args ...]
+   PROG: error: unrecognized arguments: -f
+
+   >>> parser.parse_args(['--', '-f'])
+   Namespace(args=['-f'], n=None)
+
+   >>> # ambiguous, so the -n option greedily accepts arguments
+   >>> parser.parse_args(['-n', '1', '2', '3'])
+   Namespace(args=[], n=['1', '2', '3'])
+
+   >>> parser.parse_args(['-n', '1', '--', '2', '3'])
+   Namespace(args=['2', '3'], n=['1'])
+
+
 Conflicting options
 -------------------
 
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 1f40e4a84505d..83dd3cdf03136 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -951,8 +951,8 @@ nargs
 
 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.  The supported
-values are:
+different number of command-line arguments with a single action.
+See also :ref:`specifying-ambiguous-arguments`. The supported values are:
 
 * ``N`` (an integer).  ``N`` arguments from the command line will be gathered
   together into a list.  For example::
@@ -1610,6 +1610,9 @@ argument::
    >>> parser.parse_args(['--', '-f'])
    Namespace(foo='-f', one=None)
 
+See also :ref:`the argparse howto on ambiguous arguments <specifying-ambiguous-arguments>`
+for more details.
+
 .. _prefix-matching:
 
 Argument abbreviations (prefix matching)



More information about the Python-checkins mailing list