Installation¶

Climax is installed with pip:

$ pip install climax

Getting Started¶

The following example should give you a pretty good idea of how climax works:

import climax

@climax.command()
@climax.argument('name', help='the name to repeat')
@climax.argument('--count', type=int, help='how many times to repeat')
def repeat(count, name):
    """This silly program repeats a name the given number of times."""
    for i in range(count):
        print(name)

if __name__ == '__main__':
    repeat()

In the script above, the arguments to the @climax.argument decorator are anything you would send to the ArgumentParser.add_argument method. In fact, climax passes these arguments to it untouched. The @climax.command decorator takes optional arguments, which are passed to the ArgumentParser constructor. For example, to set a custom program name, you can pass prog='my_command_name'.

When you run the above script, you get a functional command line parser:

$ python repeat.py
usage: repeat.py [-h] [--count COUNT] name

The --help option is automatically generated by argparse, from the information passed on the decorators:

$ python repeat.py --help
usage: repeat.py [-h] [--count COUNT] name

This silly program repeats a name the given number of times.

positional arguments:
  name           the name to repeat

optional arguments:
  -h, --help     show this help message and exit
  --count COUNT  how many times to repeat

If you provide valid arguments, then the command function runs:

$ python repeat.py --count 3 foo
foo
foo
foo

And if anything in the command line is incorrect, you get an error:

$ python repeat.py --count not-a-number foo
usage: repeat.py [-h] [--count COUNT] name
repeat.py: error: argument --count: invalid int value: 'not-a-number'

Building Command Groups¶

One of the nicest features of argparse is the ability to build complex command lines by grouping multiple commands under a single top-level parser. Climax support these easily:

import climax

@climax.group()
def main():
    pass

@main.command()
@climax.argument('values', type=int, nargs='+', help='sequence of numbers to add')
def add(values):
    """add numbers"""
    print(sum(values))

@main.command()
@climax.argument('values', type=int, nargs='+', help='sequence of numbers to average')
def avg(values):
    """average numbers"""
    print(sum(values) / len(values))

if __name__ == '__main__':
    main()

Note that to link a command to its parent group, the command decorator is obtained from the group function (i.e. @main.command instead of @climax.command).

Without any arguments, this script generates the following output:

$ python sumavg.py
usage: sumavg.py [-h] {add,avg} ...
sumavg.py: error: too few arguments

The --help now generates information about the group of commands:

$ python sumavg.py --help
usage: sumavg.py [-h] {add,avg} ...

positional arguments:
  {add,avg}
    add       add numbers
    avg       average numbers

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

And each command generates its own help messages as well:

$ python sumavg.py add
usage: sumavg.py add [-h] values [values ...]
sumavg.py add: error: the following arguments are required: values

$ python sumavg.py add --help
usage: sumavg.py add [-h] values [values ...]

positional arguments:
  values      sequence of numbers to add

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

Other Useful Features¶

Options vs. Arguments¶

Argparse does not make a distinction between options and arguments, positional and optional arguments are considered arguments. In climax, the @climax.argument and @climax.option decorators are equivalent, so they can be used according to your preference.

Password Prompts¶

Argparse does not provide any facility to enter passwords securely. Since this is a common need of scripts, climax includes a custom argparse action that adds this functionality:

import climax

@climax.command()
@climax.argument('--username', '-u', help='your username')
@climax.argument('--password', '-p', action=climax.PasswordPrompt,
                 help='prompt for your password')
def login(username, password):
    """Login example."""
    print(username, password)

if __name__ == '__main__':
    login()

When you run this script, the getpass function from the Python standard library is invoked to prompt for the password without echoing what you type:

$ python login.py -u john -p
Password:

Contexts¶

In the command group example above, there is a function associated with the group, called main. If arguments are defined at this level, they will apply to all the commands in the group. When a command is invoked, climax first calls the group function with its arguments, and then calls the appropriate command function.

Consider, for example, a --verbose option, which applies to all commands in a group:

