Synnefo » ./kamaki

Kamaki commands are implemented as python classes, decorated with a special

decorator called *command*. This decorator is a method of kamaki.cli that adds

a new command in a CommandTree structure (kamaki.cli.commant_tree). The later

is used by interfaces to manage kamaki commands.

There are two command sets to implement, namely mygrp1 and mygrp2. The first

will contain two commands, namely list-all and list-details. The second one

will also contain two commands, list-all and info. To avoid ambiguities,

command names should rather be prefixed with the group they belong to, e.g.

mygrp1-list-all and mygrp2-list-all.

The first command has the simplest possible syntax: no parameters, no runtime

arguments. The second accepts an optional runtime argument with a value. The

third features an optional argument and an optional runtime flag argument. The

last is an example of a command with an obligatory and an optional argument.

The above example will be used throughout the present guide.

CommandTree manages a command by its path. Each command is stored in multiple

nodes on the tree, so that the last term is a leaf and the route from root to

that leaf represents the command path. For example the commands *file upload*,

*file list* and *file info* are stored together as shown bellow::

Each command group should be stored on a different CommandTree. For that

reason, command specification modules should contain a list of CommandTree

objects, named *_commands*

A command group information (name, description) is provided at CommandTree

structure initialization:

The *command* decorator mines all the information necessary to build a command

specification which is then inserted in a CommanTree instance::

Kamaki interfaces make use of this CommandTree structure. Optimizations are

possible by using special parameters on the command decorator method.

A list of CommandTree structures must exist in the module scope, with the name

_commands, as shown above. Different CommandTree objects correspond to

different command groups.

The description of each command is the first line of the class commend. The

following declaration of *mygrp2-info* command has a "*get information for

subject with id*" description.

The argument mechanism allows the definition of run-time arguments. Some basic

argument types are defined at the

`argument module <code.html#module-kamaki.cli.argument>`_, but it is not

uncommon to extent these classes in order to achieve specialized type checking

and syntax control (e.g. at

`pithos cli module <code.html#module-kamaki.cli.commands.pithos>`_).

To declare a run-time argument on a specific command, the object class should

initialize a dict called *arguments* , where Argument objects are stored. Each

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

client level, while the type checking is implemented in the Argument code

(thus, many different Argument types might be needed).`

                ('-m', '--match'))

or more usually and elegantly:

.. code-block:: python

    from kamaki.cli.argument import ValueArgument

    @command(_mygrp1_commands)

    class mygrp1_list_details():

    """List of details"""

        arguments = dict(

            match=ValueArgument(

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

        )

Accessing run-time arguments

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

To access run-time arguments, users can use the _command_init interface, which

implements __item__ accessors to handle run-time argument values. In specific,

an instance of _command_init can use brackets to set or read <argument>.value .

.. code-block:: python

    from kamaki.cli.argument import ValueArgument

    from kamaki.cli.commands import _command_init

    @command(_mygrp1_commands)

    class mygrp1_list_details(_command_init):

        """List of details"""

        arguments = dict(

            match=ValueArgument(

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

        )

        def check_runtime_arguments(self):

            ...

            assert self['match'] == self.arguments['match'].value

            ...

The command behavior for each command / class is coded in *main*. The

parameters of *main* method defines the command parameters part of the syntax.

In specific::

The information that can be mined by *command* for each individual command is

presented in the following:

    class mygrp2_list_all():

        arguments = dict(FlagArgument('detailed list', '-l'))

Kamaki will load a command specification *only* if it is set as a configurable

option. To demonstrate this, let the command specifications coded above be

stored in a file named *grps.py*.

The developer should move file *grps.py* to kamaki/cli/commands, the default

place for command specifications, although running a command specification from

a different path is also a kamaki feature.

    [global]

    mygrp1_cli = grps

    mygrp2_cli = grps

or equivalently:

    $ kamaki config set mygrp1_cli grps

    $ kamaki config set mygrp2_cli grps

Command specification modules don't need to live in kamaki/cli/commands,

although this is suggested for uniformity. If a command module exist in another

path::

    [global]

    mygrp_cli = /another/path/grps.py

    from kamaki.cli.commands import _command_init

    class mygrp1_list_all(_command_init):

    class mygrp1_list_details(_command_init):

        arguments = dict(

            match=ValueArgument(

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

        )

            match_value = self['match']

    class mygrp2_list_all(_command_init):

        arguments = dict(

            list=FlagArgument('detailed listing', '-l')

        )

            detail_flag = self['list']

    class mygrp2_info(_command_init):