The cli package is a framework for making simple, correct command line applications in Python. With cli, you can quickly add standard command line parsing; logging; unit and functional testing; and profiling to your CLI apps. To make it easier to do the right thing, cli wraps all of these tools into a single, consistent application interface.

cli is developed along two branches. The first, ‘default’ (or ‘master’ in git) contains new features and possible bugs – this branch is the active development branch. The second, ‘stable’, contains releases both major and minor as well as bugfixes. If you’d like to help improve cli , take a look at default/master. Otherwise, stick with stable.

If you notice a problem with cli , please report it using the github issue tracker (or, if you have a fix, send a pull request ).

Public repositories for the project are hosted at github , so you can use either git to get a copy of the project’s code and history:

Basic usage¶

While the cli modules provide a simple API for designing your own applications, the default implementations are intended to be flexible enough to cover most use cases. No matter which cli.app.Application you use, the basic pattern is the same: create a callable that does the work, wrap it in an cli.app.Application , add some parameters and call its run() method.

Your callable may be a simple function or a more complex class that implements the __call__() protocol. Either way, it should accept a single app instance as its only argument. It will use this object to interact with the application framework, find out what arguments were passed on the command line, log messages, etc.

You can wrap the callable in one of two ways. First, cli.app.Application can be thought of as a decorator (see PEP 318 for more information). For example:

@cli.app.Application def yourapp ( app ): do_stuff ()

If you need to pass keyword arguments to the application, you can still use the decorator pattern:

@cli.app.CommandLineApp ( argv = [ "-v" ]) def yourapp ( app ): do_stuff ()

If you don’t like decorators (or your interpreter doesn’t support them), you can also simply pass your application callable to the cli.app.Application :

def yourapp ( app ): do_stuff () yourapp = cli . app . CommandLineApp ( yourapp )

Some more complex scripts and applications may benefit from subclassing the cli.app.Application class itself. This approach can help make your code more reusable:

class YourApp ( cli . app . CommandLineApp ): def main ( self ): do_stuff ()

When subclassing cli.app.Application , you’ll likely want to incorporate functionality from the other application classes (like cli.app.CommandLineApp ). To do this, simply call methods from the appropriate mixin classes (like cli.app.CommandLineMixin ) – in fact, this is how the application classes themselves work.

Most of the supplied cli.app.Application implementations support parameters. Parameters determine how your users interact with your program on the command line. To add parameters to your application, call add_param() after you’ve wrapped your callable (or in its setup() method):

yourapp . add_param ( "-v" , "--verbose" , default = 0 , action = "count" , help = "increase the verbosity" , )

The interface here is the same as that implemented by argparse.ArgumentParser . In this case, an verbose attribute will be created on the app.params object with an integer representing the desired verbosity level.

Once you’ve added all the parameters you need (if any – the default implementations include sensible defaults), simply call the run() method on the wrapped callable. It’s best to do this only if your script is actually being run, so shield it with a conditional:

if __name__ == "__main__" : yourapp . run ()

This will allow you to import your application and tweak it programmatically from another script without actually invoking it.