Description

ncoghlan

opened on Feb 16, 2012

Issue body actions

BPO	14039
Nosy	@ncoghlan, @cjerdonek, @vadmium, @kushaldas

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2012-02-16.23:51:44.012>
labels = ['type-feature', 'docs']
title = 'Add "metavar" argument to add_subparsers() in argparse'
updated_at = <Date 2017-04-10.02:42:35.617>
user = 'https://github.com/ncoghlan'

bugs.python.org fields:

activity = <Date 2017-04-10.02:42:35.617>
actor = 'martin.panter'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2012-02-16.23:51:44.012>
creator = 'ncoghlan'
dependencies = []
files = []
hgrepos = []
issue_num = 14039
keywords = []
message_count = 4.0
messages = ['153516', '180960', '180961', '291404']
nosy_count = 7.0
nosy_names = ['ncoghlan', 'bethard', 'chris.jerdonek', 'docs@python', 'tshepang', 'martin.panter', 'kushal.das']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue14039'
versions = ['Python 2.7', 'Python 3.4']

Linked PRs

• gh-99735: Handle no arguments when using sub-commands in argparse #99736
• gh-58247: clarify metavar behaviour in ArgumentParser.add_subparsers #148671

Activity

1. ncoghlan commented on Feb 16, 2012

   

   ncoghlan

   on Feb 16, 2012

   ContributorAuthor

   More actions

   Currently, using add_subparsers() means that the entire list of subcommands is added to the main usage message. This gets rather unwieldy when there are a lot of subcommands.

   It would be nice if the add_subparsers() method accepted a "metavar" argument that would be substituted into the usage string instead of using the subparser list directly.
2. ncoghlan

   added

   stdlibStandard Library Python modules in the Lib/ directoryStandard Library Python modules in the Lib/ directory

   type-featureA feature request or enhancementA feature request or enhancement

   on Feb 16, 2012
3. cjerdonek commented on Jan 30, 2013

   

   cjerdonek

   on Jan 30, 2013

   Member

   More actions

   Have you tried setting the metavar property on the return value of add_subparsers()? I tried this, and it seems to work.

   It looks like the logic for _metavar_formatter() is the same no matter what the action type (specifically _SubParsersAction in this case):

   http://hg.python.org/cpython/file/e81cad0c722a/Lib/argparse.py#l554
4. cjerdonek commented on Jan 30, 2013

   

   cjerdonek

   on Jan 30, 2013

   Member

   More actions

   Actually, it looks like add_subparsers() may already support passing a metavar argument, but it's just not documented?
5. vadmium commented on Apr 10, 2017

   

   vadmium

   on Apr 10, 2017

   Member

   More actions

   Thanks to bpo-11807, the documentation now lists “metavar”. (However, it looks like a positional argument, rather than keyword-only, and its use seems to be discouraged, but those issues are not specific to “metavar”.)

   Some points specific to “metavar” that I think could be clarified:

   1. Metavar seems to affect the placeholder in the “usage” message, and a heading that precedes a multi-line list of commands, but it does not affect the presentation of the multi-line list itself.

   2. The relationship between the “metavar” parameter of “add_argument” and “add_subparsers” needs clarifying. At the moment, there is a hyperlink, which implies that the description of add_argument’s parameter applies to add_subparsers. But it only discusses the “dest” parameter and CLI options (a.k.a. “optionals”), neither of which make sense in the context of subcommands. bpo-29030 (choices vs metavar) may be related.
6. vadmium

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   and removed

   stdlibStandard Library Python modules in the Lib/ directoryStandard Library Python modules in the Lib/ directory

   on Apr 10, 2017
7. vadmium

   assigned

   docspython

   on Apr 10, 2017
8. ezio-melotti

   transferred this issue fromon Apr 10, 2022
9. erlend-aasland

   added this to Argparse issueson May 19, 2022
10. erlend-aasland

    moved this to Features in Argparse issueson May 19, 2022
11. serhiy-storchaka

    added

    easy

    and removed

    type-featureA feature request or enhancementA feature request or enhancement

    on Sep 28, 2024
12. savannahostrowski

    moved this from Features to Doc issues in Argparse issueson Oct 28, 2025
13. SofieTorch

    added a commit that references this issue on Apr 17, 2026

    Merge branch 'main' into pythongh-58247-fix-subparsers-metavar-docs

    85e5056
14. SofieTorch commented on Apr 17, 2026

    

    SofieTorch

    on Apr 17, 2026

    Contributor

    More actions

    Hi, I created the PR #148671 related to this issue documenting the first point mentioned, but I'm unsure about how the second point could be addressed. The metavar linked documentation from add_subparsers and add_argument both link to the metavar arg under the section for add_argument. Under the hood, the metavar arg is handled by an Action and in add_subparsers by a sub action, so the behavior is shared between both methods but each argument is documented only under add_argument.

    How could it be clarified? I'd suggest either adding a short text under add_subparsers, following the current structure it already has, or adding it under metavar. @savannahostrowski , which place do you think would be better? 🤔
15. savannahostrowski commented on Apr 20, 2026

    

    savannahostrowski

    on Apr 20, 2026

    Member

    More actions

    I think we should land #148671 for this issue and then follow up on the second piece as a separate item, since it could substantially change the structure of the documentation. There may also be options to pare down the docs (I've done this once before and it was quite satisfying).

    We can open a new issue specifically for the add_argument <> add_subparsers cross-reference question. If you're interested, perhaps you could create the new ticket. I can assign it to you and we can discuss options there?
16. savannahostrowski

    linked a pull request that will close this issuegh-58247: clarify metavar behaviour in ArgumentParser.add_subparsers #148671on Jun 5, 2026
17. savannahostrowski

    added 2 commits that reference this issue on Oct 21, 2026

    pythongh-58247: Refine subparser metavar documentation

    8b49ad2

    gh-58247: clarify metavar behaviour in ArgumentParser.add_subparsers (#…

    1bad1f2
18. savannahostrowski

    closed this as completedin #148671on Oct 21, 2026

Issue actions