I'm noticing some things on the argparse help output that can maybe enhanced. Here is a testcase that produces an example output:

#!/usr/bin/python3 -BEOObbs
# coding=utf-8
import argparse
arguments = argparse.ArgumentParser()
arguments.add_argument('-t', '--test1', action = 'store_true', help = 'Description1')
arguments.add_argument('--test2', action = 'store_true', help = 'Description2')
arguments.add_argument('-u', '--test3', choices = ['choice1', 'choice2'], help = 'Description3', nargs = '+')
arguments.parse_args()


- A way to automatically indent names or to give the user a way to control the indentation would make them easier to read. For example --test2 is here under a short option but it would be easier to read if it would have an offset to be directly under --test1.
- The line "-u {choice1,choice2} [{choice1,choice2} ...], --test3 {choice1,choice2} [{choice1,choice2} ...]" shows the choices for every name while they are the same. Maybe they can be shortened to be shown only on the last name like "-u, --test3 {choice1,choice2} [{choice1,choice2} ...]".

I don't recall other issues or discussions about lining up short and long option strings.

Producing a more compact invocation has raised in StackOverflow questions.  I don't recall if there has been bug/issue on the same.

If I recall correctly it isn't hard to identify and change the Formatter method that produces the action invocation.  So such a change could be implemented as a Formatter subclass.  A SO search should produce that.

You can also play with the metavar of an argument to produce a more command invocation.

The formatting of choices has been discussed in other bug/issues. 

The ultimate help formatting method is to SUPPRESS the argument help, and write your own in a (RAW) description.

http://stackoverflow.com/questions/18275023/dont-show-long-options-twice-in-print-help-from-argparse

http://stackoverflow.com/questions/9366369/python-argparse-lots-of-choices-results-in-ugly-help-output

http://stackoverflow.com/questions/23936145/python-argparse-help-message-disable-metavar-for-short-options

http://stackoverflow.com/questions/13479513/how-can-i-get-python-argparse-to-list-choices-only-once

> The formatting of choices has been discussed in other bug/issues.

What was the reason showing the choices only once at default was not chosen?

Formatter _format_action_invocation(self, action) is the key function.  Notice how it treats positionals and optionals separately.  Also it calls

    default = self._get_default_metavar_for_optional(action)
    args_string = self._format_args(action, default)

to get the string that is placed after each option_string.

'choices' are incorporated via the _metavar_formatter() method (through several function calls).  They do not get their own separate consideration.  Tracing this calling stack is not a trivial task.

But if you want custom behavior at this point in the help, _format_action_invocation() is the function to play with.  You could even add the space for a nonexistent short option at this point.


http://bugs.python.org/issue16468 is an example of a 'choices' thread.  Note that a formatted list of choices is also shown in the 'usage' and error messages.  It's about formatting the choices string, not about where to show it.