@@ -1804,32 +1804,46 @@ Subcommands
18041804
18051805 {foo,bar} additional help
18061806
1807- Furthermore, :meth: `~_SubParsersAction.add_parser ` supports an additional
1808- *aliases * argument,
1809- which allows multiple strings to refer to the same subparser. This example,
1810- like ``svn ``, aliases ``co `` as a shorthand for ``checkout ``::
1807+ .. method :: _SubParsersAction.add_parser(name, *, help=None, aliases=None, deprecated=False, **kwargs)
18111808
1812- >>> parser = argparse.ArgumentParser()
1813- >>> subparsers = parser.add_subparsers()
1814- >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
1815- >>> checkout.add_argument('foo')
1816- >>> parser.parse_args(['co', 'bar'])
1817- Namespace(foo='bar')
1809+ Creates and returns a new :class: !ArgumentParser object for the
1810+ subcommand name.
18181811
1819- :meth: `~_SubParsersAction.add_parser ` supports also an additional
1820- *deprecated * argument, which allows to deprecate the subparser.
1812+ The name argument is the name of the subcommand.
18211813
1822- >>> import argparse
1823- >>> parser = argparse.ArgumentParser(prog = ' chicken.py' )
1824- >>> subparsers = parser.add_subparsers()
1825- >>> run = subparsers.add_parser(' run' )
1826- >>> fly = subparsers.add_parser(' fly' , deprecated = True )
1827- >>> parser.parse_args([' fly' ]) # doctest: +SKIP
1828- chicken.py: warning: command 'fly' is deprecated
1829- Namespace()
1814+ The help argument provides a short description for this subcommand.
1815+ If provided, it will be listed next to the command in the main
1816+ parser’s help message (e.g., `PROG --help `).
1817+
1818+ The aliases argument allows you to provide a sequence of strings
1819+ that can be used as alternative names for this subcommand
1820+ (e.g., `aliases=['co'] ` for a `'checkout' ` command).
1821+
1822+ The deprecated argument allows you to mark the subcommand as
1823+ deprecated. When a deprecated subcommand is used, :mod: argparse
1824+ will emit a warning.
1825+
1826+ This returned :class: !ArgumentParser object can be modified as usual.
1827+
1828+ *Examples *
1829+
1830+ Using aliases::
1831+
1832+ >>> parser = argparse.ArgumentParser()
1833+ >>> subparsers = parser.add_subparsers()
1834+ >>> checkout = subparsers.add_parser('checkout', aliases=['co'])
1835+ >>> checkout.add_argument('foo')
1836+ >>> parser.parse_args(['co', 'bar'])
1837+ Namespace(foo='bar')
18301838
1831- .. versionadded :: 3.13
1839+ Using deprecated::
18321840
1841+ >>> parser = argparse.ArgumentParser(prog='chicken.py')
1842+ >>> subparsers = parser.add_subparsers()
1843+ >>> fly = subparsers.add_parser('fly', deprecated=True)
1844+ >>> parser.parse_args(['fly']) # doctest: +SKIP
1845+ chicken.py: warning: command 'fly' is deprecated
1846+ Namespace()
18331847 One particularly effective way of handling subcommands is to combine the use
18341848 of the :meth: `~ArgumentParser.add_subparsers ` method with calls to :meth: `~ArgumentParser.set_defaults ` so
18351849 that each subparser knows which Python function it should execute. For
0 commit comments