Welcome to the Adama documentation ! Adama is a light and simple command line tool and API to create commands for your Python applications and also subcommands named orders
Imagine a little library that handles todo list. You named it pytodo and want a command that will handle the add order and the done order. Adama can brievely makes it work !
$> adama create_program pytodo $> ls pytodo
This will create the pytodo python script branched on your pytodo workong library. The only argument required by this script is the module's name of your library that must be on your pythonpath. If it doesn't, there is a global option --pythonpath to add a path to the pythonpath during the execution of the script. By default, the adama create_program creates a command with the same name of the module you passed as argument. You can change this by passing the --name option with the specific name you want for the command.
Running pytodo help will show you :
$> pytodo help The "orders" module can not be found under the pytodo package Usage: pytodo order [options] [args] Options: -h, --help show this help message and exit Type 'pytodo help <order>' for help on a specific order. Available orders: No orders available. Type 'adama create_order [options] pytodo <order_name>' to create one
Ok, you didn't create order yet. Next you want to see how to create them for your pytodo command
Adama comes with a create_order order that takes the module and the name of the order you want to create. This will add a new package named "orders" in the root path of your pytodo project.
$> adama create_order pytodo add $> ls /path/to/pytodo/orders add.py __init__.py $> pytodo help [...] Available orders: add help for the order (ex: __doc__) [...]
Now you need to implement the logic of your script. The only code you need to write is the execute(self, args, options) method of the Order class. In fact, your add.py file looks like this :
# -*- coding: utf-8 -*- """ """ from optparse import make_option from adama.commandment import BaseOrder, OrderError class Order(BaseOrder): """ """ options = BaseOrder.options + ( # options for order come here # use make_option # see http://docs.python.org/library/optparse.html#populating-the-parser ) # this constructs a pretty help for the order args = 'args of the order (ex: arg1 arg2)' description = 'help for the order (ex: __doc__)' examples = 'put examples here' def __init__(self, command, module): super(Order, self).__init__(command, module) def execute(self, args, options): # the logic of the order comes here return 0
Customizations on command
You can easily customize your command as :
- creating global options for all your orders
- displaying a global help for your command
- defining the version of your command (command --version)
When several of your orders share the same options, it a good idea to make them global to your command. Adama can do that. You must define a global options list in your pytodo command file :
[...] from adama import sir_yes_sir global_options = ( make_option('-o', '--option', action='store', type='string', dest='option', help='i am the help for the option -o'), ) [...]
So when you type pytodo help, you will see this help:
$> pytodo help [...] Options: -o OPTION, --option=OPTION i am the help for the option -o [...]
You can easily add a brief text help between the usage and the options. Simply add a docstring at the top of your command
#!/usr/bin/env python # -*- coding: utf-8 -*- """This command helps you to add and close todo """ [...]
Now you can see that the help is displayed for the pytodo command
$> pytodo help Usage: pytodo order [options] [args] This command helps you to add and close todo Options: [...]
To enable the --version option, you need to specify a way to pass the version of your application to the command.
$> pytodo --version pytodo 0.4.3