2 .. include:: ../rst_prolog.rst
5 **************************************
6 Extending SAT with additional commands
7 **************************************
12 .. note:: This documentation is for Python_ developers.
15 The salomeTools 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 salomeTools.
18 Here are the basic requirements that must be followed in this file in order to add a command.
23 By adding a file *mycommand.py* in the ``commands`` directory, salomeTools will define a new command named ``mycommand``.
25 In *mycommand.py*, there must be the following method: ::
27 def run(args, runner, logger):
31 In fact, at this point, the command will already be functional.
32 But there are some useful services provided by salomeTools :
34 * You can give some options to your command:
36 .. code-block:: python
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 behavior of my command.')
46 def run(args, runner, logger):
48 (options, args) = parser.parse_args(args)
52 * You can add a *description* method that will display a message when the user will call the help:
55 .. code-block:: python
56 :emphasize-lines: 9,10
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 behavior of my command.')
67 return _("The help of mycommand.")
69 def run(args, runner, logger):
71 (options, args) = parser.parse_args(args)
74 HowTo access salomeTools config and other commands
75 ========================================================
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 salomeTools
80 For example, *runner.cfg.APPLICATION.workdir*
81 contains the root directory of the current application.
83 The *runner* variable gives also access to other commands of salomeTools:
85 .. code-block:: python
87 # as CLI_ 'sat prepare ...'
88 runner.prepare(runner.cfg.VARS.application)
93 The logger variable is an instance of the Logger class.
94 It gives access to the write method.
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.
99 .. code-block:: python
101 logger.write("My message", 3) # 3 as default
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).
110 Here is a *hello* command, file *commands/hello.py*:
112 .. code-block:: python
118 Define all possible options for hello command:
122 parser = src.options.Options()
123 parser.add_option('f', 'french', 'boolean', 'french', "french set hello message in french.")
126 return _("The help of hello.")
128 def run(args, runner, logger):
130 (options, args) = parser.parse_args(args)
132 if not options.french:
133 logger.write('HELLO! WORLD!\n')
135 logger.write('Bonjour tout le monde!\n')
137 A first call of hello:
141 # Get the help of hello:
146 Bonjour tout le monde!