gh-84116: Docs: Document help and aliases for argparse.add_parser()

Doc/library/argparse.rst

@@ -1656,7 +1656,7 @@ The Namespace object
 Other utilities
 ---------------
 
-Sub-commands
+Subcommands
 ^^^^^^^^^^^^
 
 .. method:: ArgumentParser.add_subparsers(*, [title], [description], [prog], \
@@ -1672,36 +1672,49 @@ Sub-commands
    :class:`ArgumentParser` supports the creation of such subcommands with the
    :meth:`!add_subparsers` method.  The :meth:`!add_subparsers` method is normally
    called with no arguments and returns a special action object.  This object
-   has a single method, :meth:`~_SubParsersAction.add_parser`, which takes a
-   command name and any :class:`!ArgumentParser` constructor arguments, and
-   returns an :class:`!ArgumentParser` object that can be modified as usual.
+   has a single method, :meth:`~_SubParsersAction.add_parser`:
+
+   .. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None, deprecated=False, **kwargs)
+
+      Creates and returns a new :class:`!ArgumentParser` object for the
+      subcommand *name*.
+
+      The *name* argument is the name of the subcommand.
+      The *help* argument provides a short description for this subcommand. If provided, it will be listed next to the command in the main parser's help message (e.g., ``PROG --help``).
+
+      The *aliases* argument allows to provide a sequence of strings that can be used as alternative names for this subcommand (e.g., ``aliases=['r']`` for a ``'run'`` command).
+
+      The *deprecated* argument, if :const:`True`, marks the subcommand as deprecated, which typically issues a warning when used.
+      All other keyword arguments are passed directly to the
+      :class:`!ArgumentParser` constructor.
+      This returned :class:`!ArgumentParser` object can be modified as usual.
 
    Description of parameters:
 
-   * *title* - title for the sub-parser group in help output; by default
+   * *title* - title for the subparser group in help output; by default
      "subcommands" if description is provided, otherwise uses title for
      positional arguments
 
-   * *description* - description for the sub-parser group in help output, by
+   * *description* - description for the subparser group in help output, by
      default ``None``
 
-   * *prog* - usage information that will be displayed with sub-command help,
+   * *prog* - usage information that will be displayed with subcommand help,
      by default the name of the program and any positional arguments before the
      subparser argument
 
-   * *parser_class* - class which will be used to create sub-parser instances, by
+   * *parser_class* - class which will be used to create subparser instances, by
      default the class of the current parser (e.g. :class:`ArgumentParser`)
 
    * action_ - the basic type of action to be taken when this argument is
      encountered at the command line
 
-   * dest_ - name of the attribute under which sub-command name will be
+   * dest_ - name of the attribute under which subcommand name will be
      stored; by default ``None`` and no value is stored
 
    * required_ - Whether or not a subcommand must be provided, by default
      ``False`` (added in 3.7)
 
-   * help_ - help for sub-parser group in help output, by default ``None``
+   * help_ - help for subparser group in help output, by default ``None``
 
    * metavar_ - string presenting available subcommands in help; by default it
      is ``None`` and presents subcommands in form {cmd1, cmd2, ..}
@@ -1727,7 +1740,7 @@ Sub-commands
      >>> 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
@@ -1738,7 +1751,7 @@ Sub-commands
    for that particular parser will be printed.  The help message will not
    include parent parser or sibling parser messages.  (A help message for each
    subparser command, however, can be given by supplying the ``help=`` argument
-   to :meth:`~_SubParsersAction.add_parser` as above.)
+   to ``add_parser()`` as above.)
 
    ::
 
@@ -1770,7 +1783,7 @@ Sub-commands
        -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::
 
@@ -1791,34 +1804,50 @@ Sub-commands
 
        {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``::
+   .. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None, deprecated=False, **kwargs)
 
-     >>> 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')
+      Creates and returns a new :class:`!ArgumentParser` object for the
+      subcommand name.
 
-   :meth:`~_SubParsersAction.add_parser` supports also an additional
-   *deprecated* argument, which allows to deprecate the subparser.
+      The name argument is the name of the subcommand.
 
-      >>> 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()
+      The help argument provides a short description for this subcommand.
+      If provided, it will be listed next to the command in the main
+      parser’s help message (e.g., ``PROG --help``).
+
+      The aliases argument allows you to provide a sequence of strings
+      that can be used as alternative names for this subcommand
+      (e.g., ``aliases=['co']`` for a ``'checkout'`` command).
+
+      The deprecated argument allows you to mark the subcommand as
+      deprecated. When a deprecated subcommand is used, :mod:`argparse`
+      will emit a warning.
+
+      This returned :class:`!ArgumentParser`
+      object can be modified as usual.
+
+      *Examples*
+
+      Using aliases::
+
+         >>> 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')
+
+      Using deprecated::
 
-   .. versionadded:: 3.13
+         >>> parser = argparse.ArgumentParser(prog='chicken.py')
+         >>> subparsers = parser.add_subparsers()
+         >>> fly = subparsers.add_parser('fly', deprecated=True)
+         >>> parser.parse_args(['fly'])  # doctest: +SKIP
+         chicken.py: warning: command 'fly' is deprecated
+         Namespace()
 
    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::
 
@@ -1854,12 +1883,12 @@ Sub-commands
      >>> 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')
@@ -2241,7 +2270,7 @@ Registering custom types or actions
 
    Sometimes it's desirable to use a custom string in error messages to provide
    more user-friendly output. In these cases, :meth:`!register` can be used to
-   register custom actions or types with a parser and allow you to reference the
+   register custom actions or types with a parser anto reference the
    type by their registered name instead of their callable name.
 
    The :meth:`!register` method accepts three arguments - a *registry_name*,

Misc/NEWS.d/next/Documentation/2025-10-25-14-08-42.gh-issue-84116.lKcoHw.rst

@@ -0,0 +1,3 @@
+Document ``help`` and ``aliases`` parameters for
+``argparse._SubParsersAction.add_parser`` in the :mod:`argparse`
+documentation.