From 0760f92736e2340f0a18f886e125a25e1306e3d3 Mon Sep 17 00:00:00 2001
From: slateny <46876382+slateny@users.noreply.github.com>
Date: Thu, 12 May 2022 21:38:56 -0700
Subject: [PATCH 1/2] Add section to argparse howto on ambiguous argument

---
 Doc/howto/argparse.rst   | 29 +++++++++++++++++++++++++++++
 Doc/library/argparse.rst |  8 ++++++--
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst
index a97d10cfe6bb69..3075b0142d16d6 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 b5a2b794c2385f..f5ee07c26a2dc6 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::
@@ -1602,6 +1602,7 @@ there are no options in the parser that look like negative numbers::
    usage: PROG [-h] [-1 ONE] [foo]
    PROG: error: argument -1: expected one argument
 
+
 If you have positional arguments that must begin with ``-`` and don't look
 like negative numbers, you can insert the pseudo-argument ``'--'`` which tells
 :meth:`~ArgumentParser.parse_args` that everything after that is a positional
@@ -1610,6 +1611,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)

From 52dd9cef56ec71e2d1aff43be3dfc8a88f71fa59 Mon Sep 17 00:00:00 2001
From: slateny <46876382+slateny@users.noreply.github.com>
Date: Thu, 12 May 2022 21:39:41 -0700
Subject: [PATCH 2/2] Remove random newline

---
 Doc/library/argparse.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index f5ee07c26a2dc6..e35446cfe0246a 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1602,7 +1602,6 @@ there are no options in the parser that look like negative numbers::
    usage: PROG [-h] [-1 ONE] [foo]
    PROG: error: argument -1: expected one argument
 
-
 If you have positional arguments that must begin with ``-`` and don't look
 like negative numbers, you can insert the pseudo-argument ``'--'`` which tells
 :meth:`~ArgumentParser.parse_args` that everything after that is a positional