Skip to content

Add "metavar" argument to add_subparsers() in argparse #58247

Open
#148671
Open
Add "metavar" argument to add_subparsers() in argparse#58247
#148671
Labels
docsDocumentation in the Doc direasy

Description

@ncoghlan
ncoghlan
opened on Feb 16, 2012
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

Activity

  1. ncoghlan commented on Feb 16, 2012

    @ncoghlan
    ncoghlan
    on Feb 16, 2012
    ContributorAuthor

    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/ directory
    type-featureA feature request or enhancement
    on Feb 16, 2012

  3. cjerdonek commented on Jan 30, 2013

    @cjerdonek
    cjerdonek
    on Jan 30, 2013
    Member

    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
    cjerdonek
    on Jan 30, 2013
    Member

    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
    vadmium
    on Apr 10, 2017
    Member

    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 dir
    and removed
    stdlibStandard 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 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
    SofieTorch
    on Apr 17, 2026
    Contributor

    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
    savannahostrowski
    on Apr 20, 2026
    Member

    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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc direasy

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions