Title: argparse: aliases for positional arguments (subparsers)
Type: enhancement Stage: resolved
Components: Library (Lib) Versions: Python 3.2
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: bethard Nosy List: asampson, bethard, eric.araujo, georg.brandl, lukasz.langa, rhettinger
Priority: release blocker Keywords: patch

Created on 2010-07-12 20:09 by asampson, last changed 2010-12-18 11:26 by bethard. This issue is now closed.

File name Uploaded Description Edit asampson, 2010-07-12 20:09 example creating subparsers with aliases
argparse-aliases.patch asampson, 2010-12-13 02:43 patch version of the above
argparse-aliases.patch asampson, 2010-12-14 00:30 patch including a few tests
argparse-aliases.patch asampson, 2010-12-16 00:14 patch including a space and documentation
argparse-aliases.patch asampson, 2010-12-18 00:25 patch modifying correct parameter ("metavar")
Messages (17)
msg110130 - (view) Author: Adrian Sampson (asampson) Date: 2010-07-12 20:09
The argparse module supports "subparsers," which allow CLI tools to support invocation of subcommands (much like the svn or hg programs). For these subcommands, it is often useful to allow multiple names for the same command. For instance, in Mercurial, "hg blame" does the same thing as "hg annotate".

You should be able to create subparsers with command aliases, like this:
>>> subparsers.add_parser("annotate", aliases=('ann', 'blame'))

The help message for the program should display the aliases alongisde the command names.

I'm attaching an example script that adds an Action to the library to accomplish this. This isn't a patch, but if this approach seems right to other people, I'll turn it into a patch.

Here's this bug on argparse's old tracker:
msg122627 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-28 04:45
It seems to me that this alias functionality should be integrated into the subparsers code, not another action.  Guidelines for patches are at  Thanks in advance.

(Complementary idea for another bug report: Automatically recognize unambiguous shortened commands, see for example “hg d” which expands to “hg diff”.)
msg123858 - (view) Author: Adrian Sampson (asampson) Date: 2010-12-13 02:43
Thanks for the pointer, Éric. Here's a quick patch that integrates the same functionality into the existing subparser class.
msg123866 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-13 09:18
Patch looks good.  Can you add tests for the new functionality?  (This is listed in the link I gave you :)

Note: this code

    if 'aliases' in kwargs:
        aliases = kwargs.pop('aliases')
        aliases = ()

can be shortened to

    aliases = kwargs.pop('aliases', ())
msg123881 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2010-12-13 15:42
+1 on this feature request
msg123911 - (view) Author: Adrian Sampson (asampson) Date: 2010-12-14 00:30
Sorry I'm slow. Here's a new patch that includes tests. I'll also write documentation if that would be helpful, although I'm not very familiar with the style recommendations.
msg123913 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-14 00:34
Thanks for the quick update!

+                1 (1alias1,1alias2)
I think there should be a space after the comma.  Maybe “aliases:” could also be prepended, for clarity.

Help about the docs:
msg124094 - (view) Author: Adrian Sampson (asampson) Date: 2010-12-16 00:14
Great. I've added a simple example to the documentation for argparse. I also added a space to the comma separator in the alias list, but I'm worried that adding 'aliases:' will make the help less readable (especially if every command in a long list has aliases).
msg124095 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2010-12-16 00:36
Georg, be our hero here. I would be disappointed if this missed 3.2 and made us wait another 18 months (or 3 years for Linux distribution inclusion) for that feature.

This feature makes the first edition of argparse in py3k complete in terms of subcommands.
msg124096 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-16 00:43
Looks good and ready to me.

Regarding “alias” in help text, note that Mercurial prints it (using one line for them) but Subversion puts aliases in parentheses just after the main command name, which works very for me (not a beginner).  Stephen, what do you think?
msg124114 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2010-12-16 08:41
Georg, I believe this should go in 3.2.
The alias capability is an essential part
of what subparsers are all about and
these absence of aliases would leave them
partially crippled (i.e. unable to emulate
the likes of svn blame/annotate/praise).

Please approve for the second beta.
msg124215 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2010-12-17 15:47
The patch looks basically okay to me, though this line makes me nervous:

  dest += ' (%s)' % ', '.join(aliases)

