4 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.
6 In the following, a set of kamaki commands will be implemented::
8 mygrp1 list all //show a list
9 mygrp1 list details [--match=<>] //show list of details
10 mygrp2 list all [regular expression] [-l] //list all subjects
11 mygrp2 info <id> [name] //get information for subject with id
13 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.
15 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.
17 Samples of the expected behavior in one-command mode are following:
19 .. code-block:: console
33 details show a list of details
34 $ kamaki mygrp1 list all
35 ... (mygrp1 client method is called) ...
36 $ kamaki mygrp2 list all 'Z[.]' -l
37 ... (mygrp2 client method is called) ...
40 The above example will be used throughout the present guide for clarification purposes.
42 The CommandTree structure
43 -------------------------
45 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 *store upload*, *store list* and *store info* are stored together as shown bellow::
52 The example used in the present, should result to the creation of two trees::
64 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*
66 A command group information (name, description) is provided at CommandTree structure initialization:
68 .. code-block:: python
70 _mygrp1_commands = CommandTree('mygrp', 'mygrp1 description')
71 _mygrp2_commands = CommandTree('mygrp', 'mygrp2 description')
73 _commands = [_mygrp1_commands, _mygrp2_commands]
78 The *command* decorator mines all the information necessary to build a command specification which is then inserted in a CommanTree instance::
80 class code ---> command() --> updated CommandTree structure
82 Kamaki interfaces make use of this CommandTree structure. Optimizations are possible by using special parameters on the command decorator method.
84 .. code-block:: python
86 def command(cmd_tree, prefix='', descedants_depth=None):
87 """Load a class as a command
88 :param cmd_tree: is the CommandTree to be updated with a new command
89 :param prefix: of the commands allowed to be inserted ('' for all)
90 :param descedants_depth: is the depth of the tree descedants of the
94 Creating a new command specification set
95 ----------------------------------------
97 A command specification developer should create a new module (python file) with as many classes as the command specifications to be offered. Each class should be decorated with *command*.
99 .. code-block:: python
102 _commands = [_mygrp1_commands, _mygrp2_commands]
104 @command(_mygrp1_commands)
105 class mygrp1_list_all():
110 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.
112 Get command description
113 -----------------------
115 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.
117 .. code-block:: python
120 @command(_mygrp2_commands)
122 """get information for subject with id"""
125 Declare run-time argument
126 -------------------------
128 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_cli>`_).
130 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).
132 .. code-block:: python
134 from kamaki.cli.argument import ValueArgument
137 @command(_mygrp1_commands)
138 class mygrp1_list_details():
139 """list of details"""
141 def __init__(self, global_args={}):
142 global_args['match'] = ValueArgument(
143 'Filter results to match string',
145 self.arguments = global_args
147 The main method and command parameters
148 --------------------------------------
150 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::
152 main(self, param) - obligatory parameter <param>
153 main(self, param=None) - optional parameter [param]
154 main(self, param1, param2=42) - <param1> [param2]
155 main(self, param1____param2) - <param1:param2>
156 main(self, param1____param2=[]) - [param1:param2]
157 main(self, param1____param2__) - <param1[:param2]>
158 main(self, param1____param2__='') - [param1[:param2]]
159 main(self, *args) - arbitary number of params [...]
160 main(self, param1____param2, *args) - <param1:param2> [...]
162 The information that can be mined by *command* for each individual command is presented in the following:
164 .. code-block:: python
167 from kamaki.cli.argument import FlagArgument
170 _commands = [_mygrp1_commands, _mygrp2=commands]
173 @command(_mygrp2_commands)
174 class mygrp2_list_all(object):
175 """List all subjects"""
177 def __init__(self, global_args={}):
178 global_args['list'] = FlagArgument(
183 self.arguments = global_args
185 def main(self, reg_exp=None):
188 This will load the following information on the CommandTree:
190 * Syntax (from lines 8,12,19): mygrp list all [reg exp] [-l]
191 * Description (form line 9): List all subjects
192 * Arguments help (from line 13,14): -l: detailed list
197 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*.
199 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.
201 The user has to use a configuration file where the following is added:
212 .. code-block:: console
214 $ kamaki config set mygrp1.cli = grps
215 $ kamaki config set mygrp2.cli = grps
217 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::
220 cli=/another/path/grps.py
222 Summary: create a command set
223 -----------------------------
225 .. code-block:: python
229 from kamaki.cli.command_tree import CommandTree
230 from kamaki.cli.argument import ValueArgument, FlagArgument
234 # Initiallize command trees
236 _mygrp1_commands = CommandTree('mygrp', 'mygrp1 description')
237 _mygrp2_commands = CommandTree('mygrp', 'mygrp2 description')
239 _commands = [_mygrp1_commands, _mygrp2_commands]
242 # Define command specifications
245 @command(_mygrp1_commands)
246 class mygrp1_list_all():
255 @command(_mygrp1_commands)
256 class mygrp1_list_details():
257 """show list of details"""
261 def __init__(self, global_args={})
262 global_args['match'] = ValueArgument(
263 'Filter results to match string',
265 self.arguments = global_args
269 match_value = self.arguments['list'].value
273 @command(_mygrp2_commands)
274 class mygrp2_list_all():
275 """list all subjects"""
279 def __init__(self, global_args={})
280 global_args['match'] = FlagArgument('detailed listing', '-l')
281 self.arguments = global_args
283 def main(self, regular_expression=None):
285 detail_flag = self.arguments['list'].value
290 if regular_expression:
295 @command(_mygrp2_commands)
297 """get information for subject with id"""
301 def main(self, id, name=''):