Package: compago
=============================================================================Project: CompagoCopyright: ©2011,2012 Justin Mohr. All Rights Reserved.=============================================================================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.(see: http://packages.python.org/Flask-Script/)-----------------------------------------------------------------------------Quick Start-----------------------------------------------------------------------------First, install compago with pip, or alternately fetch the sources from Github or PyPI.$ pip install compagoThen, create a python file named "mycommand.py" containing this:import compagoapp = compago.Application()@app.commanddef say_hello(to="world"):print("Hello there, %s" % to)if __name__ == '__main__': app.run()Save the file, and run it thusly:$ python mycommand.pyFor some more in-depth examples, see the /examples folder in the sources.-----------------------------------------------------------------------------Background-----------------------------------------------------------------------------Why Compago?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 ofyour script.- Better, but still messy: just directly pull in sys.argv- Best, but difficult: use optparse or argparseIf 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:myapp.py:@app.commanddef check_host(hostname, username='admin', password='testing123'):'''Do some stuff.'''print "Let's do some junk on %s as user %s." % (hostname, username)Now, the function's arguments (hostname, username, password) will beavailable as command line arguments to your script:$ ./myapp.py check_host localhost --username=root --password=testing234Let's do some junk on localhost as user root.$ ./myapp.py check_host host1.example.comLet's do some junk on host1.example.com as user admin.That's it! No other nasty boilerplate required.-----------------------------------------------------------------------------Installing Compago-----------------------------------------------------------------------------Use pip or easy_install:pip install compagoeasy_install compagoBoom. Done.Or alternately, fetch the source from github:git clone https://github.com/jmohr/compago.git-----------------------------------------------------------------------------Using Compago-----------------------------------------------------------------------------Starting a Compago script is as easy as importing the compago module, andcreating a compago.Application object.import compagoapp = 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:@myapp.commanddef mycommand(say="Hello", name="John Doe"):print "%s, %s." % (say, name)In that example, the arguments "say" and "name" will be available as optionson the command line:python myapp.py --say="What up" --name="Justin Beiber"orpython myapp.py -s "Goodbye" -n "Dude"If the options are not specified, the defaults will be used. One specialtype of option exists, and that is a boolean option:@myapp.commanddef mycommand(debug=False):if debug:print "Lots of great debugging info..."else:print "Terse. Very terse."In this example, the "debug" option is a switch on the command line:python myapp.py --debugIf provided, debug will be set to True. No need to provide a value.You can mix up the argument types, as well:@myapp.commanddef deploy(hostname, username="admin", verbose=True):result = ssh_to(hostname, username=username)if verbose: print resultIt works as you'd expect.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:@myapp.option('-x', '--execute', dest='command')@myapp.option('-U', '--user', dest='username')def run(command, username):with exec_user(username):call(command)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:@myapp.commanddef help_included():'''This command has some help.'''passWhen the user runs "python myapp.py --help", it will show the docstring nextto help_included. Try it!-----------------------------------------------------------------------------Plugins-----------------------------------------------------------------------------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:@myapp.commanddef test_command(name):myapp.logger.info('Hello, {0}!'.format(name))This command will log an INFO message to myapp.py.log (or whatever yourscript is called). By default, logging will not occur unless you call yourscript with the --log option:$ python myapp.py --log test_command JustinYou can also specify --logfile, which will override the default locationof the log file.$ python myapp.py --log --logfile /var/log/myapp.log test_command JustinThe 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:YOUR_NAME: JustinYOUR_EMAIL: justin@example.orgYOUR_BACON_LEVELS:-low-medium-highAnd you call your script thusly:$ python myapp.py --configfile /etc/myapp.confThen, within your commands, you can fetch these config variables:@myapp.commanddef test_command():print myapp.config['YOUR_NAME']# ... etc ...You can disable plugins by overriding Application.default_plugins beforeinstantiating your Application:from compago import ApplicationApplication.default_plugins = []myapp = Application()# ... etc ...### Writing your own pluginsYou 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 isinitializedbefore_command_run(application, command) - called before a command is runafter_command_run(application, command) - called just after a command is runoption_added(application, option) - called after an option is definedcommand_added(application, command) - called after a command is definedFor 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:from compago.plugin import Pluginfrom datetime import datetimeclass TimePlugin(Plugin):def before_command_run(self, application):print datetime.now()def after_command_run(self, application):print datetime.now()Then, to use the plugin in your compago application:from compago import Applicationfrom time_plugin import TimePluginmyapp = Application()myapp.add_plugin(TimePlugin())@myapp.commanddef testing123():passif __name__ == '__main__':myapp.run()Simple as that!-----------------------------------------------------------------------------FAQ-----------------------------------------------------------------------------Q: Why did you write Compago?A: I really liked the way Thor and Flask-Script worked, and I wanted asimilar tool for my plain old Python scripts. And I had way to much timeon my hands.Q: What does Compago mean?A: According to Google Translate -- which is *never* wrong -- compago isLatin for "joint" or "connection".-----------------------------------------------------------------------------TODO-----------------------------------------------------------------------------* Create more helper functions for fun stuff.