Writing Commands

Commands are the central focus of Clap. Even if you’re just writing a plain old application, you will need to use a command if you want to use a Base.

The Command Base Class

The most straightforward way to create a command is to create a subclass of the class Command.

class clap.command.Command

In addition to the run(options, arguments) method, you can (and should) also override:

name

The command’s name.

aliases

An iterable of aliases for the command.

usage

The command’s usage, not including the command name or program name (defaults to [OPTIONS]).

short_desc

A brief (should be < 50 chars) description of the command.

long_desc

If this is not given, the docstring is used. It is the long description of the help, non-word-wrapped. It should explain what the command does in detail.

defaults

The default values for the command’s options. This should be a dictionary. (You can also define a get_defaults() method returning a dictionary of defaults to replace the default defaults.)

interspersed_options

Whether to allow options to be mixed in with the positional arguments. If this is False, the parser will stop accepting options upon the first non-option argument.

The most important part is the options. You can have a static iterable of Option instances named options, as well as an instance method named get_options that returns an iterable. A property named all_options does a union of both.

When a command is added to a base, its set_base() method is called. This sets the base attribute to the given base.

run(options, arguments)

You should override this method to do whatever you want this command to do when it is called from the command line.

Parameters:

• options – A dictionary of option values.
• arguments – A list or tuple of positional arguments.

Shortcuts

You can also use a decorator, command(), to create commands.

clap.command.command(options=(), aliases=(), short_desc='', long_desc='', usage='', name=None, static=True, interspersed_options=False, base_class=<class 'clap.command.Command'>)

This is a magical command decorator. You pass it various options, and it will return a function you can decorate another function with to make it a command.

Parameters:

• options – A list/tuple of options.
• aliases – A list/tuple of aliases for the command.
• short_desc – A brief (< 50 characters) description of the command. If this is DOC, the function’s docstring will be used.
• long_desc – A longer description of the command. If this is DOC, the function’s docstring will be used.
• usage – The command’s usage string. It defaults to [OPTIONS].
• name – The name of the command. If not given, it will be equal to the __name__ of the function.
• interspersed_options – Whether or not to allow interspersed options.
• static – Whether to wrap it in staticmethod() or not, obviating the need to use self in the argument list.
• base_class – The base class to subclass from. The default is Command.

For example:

@command(
    options=(
        Option('l', 'language', argument=True, desc="Language to write "
               "Hello, World in")
    ),
    aliases=('hi',),
    short_desc=DOC,
    long_desc=DOC,
    usage='[OPTIONS] [PERSON]'
)
def hello(options, arguments):
    "Prints 'Hello, world!' or just 'Hello' to a given person"
    if arguments:
        person = arguments[0]
    else:
        person = None
    if options['language'] == 'es':
        print "Hola, %s!" % (person or 'mundo')
    else:
        print "Hello, %s!" % (person or 'world')

clap.command.DOC

An object only used to take descriptions from an object’s docstring.

Usage Errors from Commands

If you want to interrupt the command with a “normal” error message, then raise a ScriptError exception with your message. It will be displayed as a normal usage error would.

exception clap.base.ScriptError(msg, status=1)

If your command encounters an error due to something the user did, raise ScriptError with the error message, like this:

raise ScriptError("can't read from a file and stdin at the same time")

The Base will automatically display it as it would a usage error, without the full traceback listing.

Parameters:

• msg – The message to display to the user. The preferred style is lowercase with no message at the end.
• status – The status code to exit with. The default is 1.