Synnefo » ./kamaki

Kamaki commands are implemented as python classes, which wear a decorator

called *command*. The decorator lives in *kamaki.cli* and its purpose is to

update the *CommandTree* structure. The *CommandTree* class (

*kamaki.cli.commant_tree*) manages command namespaces for kamaki.

    mygrp1 list all                             //show a list

    mygrp1 list details [--match=<>]            //show list of details

    mygrp2 list all [regular expression] [-l]   //list all subjects

    mygrp2 info <id> [--filter]                 //information on a subject

.. note:: By convention, the names of the groups describe subjects e.g.,

    "server", "network", "container", etc.

Here we get two command groups to implement i.e., *mygrp1* and *mygrp2*,

respectively). The underscore is used to separate command namespaces and should

be considered as a special character in this context.

parameters, no runtime arguments. The second one defines one optional runtime

argument with a value. The third features an optional parameter and an optional

runtime flag argument. The last one is an example of a command with an

obligatory and an optional parameter.

Some examples:

CommandTree manages commands and their namespaces. Each command is stored in

a tree, where each node is a name. A leaf is the rightmost term of a namespace

and contains a pointer to the executable command class.

Here is an example from the actual kamaki command structure, featuring the

commands *file upload*, *file list* and *file info* ::

For that reason, command specification modules should contain a list of

CommandTree objects, named *_commands*. This mechanism allows any interface

.. note:: The name and the description, will later appear in automatically

    created help messages

The *command* decorator mines all the information needed to build namespaces

The first line of the class commend is used as the command short description.

The rest is used as the detailed description.

The argument mechanism is based on the standard argparse module.

checking and syntax control with respect to the semantics of each command.

Still, in most cases, the argument types of the argument package are enough for

most cases.

Each argument object is a run-time argument. Syntax checking happens at the

command specification level, while the type checking is implemented in the

Argument subclasses.

To access run-time arguments, command classes extend the *_command_init*

interface, which implements *__item__* accessors to handle run-time argument

values. In other words, one may get the runtime value of an argument by calling

*self[<argument>]*.

Non-positional required arguments

---------------------------------

By convention, kamaki uses positional arguments for identifiers and

non-positional arguments for everything else. By default, non-positional

arguments are optional. A non-positional argument can explicitly set to be

required at command specification level:

.. code-block:: python

    ...

    @command(_mygrp1_commands)

    class mygrp1_list_details(_command_init):

        """List of details"""

        arguments = dict(

            match=ValueArgument(

                'Filter output to match string', ('-m', --match'))

        )

        required = (match, )

A tupple means "all required", while a list notation means "at least one".

.. tip:: By convention, the main functionality is implemented in a member

    method called *_run*. This allows the separation between syntax and logic.

    For example, an external library may need to call a command without caring

Assume that the command specifications presented so far be stored in a file

named *grps.py*.