https://github.com/python/cpython/commit/74db4404eaa9b4448b50ab7be7d50487dc0585fd commit: 74db4404eaa9b4448b50ab7be7d50487dc0585fd branch: main author: Krishna-web-hub <[email protected]> committer: savannahostrowski <[email protected]> date: 2026-02-06T13:26:44-08:00 summary:
gh-84116: Docs: Document help and aliases for argparse.add_parser() (#140574) * gh-140281: Doc: Update free-threading how-to * gh-140281: Doc: Update free-threading how-to * Fix trailing whitespace * doc fixing of the cpython fixes#84116 * Docs: Document help and aliases for argparse.add_parser() (gh-84116) * Docs: Document help and aliases for argparse.add_parser() (gh-84116) * Fix trailing whitespace * Fix trailing whitespace * Fix trailing whitespace * Fix trailing whitespace * Fix trailing whitespace * Fix trailing whitespace * Fix trailing errors * Fix trailing errors and spaces * Fix docutils formatting, NEWS ref, and trailing whitespace * Docs: Update argparse.rst and add NEWS entry * Delete Doc/howto/free-threading-python.rst * Delete Misc/NEWS.d/next/Documentation/2025-10-25-00-49-43.gh-issue-140281.tuMQUe.rst * adding the depreceated tag * The error indexing was fixed * Fix trailing whitespace * Restore missing free-threading documentation * fixing some minor error * fixing some minor error part 2 * fixing some minor error part 3 * Fix NEWS entry format * Final cleanup of NEWS entry format 2 * changes in the argparse.rst * Remove unnecessary NEWS entry * Fixing the issue as requested * Added the Changes done before. * done the changes * done the changes#1 * Apply suggestion from @picnixz Co-authored-by: Bénédikt Tran <[email protected]> * Apply suggestion from @picnixz Co-authored-by: Bénédikt Tran <[email protected]> * Done the changes * Done the new changes * The versionadded is rectified * Update Doc/library/argparse.rst Co-authored-by: Stan Ulbrych <[email protected]> * Docs editing * Docs fixing whitespace * Docs rectifiying * little bit rectification * Indentation rectification * Indentation rectification 1 * Apply suggestion from @picnixz Co-authored-by: Bénédikt Tran <[email protected]> * deprecated rectification * Remove mistakenly added NEWS entry * Update Doc/library/argparse.rst Co-authored-by: Bénédikt Tran <[email protected]> * changes #1 Co-authored-by: Bénédikt Tran <[email protected]> * Update Doc/library/argparse.rst 2 Co-authored-by: Bénédikt Tran <[email protected]> * removed useless thing Co-authored-by: Bénédikt Tran <[email protected]> * changed according to the request Co-authored-by: Bénédikt Tran <[email protected]> * Updated the test part --------- Co-authored-by: Bénédikt Tran <[email protected]> Co-authored-by: Stan Ulbrych <[email protected]> files: M Doc/library/argparse.rst diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index c7532ecd629b02..81e5d3470c3e57 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1771,7 +1771,7 @@ Subcommands >>> parser.parse_args(['--foo', 'b', '--baz', 'Z']) Namespace(baz='Z', foo=True) - Note that the object returned by :meth:`parse_args` will only contain + Note that the object returned by :meth:`~ArgumentParser.parse_args` will only contain attributes for the main parser and the subparser that was selected by the command line (and not any other subparsers). So in the example above, when the ``a`` command is specified, only the ``foo`` and ``bar`` attributes are @@ -1814,7 +1814,7 @@ Subcommands -h, --help show this help message and exit --baz {X,Y,Z} baz help - The :meth:`add_subparsers` method also supports ``title`` and ``description`` + The :meth:`~ArgumentParser.add_subparsers` method also supports ``title`` and ``description`` keyword arguments. When either is present, the subparser's commands will appear in their own group in the help output. For example:: @@ -1835,34 +1835,8 @@ Subcommands {foo,bar} additional help - Furthermore, :meth:`~_SubParsersAction.add_parser` supports an additional - *aliases* argument, - which allows multiple strings to refer to the same subparser. This example, - like ``svn``, aliases ``co`` as a shorthand for ``checkout``:: - - >>> parser = argparse.ArgumentParser() - >>> subparsers = parser.add_subparsers() - >>> checkout = subparsers.add_parser('checkout', aliases=['co']) - >>> checkout.add_argument('foo') - >>> parser.parse_args(['co', 'bar']) - Namespace(foo='bar') - - :meth:`~_SubParsersAction.add_parser` supports also an additional - *deprecated* argument, which allows to deprecate the subparser. - - >>> import argparse - >>> parser = argparse.ArgumentParser(prog='chicken.py') - >>> subparsers = parser.add_subparsers() - >>> run = subparsers.add_parser('run') - >>> fly = subparsers.add_parser('fly', deprecated=True) - >>> parser.parse_args(['fly']) # doctest: +SKIP - chicken.py: warning: command 'fly' is deprecated - Namespace() - - .. versionadded:: 3.13 - One particularly effective way of handling subcommands is to combine the use - of the :meth:`add_subparsers` method with calls to :meth:`set_defaults` so + of the :meth:`~ArgumentParser.add_subparsers` method with calls to :meth:`~ArgumentParser.set_defaults` so that each subparser knows which Python function it should execute. For example:: @@ -1898,12 +1872,12 @@ Subcommands >>> args.func(args) ((XYZYX)) - This way, you can let :meth:`parse_args` do the job of calling the + This way, you can let :meth:`~ArgumentParser.parse_args` do the job of calling the appropriate function after argument parsing is complete. Associating functions with actions like this is typically the easiest way to handle the different actions for each of your subparsers. However, if it is necessary to check the name of the subparser that was invoked, the ``dest`` keyword - argument to the :meth:`add_subparsers` call will work:: + argument to the :meth:`~ArgumentParser.add_subparsers` call will work:: >>> parser = argparse.ArgumentParser() >>> subparsers = parser.add_subparsers(dest='subparser_name') @@ -1922,6 +1896,43 @@ Subcommands the main parser. +.. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None, + deprecated=False, **kwargs) + + Create and return a new :class:`ArgumentParser` object for the + subcommand *name*. + + The *name* argument is the name of the sub-command. + + The *help* argument provides a short description for this sub-command. + + The *aliases* argument allows providing alternative names for this + sub-command. For example:: + + >>> parser = argparse.ArgumentParser() + >>> subparsers = parser.add_subparsers() + >>> checkout = subparsers.add_parser('checkout', aliases=['co']) + >>> checkout.add_argument('foo') + >>> parser.parse_args(['co', 'bar']) + Namespace(foo='bar') + + The *deprecated* argument, if ``True``, marks the sub-command as + deprecated and will issue a warning when used. For example:: + + >>> parser = argparse.ArgumentParser(prog='chicken.py') + >>> subparsers = parser.add_subparsers() + >>> fly = subparsers.add_parser('fly', deprecated=True) + >>> args = parser.parse_args(['fly']) + chicken.py: warning: command 'fly' is deprecated + Namespace() + + All other keyword arguments are passed directly to the + :class:`!ArgumentParser` constructor. + + .. versionadded:: 3.13 + Added the *deprecated* parameter. + + FileType objects ^^^^^^^^^^^^^^^^ _______________________________________________ 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]
