gh-84116: Docs: Document help and aliases for argparse.add_parser() #140574
Conversation
…python into doc-fix-140281
Krishna-web-hub
force-pushed
the
doc-fix-84116
branch
from
57a35b9 to
343648b
Compare
StanFromIreland
changed the title
StanFromIreland
left a comment
StanFromIreland
left a comment
There was a problem hiding this comment.
There seem to be two different things mixed in this PR, please split it.
Krishna-web-hub
force-pushed
the
doc-fix-84116
branch
from
ce36e2d to
10dffc6
Compare
Krishna-web-hub
force-pushed
the
doc-fix-84116
branch
from
10dffc6 to
e955fb0
Compare
There was a problem hiding this comment.
Why are you deleting this?!
There was a problem hiding this comment.
Hello @StanFromIreland ,
Because i by mistakenly added the other branch commit in this branch.
please let me raise a new pr for it.I am very sorry for this mistake
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
This comment was marked as spam.
This comment was marked as spam.
Sorry, something went wrong.
savannahostrowski
left a comment
savannahostrowski
left a comment
There was a problem hiding this comment.
Thanks for kicking this off! My main comment on this is where to place this content, and some additional restructuring to reconcile duplicative content!
We'll also need to add back the doc on free threading (no worries there, it happens to everyone from time to time 😅 !)
| 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 | ||
|
|
There was a problem hiding this comment.
I would actually recommend adding the formal documentation for the ~_SubParsersAction.add_parser method just above this block. We can remove this redundant section about aliases and incorporate deprecated as well.
I'm thinking something like:
.. method:: _SubParsersAction.add_parser(name, *, help=None, aliases=None, deprecated=False, **kwargs)
<rest of method docs>
This returned :class:`!ArgumentParser` object can be modified as usual.
The following example shows how to use *aliases* to create a shorthand
for a subcommand, like ``svn`` uses ``co`` for ``checkout``::
<examples>
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
4 participants
gh-84116: Doc: update the argparse documentation to clearly define the help and aliases parameters for add_parser() and added the required news file for this change.
Doc/library/argparse.rst
Replaced the vague, single-sentence description of _SubParsersAction.add_parser with a formal .. method:: directive.
This new directive explicitly lists help and aliases as parameters, along with descriptions of what they do.
Removed the old, redundant paragraphs about help (which was in parentheses) and aliases (which was a "Furthermore..." note) from later in the document. This centralizes all the information in one logical place.
Misc/NEWS.d/next/Library/...
Added the required "blurb" file to log this documentation fix.
📚 Documentation preview 📚: https://cpython-previews--140574.org.readthedocs.build/