homepage

The title says it all really, but to demostrate: Let's say I'm building a program which takes another command as its argument(s) on the command line, to execute it in a special way or whatever. The natural way to do this then would be something like the following:
 import argparse
 parser = argparse.ArgumentParser()
 parser.add_argument('cmd', nargs='*')
 parser.parse_args()
Which gives the following output with -h:
 usage: nargs.py [-h] [cmd [cmd ...]]
 positional arguments:
 cmd
 optional arguments:
 -h, --help show this help message and exit
Now, let's say I want to have 'command' printed in the help output, but still write the shorter 'cmd' in the code. Naturally I would make use of the metavar feature:
 import argparse
 parser = argparse.ArgumentParser()
 parser.add_argument('cmd', nargs='*', metavar='command')
 parser.parse_args()
So now the help output is:
 usage: nargs.py [-h] [command [command ...]]
 positional arguments:
 command
 optional arguments:
 -h, --help show this help message and exit
That's better, but I don't really want it to say 'command' twice there, it's more like a command and then its arguments. So what about a tuple instead?
 import argparse
 parser = argparse.ArgumentParser()
 parser.add_argument('cmd', nargs='*', metavar=('command', 'arguments'))
 parser.parse_args()
So let's see what happens now with -h:
 Traceback (most recent call last):
 File "/Users/Vasilis/Sources/Tests/nargs.py", line 6, in <module>
 parser.parse_args()
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 1717, in parse_args
 args, argv = self.parse_known_args(args, namespace)
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 1749, in parse_known_args
 namespace, args = self._parse_known_args(args, namespace)
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 1955, in _parse_known_args
 start_index = consume_optional(start_index)
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 1895, in consume_optional
 take_action(action, args, option_string)
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 1823, in take_action
 action(self, namespace, argument_values, option_string)
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 1016, in __call__
 parser.print_help()
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 2348, in print_help
 self._print_message(self.format_help(), file)
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 2325, in format_help
 formatter.add_arguments(action_group._group_actions)
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 272, in add_arguments
 self.add_argument(action)
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 257, in add_argument
 invocations = [get_invocation(action)]
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 535, in _format_action_invocation
 metavar, = self._metavar_formatter(action, default)(1)
 ValueError: too many values to unpack (expected 1)
Hm, that didn't go very well. Perhaps I can try with a single element in the tuple, as the exception seems to suggest:
 import argparse
 parser = argparse.ArgumentParser()
 parser.add_argument('cmd', nargs='*', metavar=('command',))
 parser.parse_args()
Any better?
 Traceback (most recent call last):
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 1334, in add_argument
 self._get_formatter()._format_args(action, None)
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 579, in _format_args
 result = '[%s [%s ...]]' % get_metavar(2)
 TypeError: not enough arguments for format string
 During handling of the above exception, another exception occurred:
 Traceback (most recent call last):
 File "/Users/Vasilis/Sources/Tests/nargs.py", line 5, in <module>
 parser.add_argument('cmd', nargs='*', metavar=('command',))
 File "/usr/local/Cellar/python3/3.4.0/Frameworks/Python.framework/Versions/3.4/lib/python3.4/argparse.py", line 1336, in add_argument
 raise ValueError("length of metavar tuple does not match nargs")
 ValueError: length of metavar tuple does not match nargs
No, not really.
So there you have it. I think the two-element-tuple example should do the right thing (print "[command [arguments ...]]"). But if not, at least *some* kind of tuple should work without raising an exception.
Apart from 3.4, I see precisely the same behaviour with Python 2.7 too. I haven't tested with any other version I'm afraid.

I think is issue was already raised in
http://bugs.python.org/issue14074
argparse allows nargs>1 for positional arguments but doesn't allow metavar to be a tuple

Ah, I did come across that issue when I was searching for prior reports, but somehow it didn't register in my head as being the same thing. Does the fix for that address the behaviour I'm seeing too? If so, feel free to close as a duplicate. Additionally, if that fix is indeed relevant, is there an ETA for it?