@climax.group()
@climax.argument('--verbose', action='store_true')
def main(verbose):
    return {'verbose': verbose}

After the group function processes its arguments, it may need to communicate some state to the command function that will run after it. For this purpose, the group function can return a dictionary with values that will be sent as arguments into the command function, in addition to the arguments generated by argparse.

To support verbosity, the sum function can then be coded as follows:

@main.command()
@climax.argument('values', type=int, nargs='+', help='sequence of numbers to add')
def add(values, verbose):
    """add numbers"""
    if verbose:
        print('The input values are: ', str(values))
    print(sum(values))

Return Values¶

You have seen in the previous section that the return value from a group function is the context that is passed as arguments to the command function. A command function can also return a value, which is returned to the caller:

import climax

@climax.command()
@climax.argument('--count', type=int, help='how many times to repeat')
@climax.argument('name', help='the name to repeat')
def repeat(count, name):
    """This silly program repeats a name the given number of times."""
    for i in range(count):
        print(name)
    return count

if __name__ == '__main__':
    result = main()
    # result now has the return value from the command

Parents¶

Argparse supports the concept of “parents”, which allows a command to inherit arguments from another command, which is designated as a parent. The purpose of this feature is to avoid duplication when a common set of arguments needs to be applied to several commands.

With climax, the parent feature is available through a parent decorator:

import climax

@climax.parent()
@climax.argument('--count', type=int, help='how many times to repeat')
def repeat()
    pass

@climax.group()
def main():
    pass

@main.command(parents=[repeat])
def foo(count):
    for i in range(count):
        print('foo')

@main.command(parents=[repeat])
@climax.argument('name', help='the name to repeat')
def bar(name, count):
    for i in range(count):
        print(name)

if __name__ == '__main__':
    main()

In this example, both the foo and bar commands accept --count as argument. The function that handles a command that has parents will receive its own arguments combined with those of the parents.

Optional Commands¶

In Python 3.2 and older, argparse requires that a command name is specified when using groups. But argparse versions that ship with Python 3.3 and newer lift that requirement due to a bug that inadvertently slipped. This makes it possible to specify a command line in which no command from the group is selected, something that can sometimes be useful.

If you are using one of the newer Python versions, climax makes group commands required by default, like in the older Python releases. This gives a consistent behavior. To make commands in a group optional, the group can be given the required=False argument:

import climax

@climax.group(required=False)
def main():
    print('this is main')

@main.command()
def cmd()
    print('this is cmd')

With this example, the following two commands are both valid:

$ python main.py cmd
this is main
this is cmd

$ python main.py
this is main

Without setting required=False, the second command would return an error. Note that optional commands do not work in Python releases before 3.3.

Recursive Groups¶

Argparse supports multiple levels of commands and sub-commands. In climax, multiple layers of commands can be built using the familiar decorator syntax. Consider the following example:

@climax.group()
def main():
    pass

@main.group()
def sub1():
    pass

@sub1.command()
def sub1a():
    pass

@sub1.command()
def sub1b():
    pass

@main.command()
def sub2():
    pass

Integration with native argparse parsers¶

Climax’s use of argparse is not magical. In fact, it is possible to attach a regular argparse parser as a command in a climax group, by passing a parser argument to the @command decorator:

@climax.group()
def grp():
    pass

parser = argparse.ArgumentParser('cmd1.py')
parser.add_argument('--repeat', type=int)
parser.add_argument('name')

@grp.command(parser=parser)
def cmd1(repeat, name):
    pass

Or directly to the main command:

import climax

parser = argparse.ArgumentParser('cmd.py')
parser.add_argument('--repeat', type=int)
parser.add_argument('name')


@climax.command(parser=parser)
def cmd(repeat, name):
    pass

The reverse is also possible. If you need to obtain the argparse parser generated by climax to integrate it with another parser or to make custom modifications to it, you can simply obtain it by invoking the parser attribute on the corresponding function. In the above example, grp.parser returns a fully built and ready to use parser.

climax

Navigation

Related Topics