[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