Write polished command line applications in a fraction of the time.Guaranteed, or double your money back!

Compago is a framework for simple command-line parsing in Python. Compagoprovides a simple framework and set of decorators to allow you to quicklyand easily define a set of commands within a script. For those familiar withRuby's Thor, Compago fills a similar niche.

This project was inspired by the excellent Flask-Script extension for Flask,but has been entirely rewritten to remove all Flask dependencies.

We've all needed to whip up a quick command line script at some point. Howoften have you wanted to wrap a quick five lines of Python in a script forreuse? Perhaps your little script requires a few arguments to be passed in.In the past, you've had a few options:

- Quick and dirty: just hard code some global variables at the top of your script. - Better, but still messy: just directly pull in sys.argv - Best, but difficult: use optparse or argparse

If you'll be using the script often, option 1 can become a pain very quickly.You have to open the file in a text editor every time you need to change thevalues. And if you ever need to let someone else use the script, option 1 canbe a no-go.

Option 2 is pretty easy, but just directly using sys.argv can get outof control very quickly if you need to pull in more than one command lineargument. And similar to using global variables, expecting other users toalways play nice with the command line args is just asking for trouble.

Using argparse and/or optparse is the most prudent option, but if your scriptis just a few lines of code, setting up all of that boilerplate can add a tonof overhead to your quick script.

With Compago, you have another option. With the use of some simpledecorators, Compago can introspect a function, and set up command linearguments and defaults automagically.

For example, instead of importing optparse, and manually setting up eachoption in an OptionParser, and then taking the output of that and feedingit into your function, you can just define your function thusly:

Starting a Compago script is as easy as importing the compago module, andcreating a compago.Application object.

import compago

app = compago.Application()

An Application has one primary attribute, a name. By default, this will justbe the name of the script (sys.argv[0]), but you can override this if needed.The name will be shown in the help.

-----------------------------------------------------------------------------Commands and Options-----------------------------------------------------------------------------

After you create the application, you need to define some commands. A commandwill be accessible for the user to call on the command line. For example, inthe Quick Start example above, the "check_host" function is a command. Youcan define as many commands as you want in your script.

The @app.command decorator is pretty straight forward in its usage. Simplydecorate a function (with or without arguments), and the function will thenbe available as a "command" on the command line.

Function arguments without a default defined will be "positional" or"required" arguments on the command line. For example, in the check_hostexample above, the "hostname" argument is required on the command line.

If you provide a default for your function argument, it will be an optionon the command line. For example:

Another decorator is available if you need more control over the options.You can define one or more @option decorators on your function, and passin the same arguments that you would pass directly to argparse.ArgumentParserto define an option. See it in action:

This also works about as you'd expect. One thing to note, if you decorateyour function with one or more @option decorators, there is no need to alsodecorate it with @command. This will be done automatically.

Finally, adding help strings to your commands is super easy. Just put adocstring in the function, and that string will be shown when the userruns --help or -h on the command line. For example:

Compago provides a simple plugin framework, which allows you to write yourown plugins to be used in your scripts. Two default plugins are provided,and are turned on by default if you have the compago_plugins moduleinstalled.

The default plugins are LoggingPlugin and ConfigPlugin. LoggingPluginprovides access to Python's logging infrastructure from within your commands.For example:

The second default plugin is the ConfigPlugin. This allows you to readconfig vars from a YAML formatted config file (default location:./myapp.py.conf). This location can be overridden by specifying the--configfile option on the command line.

Any config variables defined in the config file are available within yourcommands as myapp.config['YOUR_KEY']. For example, say you have a config filenamed /etc/myapp.conf:

You can disable plugins by overriding Application.default_plugins beforeinstantiating your Application:

from compago import Application Application.default_plugins = []

myapp = Application()

# ... etc ...

### Writing your own plugins

You can write your own plugins easily. A plugin is a class that inheritsfrom compago.plugin.Plugin. It should override one or more of the hookmethods:

after_application_init(application) - called just after the application is initialized before_command_run(application, command) - called before a command is run after_command_run(application, command) - called just after a command is run option_added(application, option) - called after an option is defined command_added(application, command) - called after a command is defined

For example, let's say we want a simple plugin that prints out the currenttime before and after each command is run. Create a file time_plugin.py: