author Alexander Solovyov <>
Wed, 02 Sep 2009 12:50:52 +0300
changeset 80 eacc0c57f0e6
parent 75 2782b2406ba8
child 94 0178aca18a6d
permissions -rw-r--r--
Added tag 0.9.8 for changeset cc24c392fd45

 Opster usage


Configuration of option parser is a list of tuples::

  opts = [('l', 'listen', 'localhost', 'ip to listen on'),
          ('p', 'port', 8000, 'port to listen on'),
          ('d', 'daemonize', False, 'daemonize process'),
          ('', 'pid-file', '', 'name of file to write process ID to')]

Each tuple is a definition of some option, consisting of 4 elements:

 1. short name
 2. long name (read note_)
 3. default value
 4. help string

If a short name renders to False (for example, empty string), then it's not used
at all. Long name is pretended to be available in any case. Default value also
determines how supplied argument should be parsed:

 - function: return value of function called with a specified value is passed
 - integer: value is convert to integer
 - string: value is passed as is
 - list: value is appended to this list
 - boolean/None: ``not default`` is passed and option takes no argument

Usage is easy like that::

  from opster import command

  @command(options=opts, usage='%name [-l HOST] DIR')
  def main(dirname, **opts):
      '''write some help here'''

There is alternative declaration, easier for simple cases::

  @command(usage='%name [-l HOST] DIR')
  def main(dirname,
           listen=('l', 'localhost', 'ip to listen on'),
           pid_file=('', '', 'name of file to write process ID to')):

.. _note:

I think it's easy to understand what's going on here, except that you need to
know that underscores in the long name will be replaced with dash at the command
line. Of course, reverse process happens: if you have option with a dash in long
name in a definition, it will be replaced with underscore when passed to
function. This is done to comply with standarts of writing both console
interfaces and Python application.

After that you can simply call this function as an entry point to your program::

  if __name__ == '__main__':

This will run command line parsing facility, using arguments from
``sys.argv``. ``%name`` will be replaced with ``sys.argv[0]`` (or prepended to
usage string if there is no ``%name``), and rest of arguments will be passed to
command line parser. In case if rest is empty, help will be displayed.

Of course, you can use your function programmatically, supplying list of
arguments to function::

  main('-l /my/dir'.split())

Or, if you need this, you can call this function as usual::

  main('/my/dir', listen='')

In this case no type conversion (which is done upon arguments parsing) will be


It's pretty usual for complex application to have some system of subcommands,
and opster provides facility for handling them. Configuration is simple::

  cmdtable = {
           [('t', 'test', False, 'just test execution')],
           '[-t] ...'),
           [('p', 'pass', False, 'don\'t run the command'),
            ('', 'exit', 0, 'exit with supplied code (default: 0)')],
           '[-p] [--exit value] ...')}

Keys in this dictionary are subcommand names. You can add aliases for
subcommands, separating them with the ``|`` sign (of course, there can be few
aliases). Marking command with preceding ``^`` means that this command should
be included in short help, marking with preceding ``~`` means that this command
should be removed from all command listings (more on that later).

Values here are tuples, consisting of 3 elements:

 1. function, which will handle this subcommand
 2. list of options
 3. usage string (used by help generator)

Your application will also always have ``help`` command, when it uses subcommand

You can define your functions for subcommands like this::

    def simple(*args, **opts):
        '''some descriptive text here

        more help, I'd said a lot of help here ;-)

Naturally ``args`` is a list, containing all arguments to command, and ``opts``
is a dictionary, containing every option.

After definition of all elements you can call command dispatcher (``cmdtable``
is defined earlier)::

  from opster import dispatch

  if __name__ == '__main__':

Example usage, calling ``complex_`` with 5 as an argument for ``exit`` option,
shows that command dispatcher will understand partial names of commands and

  app har --ex 5

But if your program is something like program shown earlier, you can use
shortened api::

  @command(usage='[-t] ...', shortlist=True)
  def simple(somearg,
             test=('t', False, 'just test execution')):

  if __name__ == '__main__':

Every :ref:`@command <api-command>` stores information about decorated function in
special global command table, which allows to call ``dispatch()`` without

Help generation

Help is generated automatically and is available by the ``-h/--help`` command
line option or by ``help`` subcommand (if you're using subcommand system).

It is generated from usage, function docstring and a list of option help
strings, wrapped to length of 70 characters and looks like that::

  > ./ help complex complex: [-p] [--exit value] ...

  That's more complex command indented to do something

      Let's try to do that (what?!)


   -p --pass  don't run the command
      --exit  exit with supplied code (default: 0)
   -h --help  show help

Tips and tricks

There is one thing which may be obvious: it's easy to have "semi-global"
options. If your subcommands (or scripts) tend to have same options in some
cases - for example, few commands (not every) can receive database credentials -
you can define this options in separate list and then add them to command's own
options, i.e.::

  @command(cmd_opts + dbopts)
  def select(**opts):