doc/src/write_command.rst

   1
   2 .. include:: ../rst_prolog.rst
   3
   4
   5 **************************************
   6 Extending SAT with additional commands
   7 **************************************
   8
   9 Introduction
  10 ============
  11
  12 .. note:: This documentation is for Python_ developers.
  13
  14
  15 The sat product provides a simple way to develop commands.
  16 The first thing to do is to add a file with *.py* extension in the ``commands`` directory of sat.
  17
  18 Here are the basic requirements that must be followed in this file in order to add a command.
  19
  20 Basic requirements
  21 ==================
  22
  23 By adding a file *mycommand.py* in the ``commands`` directory, sat will define a new command named ``mycommand``.
  24
  25 In *mycommand.py*, there must be the following method: ::
  26
  27     def run(args, runner, logger):
  28         # your algorithm ...
  29         pass
  30
  31 In fact, at this point, the command will already be functional.
  32 But there are some useful services provided by sat :
  33
  34 * You can give some options to your command:
  35
  36 .. code-block:: python
  37
  38     import src
  39
  40     # Define all possible option for mycommand command :  'sat mycommand <options>'
  41     parser = src.options.Options()
  42     parser.add_option('m', 'myoption', \
  43                       'boolean', 'myoption', \
  44                       'My option changes the behaviour of my command.')
  45
  46     def run(args, runner, logger):
  47         # Parse the options
  48         (options, args) = parser.parse_args(args)
  49         # algorithm
  50
  51
  52 * You can add a *description* method that will display a message when the user will call the help:
  53
  54
  55 .. code-block:: python
  56    :emphasize-lines: 9,10
  57
  58     import src
  59
  60     # Define all possible option for mycommand command : 'sat mycommand <options>'
  61     parser = src.options.Options()
  62     parser.add_option('m', 'myoption', \
  63                       'boolean', 'myoption', \
  64                       'My option changes the behaviour of my command.')
  65
  66     def description():
  67         return _("The help of mycommand.")
  68
  69     def run(args, runner, logger):
  70         # Parse the options
  71         (options, args) = parser.parse_args(args)
  72         # algorithm
  73
  74 HowTo access sat config and other commands
  75 ========================================================
  76
  77 The *runner* variable is an python instance of *Sat* class.
  78 It gives access to *runner.cfg* which is the data model defined from all
  79 *configuration pyconf files* of sat
  80 For example, *runner.cfg.APPLICATION.workdir*
  81 contains the root directory of the current application.
  82
  83 The *runner* variable gives also access to other commands of sat
  84
  85 .. code-block:: python
  86
  87     # as CLI_ 'sat prepare ...'
  88     runner.prepare(runner.cfg.VARS.application)
  89
  90 HowTo logger
  91 ==============
  92
  93 The logger variable is an instance of the Logger class.
  94 It gives access to the write method.
  95
  96 When this method is called, the message passed as parameter
  97 will be displayed in the terminal and written in an xml log file.
  98
  99 .. code-block:: python
 100
 101     logger.write("My message", 3) # 3 as default
 102
 103 The second argument defines the level of verbosity
 104 that is wanted for this message.
 105 It has to be between 1 and 5 (the most verbose level).
 106
 107 HELLO example
 108 ==============
 109
 110 Here is a *hello* command, file *commands/hello.py*:
 111
 112 .. code-block:: python
 113
 114     import src
 115
 116     """
 117     hello.py
 118     Define all possible options for hello command:
 119     sat hello <options>
 120     """
 121
 122     parser = src.options.Options()
 123     parser.add_option('f', 'french', 'boolean', 'french', "french set hello message in french.")
 124
 125     def description():
 126         return _("The help of hello.")
 127
 128     def run(args, runner, logger):
 129         # Parse the options
 130         (options, args) = parser.parse_args(args)
 131         # algorithm
 132         if not options.french:
 133             logger.write('HELLO! WORLD!\n')
 134         else:
 135             logger.write('Bonjour tout le monde!\n')
 136
 137 A first call of hello:
 138
 139 .. code-block:: bash
 140
 141     # Get the help of hello:
 142     ./sat --help hello
 143
 144     # To get bonjour
 145     ./sat hello --french
 146     Bonjour tout le monde!
 147
 148     # To get hello
 149     ./sat hello
 150     HELLO! WORLD!
 151
 152     # To get the log
 153     ./sat log
 154
 155
 156
 157
 158