classification
Title: Add "metavar" argument to add_subparsers() in argparse
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: bethard, chris.jerdonek, docs@python, kushal.das, martin.panter, ncoghlan, tshepang
Priority: normal Keywords:

Created on 2012-02-16 23:51 by ncoghlan, last changed 2017-04-10 02:42 by martin.panter.

Messages (4)
msg153516 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2012-02-16 23:51
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.
msg180960 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-01-30 01:52
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
msg180961 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2013-01-30 01:59
Actually, it looks like add_subparsers() may already support passing a metavar argument, but it's just not documented?
msg291404 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-04-10 02:42
Thanks to Issue 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. Issue 29030 (choices vs metavar) may be related.
History
Date User Action Args
2017-04-10 02:42:35martin.pantersetversions: + Python 2.7
nosy: + martin.panter, docs@python

messages: + msg291404

assignee: docs@python
components: + Documentation, - Library (Lib)
2013-01-30 01:59:41chris.jerdoneksetmessages: + msg180961
2013-01-30 01:52:31chris.jerdoneksetmessages: + msg180960
2013-01-30 01:28:53chris.jerdoneksetnosy: + chris.jerdonek
2012-10-14 10:26:35berker.peksagsetversions: + Python 3.4, - Python 3.3
2012-10-09 08:06:08kushal.dassetnosy: + kushal.das
2012-03-31 11:38:24tshepangsetnosy: + tshepang
2012-02-16 23:51:44ncoghlancreate