Wiki

Clone wiki

adama / Home

Commander Adama

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

Creating commands

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

Creating orders

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)

Global options

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
[...]


Global help

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:
[...]


Global version

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

Updated