https://github.com/python/cpython/commit/e6fc15f7ec5f8f98cc4e0fc67d2051d0b4ce52d2 commit: e6fc15f7ec5f8f98cc4e0fc67d2051d0b4ce52d2 branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: savannahostrowski <[email protected]> date: 2026-11-12T17:56:20Z summary:
[3.14] gh-101472: Redocument `argparse.REMAINDER` and its limitations (GH-160119) (#161887) gh-101472: Redocument `argparse.REMAINDER` and its limitations (GH-160119) (cherry picked from commit f322b3ec8ac9bce2ddaaa26a70a4e505bc18cba1) Co-authored-by: Savannah Ostrowski <[email protected]> files: M Doc/library/argparse.rst M Lib/test/test_argparse.py diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index bc08b1ec86ec3a..99be249cc14c36 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -969,6 +969,53 @@ See also :ref:`specifying-ambiguous-arguments`. The supported values are: usage: PROG [-h] foo [foo ...] PROG: error: the following arguments are required: foo +.. _argparse.REMAINDER: + +* ``argparse.REMAINDER``. Remaining command-line arguments are gathered into a + list, including strings that look like options. This is useful for forwarding + arguments to another command. A common pattern is a final positional argument + after a command name; options for the outer parser must precede that command:: + + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo') + >>> parser.add_argument('command') + >>> parser.add_argument('args', nargs=argparse.REMAINDER) + >>> parser.parse_args('--foo B cmd --foo C'.split()) + Namespace(foo='B', command='cmd', args=['--foo', 'C']) + >>> parser.parse_args(['cmd']) + Namespace(foo=None, command='cmd', args=[]) + + When the remainder is the first positional argument, leading options are still + parsed normally. It starts with the first positional value, or with ``--``. + In a subparser, the subcommand name has already been consumed by the parent + parser and does not start the remainder. Any ``--`` consumed by the remainder + is retained:: + + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('args', nargs=argparse.REMAINDER) + >>> parser.parse_args(['--', '--foo', 'B']) + Namespace(args=['--', '--foo', 'B']) + + For an optional argument, supply the option separately from its values:: + + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--forward', nargs=argparse.REMAINDER) + >>> parser.parse_args('--forward --foo B --'.split()) + Namespace(forward=['--foo', 'B', '--']) + >>> parser.parse_args(['--forward']) + Namespace(forward=[]) + + An attached value such as ``--forward=value`` supplies only that value; + subsequent arguments are parsed normally. + + .. versionchanged:: 3.15 + Optional arguments with ``nargs=argparse.REMAINDER`` consume ``--`` and + subsequent arguments instead of stopping at ``--``. + + With the default ``'store'`` action, an empty positional remainder ignores + default_ and produces ``[]``. The choices_ restriction is not applied to the + remainder. + If the ``nargs`` keyword argument is not provided, the number of arguments consumed is determined by the action_. Generally this means a single command-line argument will be consumed and a single item (not a list) will be produced. @@ -2262,8 +2309,9 @@ Intermixed parsing These parsers do not support all the :mod:`!argparse` features, and will raise exceptions if unsupported features are used. In particular, subparsers, - and mutually exclusive groups that include both - optionals and positionals are not supported. + positional arguments with + :ref:`nargs=argparse.REMAINDER <argparse.REMAINDER>`, and mutually exclusive + groups that include both optionals and positionals are not supported. The following example shows the difference between :meth:`~ArgumentParser.parse_known_args` and diff --git a/Lib/test/test_argparse.py b/Lib/test/test_argparse.py index 740119a952f81b..a9a17a5fdda6de 100644 --- a/Lib/test/test_argparse.py +++ b/Lib/test/test_argparse.py @@ -1637,6 +1637,75 @@ class TestNargsRemainder(ParserTestCase): ] +class TestNargsRemainderBoundaries(TestCase): + + def test_first_positional(self): + parser = argparse.ArgumentParser(exit_on_error=False) + parser.add_argument('--foo') + parser.add_argument('args', nargs=argparse.REMAINDER) + + for args in (['--unknown'], ['--foo', 'B', '--unknown']): + with self.subTest(args=args): + with self.assertRaisesRegex( + argparse.ArgumentError, + 'unrecognized arguments: --unknown'): + parser.parse_args(args) + self.assertEqual(parser.parse_args(['--foo', 'B']), + NS(foo='B', args=[])) + self.assertEqual(parser.parse_args(['cmd', '--foo', 'C']), + NS(foo=None, args=['cmd', '--foo', 'C'])) + self.assertEqual(parser.parse_args(['--', '--foo', 'C']), + NS(foo=None, args=['--', '--foo', 'C'])) + + def test_first_positional_in_subparser(self): + parser = argparse.ArgumentParser(exit_on_error=False) + subparser = parser.add_subparsers().add_parser('run') + subparser.add_argument('--foo', action='store_true') + subparser.add_argument('args', nargs=argparse.REMAINDER) + + with self.assertRaisesRegex(argparse.ArgumentError, + 'unrecognized arguments: --unknown'): + parser.parse_args(['run', '--unknown']) + self.assertEqual(parser.parse_args(['run', '--foo']), + NS(foo=True, args=[])) + self.assertEqual(parser.parse_args(['run', 'cmd', '--foo']), + NS(foo=False, args=['cmd', '--foo'])) + self.assertEqual(parser.parse_args(['run', '--', '--foo']), + NS(foo=False, args=['--', '--foo'])) + + def test_optional_captures_options(self): + parser = argparse.ArgumentParser() + parser.add_argument('--foo', action='store_true') + parser.add_argument('--forward', nargs=argparse.REMAINDER, + default=['fallback']) + + self.assertEqual(parser.parse_args(['--forward']), + NS(foo=False, forward=[])) + self.assertEqual(parser.parse_args(['--forward', '--foo']), + NS(foo=False, forward=['--foo'])) + + def test_optional_attached_value(self): + parser = argparse.ArgumentParser() + parser.add_argument('-f', '--forward', nargs=argparse.REMAINDER) + + for option in ('--forward=a', '-fa'): + with self.subTest(option=option): + self.assertEqual(parser.parse_known_args([option, 'b']), + (NS(forward=['a']), ['b'])) + + def test_empty_positional_ignores_default(self): + parser = argparse.ArgumentParser() + parser.add_argument('args', nargs=argparse.REMAINDER, + default=['fallback']) + self.assertEqual(parser.parse_args([]), NS(args=[])) + + def test_type_conversion_without_choices_validation(self): + parser = argparse.ArgumentParser() + parser.add_argument('args', nargs=argparse.REMAINDER, + type=int, choices=[1]) + self.assertEqual(parser.parse_args(['2']), NS(args=[2])) + + class TestOptionLike(ParserTestCase): """Tests options that may or may not be arguments""" @@ -6594,7 +6663,7 @@ def test_basic(self): self.assertEqual(bar.required, True) def test_remainder(self): - # Intermixed and remainder are incompatible + # Intermixed and positional remainder are incompatible parser = ErrorRaisingArgumentParser(prog='PROG') parser.add_argument('-z') parser.add_argument('x') @@ -6606,6 +6675,14 @@ def test_remainder(self): parser.parse_intermixed_args(argv) self.assertRegex(str(cm.exception), r'\.\.\.') + def test_optional_remainder(self): + parser = argparse.ArgumentParser() + parser.add_argument('command') + parser.add_argument('--forward', nargs=argparse.REMAINDER) + self.assertEqual( + parser.parse_intermixed_args(['cmd', '--forward', '--foo']), + NS(command='cmd', forward=['--foo'])) + def test_required_exclusive(self): # required mutually exclusive group; intermixed works fine parser = argparse.ArgumentParser(prog='PROG', exit_on_error=False) _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
