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

Krishna-web-hub · 2025-10-25T09:47:46Z

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/

…python into doc-fix-140281

…4116)

StanFromIreland

There seem to be two different things mixed in this PR, please split it.

Krishna-web-hub · 2025-12-09T17:56:46Z

I have made the requested changes; please review again.

bedevere-app · 2025-12-09T17:56:53Z

Thanks for making the requested changes!

@picnixz, @savannahostrowski: please review the changes made to this pull request.

savannahostrowski

Thanks for the updates. A few comments:

Can we make add_parser a top-level method directive rather than nesting it under add_subparsers? Right now it's a bit muddled. I think placing it around line 1807 (after the add_subparsers examples) would work well.
Related to the last point, the existing sections about add_parser aliases and deprecated further down in the docs are now redundant. We can remove those paragraphs and incorporate the content/examples into the new add_parser documentation.

Doc/library/argparse.rst

bedevere-app · 2025-12-09T19:02:59Z

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 I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

And if you don't make the requested changes, you will be put in the comfy chair!

Krishna-web-hub · 2025-12-11T18:03:54Z

Hi @savannahostrowski ,@picnixz I have made the requested changes; please review again.

bedevere-app · 2025-12-11T18:04:02Z

Thanks for making the requested changes!

@savannahostrowski, @picnixz: please review the changes made to this pull request.

Krishna-web-hub · 2025-12-24T12:04:05Z

Hi @savannahostrowski , @picnixz i have done all the changes according to your message been waiting for any further changes.

Krishna-web-hub · 2025-12-28T06:12:06Z

Apologies for the confusion
@savannahostrowski @picnixz.
I realized that my local commits were not successfully pushed when I posted my last message. I have just pushed the correct changes now, and the checks have passed. The PR is ready for review again.

picnixz

There are still unrelated changes. Please avoid asking for a review if there is still things to change and address.

picnixz · 2025-12-28T17:51:51Z

Doc/library/argparse.rst

 ---------------

-Sub-commands
+Subcommands


I think we can revert this change. Changing it would change the generated indices and thus break existing URLs, which is not always a good idea.

picnixz · 2025-12-28T17:52:24Z

Doc/library/argparse.rst

+      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``).


Please wrap lines under 80 characters.

picnixz · 2025-12-28T17:52:38Z

Doc/library/argparse.rst

+      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


Suggested change

All other keyword arguments are passed directly to the

All other keyword arguments are passed directly to the

picnixz · 2025-12-28T17:52:43Z

Doc/library/argparse.rst

+      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.


Suggested change

This returned :class:`!ArgumentParser` object can be modified as usual.

picnixz · 2025-12-28T17:53:00Z

Doc/library/argparse.rst

   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


Revert those unrelated changes. Or more generally, why was this changed?

picnixz · 2025-12-28T17:53:37Z

Doc/library/argparse.rst

-   *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)


Why do we have a duplicated entry here?

picnixz · 2025-12-28T17:54:19Z

Doc/library/argparse.rst

-      >>> parser.parse_args(['fly'])  # doctest: +SKIP
-      chicken.py: warning: command 'fly' is deprecated
-      Namespace()
+      The help argument provides a short description for this subcommand.


Merge the documentation but chose whether to place it here or elsewhere. It doesn't make sense to have duplicated text. As for the examples, either put them below the documented method or in a dedicated section.

picnixz · 2025-12-28T17:54:56Z

Doc/library/argparse.rst

   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


Why was this changed?

bedevere-app · 2025-12-28T17:55:24Z

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 I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Krishna-web-hub added 6 commits October 24, 2025 20:55

pythongh-140281: Doc: Update free-threading how-to

810fde1

pythongh-140281: Doc: Update free-threading how-to

b9ca059

Merge branch 'main' into doc-fix-140281

bfbf864

Fix trailing whitespace

16a1c46

Merge branch 'doc-fix-140281' of https://github.com/Krishna-web-hub/c…

639865d

…python into doc-fix-140281

doc fixing of the cpython fixes#84116

3f0aa48

Krishna-web-hub requested a review from savannahostrowski as a code owner October 25, 2025 09:47

bedevere-app bot added the docs Documentation in the Doc dir label Oct 25, 2025

