Repository navigation
Add "metavar" argument to add_subparsers() in argparse #58247
Description
| 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']
Activity
ncoghlan commentedon Feb 16, 2012
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.
cjerdonek commentedon Jan 30, 2013
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
cjerdonek commentedon Jan 30, 2013
Actually, it looks like add_subparsers() may already support passing a metavar argument, but it's just not documented?
vadmium commentedon Apr 10, 2017
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:
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.
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.
Merge branch 'main' into pythongh-58247-fix-subparsers-metavar-docs
SofieTorch commentedon Apr 17, 2026
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
metavarlinked documentation fromadd_subparsersandadd_argumentboth link to the metavar arg under the section foradd_argument. Under the hood, the metavar arg is handled by anActionand inadd_subparsersby a sub action, so the behavior is shared between both methods but each argument is documented only underadd_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 undermetavar. @savannahostrowski , which place do you think would be better? 🤔savannahostrowski commentedon Apr 20, 2026
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?