python argparse print usage text after description

Question

Is there a way to print usage text after the description text with python argparse? I have my cmd line argparse working, but i would like to print version info before usage info.

Edit:

version: 1.0

usage: blahcmd [-h] [-help] 

some lovely help

Answer 1

The argparse module does not provide any option to add a "prolog". When the help is displayed it always start with usage:. The best you can do is to customize the usage text adding the version number, using the usage parameter when you instantiate the ArgumentParser:

import argparse

parser = argparse.ArgumentParser(usage='Any text you want\n')

Note that the help will still start with usage:.

A dirty workaround that might work is to start the usage message with a \r:

>>> import argparse
>>> usage = '\r{}\nusage: %(prog)s etc.'.format('Version a b'.ljust(len('usage:')))
>>> parser = argparse.ArgumentParser(usage=usage)
>>> parser.parse_args(['-h'])
Version a b
usage:  etc.

optional arguments:
  -h, --help  show this help message and exit

I don't think that this usage of \r is portable. There are probably some terminals where this trick doesn't work. I've ljusted the version string to make sure that when the trick works, the whole usage: string disappears from string and you don't get things like v1.2e: when using short version strings.

Note: you must manually create the whole usage text now.

Answer 2

Here's an ugly hack (see my comment on the original question):

Define your own subclass of HelpFormatter to pass to the parser with the formatter_class option. The subclass should probably override the _format_usage method. This isn't entirely recommended, since the interface for defining your own formatting class was never made public.

from argparse import ArgumentParser, HelpFormatter
from gettext import gettext as _

class VersionedHelp(HelpFormatter):
    def _format_usage(self, usage, actions, groups, prefix=None):
        if prefix is None:
            prefix = _('Version: x.y\n\nusage: ')
        return HelpFormatter._format_usage(self, usage, actions, groups, prefix)

p = ArgumentParser(formatter_class=VersionedHelp)
p.parse_args()

Answer 3

A rough solution is to add the version text to your usage line. It's not perfect (note the extra 'usage' text), but its a start

In [64]: parser=argparse.ArgumentParser(description='description')
# 'usage' parameter just sets the 'usage' attribute
In [67]: parser.usage='version 1.0.1\n'+parser.format_usage()
In [68]: parser.print_help()
usage: version 1.0.1
usage: ipython [-h]

description

optional arguments:
  -h, --help  show this help message and exit

The order of components in the help are determined by the ArgumentParser.format_help method (quoting from the argparse.py file):

def format_help(self):
    formatter = self._get_formatter()

    # usage
    formatter.add_usage(self.usage, self._actions,
                        self._mutually_exclusive_groups)

    # description
    formatter.add_text(self.description)

    # positionals, optionals and user-defined groups
    for action_group in self._action_groups:
        formatter.start_section(action_group.title)
        formatter.add_text(action_group.description)
        formatter.add_arguments(action_group._group_actions)
        formatter.end_section()

    # epilog
    formatter.add_text(self.epilog)

    # determine help from format above
    return formatter.format_help()

I can imagine writing a custom method that adds your version information, e.g.

def format_help(self):
    formatter = self._get_formatter()

    # version info
    formatter.add_text('version 1.0.1')

    # usage
    formatter.add_usage(self.usage, self._actions,
                        self._mutually_exclusive_groups)
    ...

In ipython this function works:

In [74]: def format_help(parser):
    formatter=parser._get_formatter()
    formatter.add_text('version 1.0.1')
    formatter.add_usage(parser.usage, parser._actions, parser._mutually_exclusive_groups)
    formatter.add_text(parser.description)
    return formatter.format_help()
In [75]: print format_help(parser)
version 1.0.1

usage: ipython [-h]

description