github-project-automation bot added this to Docs PRs Oct 25, 2025

bedevere-app bot mentioned this pull request Oct 25, 2025

argparse: help parameter not documented in add_subparsers().add_parser #84116

Open

bedevere-app bot added the awaiting review label Oct 25, 2025

github-project-automation bot moved this to Todo in Docs PRs Oct 25, 2025

Docs: Document help and aliases for argparse.add_parser() (pythongh-8…

343648b

…4116)

Krishna-web-hub force-pushed the doc-fix-84116 branch from 57a35b9 to 343648b Compare October 25, 2025 10:16

StanFromIreland changed the title ~~Doc fix 84116Docs: Document help and aliases for argparse.add_parser() (gh-84116) #84116~~ gh-84116: Docs: Document help and aliases for argparse.add_parser() Oct 25, 2025

Docs: Document help and aliases for argparse.add_parser() (pythongh-8…

4b07ba3

…4116)

StanFromIreland requested changes Oct 25, 2025

View reviewed changes

bedevere-app bot added awaiting core review and removed awaiting review labels Oct 25, 2025

Krishna-web-hub added 9 commits October 25, 2025 16:16

Fix trailing whitespace

8bb4bae

Fix trailing whitespace

3361447

Fix trailing whitespace

100207d

Fix trailing whitespace

0f27e63

Fix trailing whitespace

7e6102a

Fix trailing whitespace

a76954c

Fix trailing errors

ac2b754

Fix trailing errors and spaces

b08e8ed

Fix docutils formatting, NEWS ref, and trailing whitespace

fa1d877

Krishna-web-hub force-pushed the doc-fix-84116 branch from ce36e2d to 10dffc6 Compare October 25, 2025 13:52

Docs: Update argparse.rst and add NEWS entry

e955fb0

Remove unnecessary NEWS entry

1a5c449

Krishna-web-hub force-pushed the doc-fix-84116 branch from a7913cf to 1a5c449 Compare December 8, 2025 23:32

Krishna-web-hub requested a review from picnixz December 9, 2025 11:56

StanFromIreland added the skip news label Dec 9, 2025

Krishna-web-hub requested review from StanFromIreland and savannahostrowski December 9, 2025 17:44

bedevere-app bot added awaiting change review and removed awaiting changes labels Dec 9, 2025

savannahostrowski requested changes Dec 9, 2025

View reviewed changes

Doc/library/argparse.rst Outdated Show resolved Hide resolved

Doc/library/argparse.rst Outdated Show resolved Hide resolved

Doc/library/argparse.rst Outdated Show resolved Hide resolved

Doc/library/argparse.rst Outdated Show resolved Hide resolved

bedevere-app bot added awaiting changes and removed awaiting change review labels Dec 9, 2025

Fixing the issue as requested

2dd07bb

bedevere-app bot added awaiting change review and removed awaiting changes labels Dec 11, 2025

bedevere-app bot requested a review from savannahostrowski December 11, 2025 18:04

Krishna-web-hub added 3 commits December 27, 2025 01:02

Added the Changes done before.

850c986

done the changes

7f95d28

done the changes#1

18cbbae

Krishna-web-hub requested a review from dreadstache December 28, 2025 17:46

picnixz requested changes Dec 28, 2025

View reviewed changes

bedevere-app bot added awaiting changes and removed awaiting change review labels Dec 28, 2025

	All other keyword arguments are passed directly to the

	All other keyword arguments are passed directly to the

Uh oh!

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

Are you sure you want to change the base?

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

Conversation

Krishna-web-hub commented Oct 25, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Krishna-web-hub commented Dec 9, 2025

Uh oh!

bedevere-app bot commented Dec 9, 2025

Uh oh!

savannahostrowski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bedevere-app bot commented Dec 9, 2025

Uh oh!

Krishna-web-hub commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bedevere-app bot commented Dec 11, 2025

Uh oh!

Krishna-web-hub commented Dec 24, 2025

Uh oh!

Krishna-web-hub commented Dec 28, 2025

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Dec 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Krishna-web-hub commented Oct 25, 2025 •

edited by github-actions bot

Loading

Krishna-web-hub commented Dec 11, 2025 •

edited

Loading