Since this is just for help formatting, can't you just modify metavar instead? The dest is the attribute on the namespace where the result should be stored. The metavar is the value that should be displayed in help messages.

As to where the aliases should be printed, I don't have a strong preference. The svn aliases show up when you do a generic "svn help" (but not if you do a "svn help blame") and looks like:

Available subcommands:
   blame (praise, annotate, ann)

The hg aliases show up when you do a "hg help commit" (but not if you do a "hg help") and looks like:

hg commit [OPTION]... [FILE]...

aliases: ci

I guess the patch makes it pretty easy to emulate the svn version.
msg124216 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-12-17 15:49
I can see that this is really useful; approved for beta2 as soon as Steven's issue from the last message is handled.
msg124265 - (view) Author: Adrian Sampson (asampson) Date: 2010-12-18 00:25
Thanks for the suggestion, Steven. I hadn't yet internalized the difference between dest and metavar.

This version of the patch modifies metavar instead. Because it looks like this issue is up for 3.2b2, I've modified NEWS and ACKS (I hope this was the right thing to do).

I also see the logic behind both help styles Steven depicts. If there's any interest, I can implement the other (hg) style or make it an option.
msg124278 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2010-12-18 10:39
Looks good to me.
msg124280 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2010-12-18 10:43
Steven, can you go ahead and apply this?
msg124281 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2010-12-18 11:26
Applied in r87362.
Date User Action Args
2010-12-18 11:26:22bethardsetstatus: open -> closed
nosy: georg.brandl, rhettinger, bethard, eric.araujo, asampson, lukasz.langa
messages: + msg124281

resolution: fixed
stage: resolved
2010-12-18 10:43:13rhettingersetnosy: georg.brandl, rhettinger, bethard, eric.araujo, asampson, lukasz.langa
messages: + msg124280
2010-12-18 10:39:21bethardsetnosy: georg.brandl, rhettinger, bethard, eric.araujo, asampson, lukasz.langa
messages: + msg124278
2010-12-18 00:25:43asampsonsetfiles: + argparse-aliases.patch
nosy: georg.brandl, rhettinger, bethard, eric.araujo, asampson, lukasz.langa
messages: + msg124265
2010-12-17 15:49:39georg.brandlsetpriority: normal -> release blocker

messages: + msg124216
assignee: georg.brandl -> bethard
nosy: georg.brandl, rhettinger, bethard, eric.araujo, asampson, lukasz.langa
2010-12-17 15:47:16bethardsetnosy: georg.brandl, rhettinger, bethard, eric.araujo, asampson, lukasz.langa
messages: + msg124215
2010-12-16 08:41:44rhettingersetassignee: georg.brandl
versions: + Python 3.2, - Python 3.3
messages: + msg124114
nosy: georg.brandl, rhettinger, bethard, eric.araujo, asampson, lukasz.langa
2010-12-16 00:43:19eric.araujosetnosy: georg.brandl, rhettinger, bethard, eric.araujo, asampson, lukasz.langa
messages: + msg124096
2010-12-16 00:36:56lukasz.langasetnosy: + lukasz.langa, georg.brandl
messages: + msg124095
2010-12-16 00:14:53asampsonsetfiles: + argparse-aliases.patch
nosy: rhettinger, bethard, eric.araujo, asampson
messages: + msg124094
2010-12-14 00:34:30eric.araujosetmessages: + msg123913
2010-12-14 00:30:23asampsonsetfiles: + argparse-aliases.patch

messages: + msg123911
2010-12-13 15:42:37rhettingersetnosy: + rhettinger
messages: + msg123881
2010-12-13 09:18:02eric.araujosetmessages: + msg123866
versions: + Python 3.3, - Python 3.2
2010-12-13 02:43:50asampsonsetfiles: + argparse-aliases.patch
keywords: + patch
messages: + msg123858
2010-11-28 04:45:39eric.araujosetnosy: + eric.araujo
messages: + msg122627
2010-07-13 14:54:05r.david.murraysetnosy: + bethard

versions: + Python 3.2, - Python 2.7
2010-07-12 20:09:02asampsoncreate