argparse: aliases for positional arguments (subparsers)

[asampson]

BPO	9234
Nosy	@birkenfeld, @rhettinger, @merwok, @ambv
Files	aliases.py: example creating subparsers with aliases argparse-aliases.patch: patch version of the above argparse-aliases.patch: patch including a few tests argparse-aliases.patch: patch including a space and documentation argparse-aliases.patch: patch modifying correct parameter ("metavar")

^{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 = <Date 2010-12-18.11:26:22.916>
created_at = <Date 2010-07-12.20:09:01.994>
labels = ['type-feature', 'library', 'release-blocker']
title = 'argparse: aliases for positional arguments (subparsers)'
updated_at = <Date 2010-12-18.11:26:22.915>
user = 'https://bugs.python.org/asampson'

bugs.python.org fields:

activity = <Date 2010-12-18.11:26:22.915>
actor = 'bethard'
assignee = 'bethard'
closed = True
closed_date = <Date 2010-12-18.11:26:22.916>
closer = 'bethard'
components = ['Library (Lib)']
creation = <Date 2010-07-12.20:09:01.994>
creator = 'asampson'
dependencies = []
files = ['17971', '20026', '20034', '20073', '20101']
hgrepos = []
issue_num = 9234
keywords = ['patch']
message_count = 17.0
messages = ['110130', '122627', '123858', '123866', '123881', '123911', '123913', '124094', '124095', '124096', '124114', '124215', '124216', '124265', '124278', '124280', '124281']
nosy_count = 6.0
nosy_names = ['georg.brandl', 'rhettinger', 'bethard', 'eric.araujo', 'asampson', 'lukasz.langa']
pr_nums = []
priority = 'release blocker'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue9234'
versions = ['Python 3.2']

[asampson]

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:
http://code.google.com/p/argparse/issues/detail?id=23

[merwok]

It seems to me that this alias functionality should be integrated into the subparsers code, not another action. Guidelines for patches are at http://www.python.org/dev/patches/ Thanks in advance.

(Complementary idea for another bug report: Automatically recognize unambiguous shortened commands, see for example “hg d” which expands to “hg diff”.)

[asampson]

Thanks for the pointer, Éric. Here's a quick patch that integrates the same functionality into the existing subparser class.

[merwok]

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')
    else:
        aliases = ()

can be shortened to

    aliases = kwargs.pop('aliases', ())

[rhettinger]

+1 on this feature request

[asampson]

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.

[merwok]

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: http://docs.python.org/dev/documenting/

[asampson]

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).

[ambv]

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.

[merwok]

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?

[rhettinger]

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.

[bethard]

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:
add
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.