homepage

At present, if a number (e.g. 2) of optional positional arguments
are defined (e.g. arg1 and arg2) argparse formats them as follows:
usage: program [arg1] [arg2]
in the usage message. I would like to suggest that a better format would be:
usage: program [arg1 [arg2]]
as this more accurately reflects the way argparse treats them during parsing of the command line.
This formatting would be consistent with the way argparse currently formats a single optional positional argument with nargs='*', namely:
usage: program [arg [arg ...]]

I think this is a good idea, and seems to me more like a bug than a feature request.

I agree that this is a bug in current argparse formatting.
It might be a little difficult to fix though because the current option formatting handles arguments one at a time, and producing something like [arg1 [arg2]] requires some understanding of how arguments interact, which the formatter currently doesn't have.
But patches are certainly welcome.

This is a HelpFormatter function that takes a list of formatted actions, and groups contiguous blocks of optional positional actions. It accounts for optionals (via prefix_chars) and mutually exclusive groups.
Since it assumes 'parts' is a list, rather than string, it works best with the '_format_actions_usage' method in the patch that I submitted to http://bugs.python.org/issue11874 
 def _positionals_regroup(self, parts):
 # change '[arg1] [arg2]' to '[arg1 [arg2]]'
 # apply to a list of formatted arguments
 # don't apply to optionals (with prefix chars) or groups
 chars = getattr(self, 'prefix_chars',set('-'))
 R = _re.compile(r'\] \[(.*)\]')
 result = []
 text = None
 while parts:
 part = parts.pop()
 if part:
 if part[0]=='[' and part[1] not in chars and '|' not in part:
 if text:
 text = ' '.join([part, text])
 else:
 text = part
 if R.search(text):
 text = R.sub(' [\g<1>]]',text)
 else:
 if text:
 result.insert(0,text)
 text = None
 result.insert(0,part)
 if text:
 result.insert(0,text)
 return result
To avoid compatibility issues it could implemented in a subclassed HelpFormatter.

This patch adds a ReGroupHelpFormatter class, which regroups positional arguments in the usage line as discussed before. It builds on the reworked usage formatter in bugs/python.org/issue11874 (which keeps usage as a list longer).
For a complicate parser, usage may look like:
 usage: regp [-h] foo [arg1 [arg2 [arg3 [arg3 ...] [arg4]]]]

This is a testing script for this patch. It is not a unit test.
Example:
 p = argparse.ArgumentParser()
 p.formatter_class = argparse.ReGroupHelpFormatter
 p.add_argument('foo')
 p.add_argument('arg1',nargs='?')
 p.add_argument('arg2',nargs='?')
 a = p.add_argument('arg3',nargs='*')
 b = p.add_argument('arg4', nargs='?')
 # usage: regp [-h] foo [arg1 [arg2 [arg3 [arg3 ...] [arg4]]]]