Currently when you specify more than one name for an option (typically short and long versions) each name is listed with its entire arg list. This is annoying for options taking many args or choices, for example:
 
  --type {html,pdf,github,blogger}, -t {html,pdf,github,blogger}

Wouldn't it be better to just show something like:

  --type|-t {html,pdf,github,blogger}

There are 2 issues here - 

- how to make the 'choices' list most compact

- how to make the multiple option strings display (long and short) more compact, regardless of why the argument part is long.

When the choices display is too long, 'metavar' is a handy alternative.  You can still display the choices in the body of the help message, either as an explicit list or with the `%(choices)s` string.  The long choices list will still appear in the error messages.

There are other bug/issues about formatting the choices list.

I have participated in discussions about replacing

    -f FOO, --foo FOO etc 

with

    -f/--foo FOO etc

I'm sure that's been raised on Stackoverflow, but there might also be a bug/issue on the topic.  I'd have to do some search to find those.  I believe it can addressed with a HelpFormatter subclass that changes one method.

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

Once answer demonstrates how to change the Formatter:

class CustomHelpFormatter(argparse.HelpFormatter):
    def _format_action_invocation(self, action):
        if not action.option_strings or action.nargs == 0:
            return super()._format_action_invocation(action)
        default = self._get_default_metavar_for_optional(action)
        args_string = self._format_args(action, default)
        return ', '.join(action.option_strings) + ' ' + args_string

Another answer suggests using metavar=''.

Another SO question with a few more links:

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

Thank you for the tips, Paul. The issue is related to the default behavior but it's always good to know about handy workarounds and extensibility hooks.