Add "metavar" argument to add_subparsers() in argparse

[ncoghlan]

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

[ncoghlan]

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]

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]

Actually, it looks like add_subparsers() may already support passing a metavar argument, but it's just not documented?

[vadmium]

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.