doc/build/html/write_command.html

   1
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6   <head>
   7     <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
   8     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   9     <title>Add a user custom command &#8212; salomeTools 5.0.0dev documentation</title>
  10     <link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
  11     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
  12     <script type="text/javascript" src="_static/documentation_options.js"></script>
  13     <script type="text/javascript" src="_static/jquery.js"></script>
  14     <script type="text/javascript" src="_static/underscore.js"></script>
  15     <script type="text/javascript" src="_static/doctools.js"></script>
  16     <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
  17     <link rel="index" title="Index" href="genindex.html" />
  18     <link rel="search" title="Search" href="search.html" />
  19     <link rel="next" title="src" href="commands/apidoc/modules.html" />
  20     <link rel="prev" title="Command generate" href="commands/generate.html" />
  21
  22   <link rel="stylesheet" href="_static/custom.css" type="text/css" />
  23
  24
  25   <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
  26
  27   </head><body>
  28
  29
  30     <div class="document">
  31       <div class="documentwrapper">
  32         <div class="bodywrapper">
  33           <div class="body" role="main">
  34
  35   <div class="section" id="add-a-user-custom-command">
  36 <h1>Add a user custom command<a class="headerlink" href="#add-a-user-custom-command" title="Permalink to this headline">¶</a></h1>
  37 <div class="section" id="introduction">
  38 <h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
  39 <div class="admonition note">
  40 <p class="first admonition-title">Note</p>
  41 <p class="last">This documentation is for <a class="reference external" href="https://docs.python.org/2.7">Python</a> developers.</p>
  42 </div>
  43 <p>The salomeTools product provides a simple way to develop commands.
  44 The first thing to do is to add a file with <em>.py</em> extension in the <code class="docutils literal notranslate"><span class="pre">commands</span></code> directory of salomeTools.</p>
  45 <p>Here are the basic requirements that must be followed in this file in order to add a command.</p>
  46 </div>
  47 <div class="section" id="basic-requirements">
  48 <h2>Basic requirements<a class="headerlink" href="#basic-requirements" title="Permalink to this headline">¶</a></h2>
  49 <p>By adding a file <em>mycommand.py</em> in the <code class="docutils literal notranslate"><span class="pre">commands</span></code> directory, salomeTools will define a new command named <code class="docutils literal notranslate"><span class="pre">mycommand</span></code>.</p>
  50 <p>In <em>mycommand.py</em>, there must be the following method:</p>
  51 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">runner</span><span class="p">,</span> <span class="n">logger</span><span class="p">):</span>
  52     <span class="c1"># your algorithm ...</span>
  53     <span class="k">pass</span>
  54 </pre></div>
  55 </div>
  56 <p>In fact, at this point, the command will already be functional.
  57 But there are some useful services provided by salomeTools :</p>
  58 <ul class="simple">
  59 <li>You can give some options to your command:</li>
  60 </ul>
  61 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">src</span>
  62
  63 <span class="c1"># Define all possible option for mycommand command :  &#39;sat mycommand &lt;options&gt;&#39;</span>
  64 <span class="n">parser</span> <span class="o">=</span> <span class="n">src</span><span class="o">.</span><span class="n">options</span><span class="o">.</span><span class="n">Options</span><span class="p">()</span>
  65 <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s1">&#39;m&#39;</span><span class="p">,</span> <span class="s1">&#39;myoption&#39;</span><span class="p">,</span> \
  66                   <span class="s1">&#39;boolean&#39;</span><span class="p">,</span> <span class="s1">&#39;myoption&#39;</span><span class="p">,</span> \
  67                   <span class="s1">&#39;My option changes the behavior of my command.&#39;</span><span class="p">)</span>
  68
  69 <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">runner</span><span class="p">,</span> <span class="n">logger</span><span class="p">):</span>
  70     <span class="c1"># Parse the options</span>
  71     <span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
  72     <span class="c1"># algorithm</span>
  73 </pre></div>
  74 </div>
  75 <ul class="simple">
  76 <li>You can add a <em>description</em> method that will display a message when the user will call the help:</li>
  77 </ul>
  78 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span> <span class="nn">src</span>
  79
  80  <span class="c1"># Define all possible option for mycommand command : &#39;sat mycommand &lt;options&gt;&#39;</span>
  81  <span class="n">parser</span> <span class="o">=</span> <span class="n">src</span><span class="o">.</span><span class="n">options</span><span class="o">.</span><span class="n">Options</span><span class="p">()</span>
  82  <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s1">&#39;m&#39;</span><span class="p">,</span> <span class="s1">&#39;myoption&#39;</span><span class="p">,</span> \
  83                    <span class="s1">&#39;boolean&#39;</span><span class="p">,</span> <span class="s1">&#39;myoption&#39;</span><span class="p">,</span> \
  84                    <span class="s1">&#39;My option changes the behavior of my command.&#39;</span><span class="p">)</span>
  85
  86 <span class="hll"> <span class="k">def</span> <span class="nf">description</span><span class="p">():</span>
  87 </span><span class="hll">     <span class="k">return</span> <span class="n">_</span><span class="p">(</span><span class="s2">&quot;The help of mycommand.&quot;</span><span class="p">)</span>
  88 </span>
  89  <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">runner</span><span class="p">,</span> <span class="n">logger</span><span class="p">):</span>
  90      <span class="c1"># Parse the options</span>
  91      <span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
  92      <span class="c1"># algorithm</span>
  93 </pre></div>
  94 </div>
  95 </div>
  96 <div class="section" id="howto-access-salometools-config-and-other-commands">
  97 <h2>HowTo access salomeTools config and other commands<a class="headerlink" href="#howto-access-salometools-config-and-other-commands" title="Permalink to this headline">¶</a></h2>
  98 <p>The <em>runner</em> variable is an python instance of <em>Sat</em> class.
  99 It gives access to <em>runner.cfg</em> which is the data model defined from all
 100 <em>configuration pyconf files</em> of salomeTools
 101 For example, <em>runner.cfg.APPLICATION.workdir</em>
 102 contains the root directory of the current application.</p>
 103 <p>The <em>runner</em> variable gives also access to other commands of salomeTools:</p>
 104 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># as CLI_ &#39;sat prepare ...&#39;</span>
 105 <span class="n">runner</span><span class="o">.</span><span class="n">prepare</span><span class="p">(</span><span class="n">runner</span><span class="o">.</span><span class="n">cfg</span><span class="o">.</span><span class="n">VARS</span><span class="o">.</span><span class="n">application</span><span class="p">)</span>
 106 </pre></div>
 107 </div>
 108 </div>
 109 <div class="section" id="howto-logger">
 110 <h2>HowTo logger<a class="headerlink" href="#howto-logger" title="Permalink to this headline">¶</a></h2>
 111 <p>The logger variable is an instance of the Logger class.
 112 It gives access to the write method.</p>
 113 <p>When this method is called, the message passed as parameter
 114 will be displayed in the terminal and written in an xml log file.</p>
 115 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">logger</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">&quot;My message&quot;</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span> <span class="c1"># 3 as default</span>
 116 </pre></div>
 117 </div>
 118 <p>The second argument defines the level of verbosity
 119 that is wanted for this message.
 120 It has to be between 1 and 5 (the most verbose level).</p>
 121 </div>
 122 <div class="section" id="hello-example">
 123 <h2>HELLO example<a class="headerlink" href="#hello-example" title="Permalink to this headline">¶</a></h2>
 124 <p>Here is a <em>hello</em> command, file <em>commands/hello.py</em>:</p>
 125 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">src</span>
 126
 127 <span class="sd">&quot;&quot;&quot;</span>
 128 <span class="sd">hello.py</span>
 129 <span class="sd">Define all possible options for hello command:</span>
 130 <span class="sd">sat hello &lt;options&gt;</span>
 131 <span class="sd">&quot;&quot;&quot;</span>
 132
 133 <span class="n">parser</span> <span class="o">=</span> <span class="n">src</span><span class="o">.</span><span class="n">options</span><span class="o">.</span><span class="n">Options</span><span class="p">()</span>
 134 <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s1">&#39;f&#39;</span><span class="p">,</span> <span class="s1">&#39;french&#39;</span><span class="p">,</span> <span class="s1">&#39;boolean&#39;</span><span class="p">,</span> <span class="s1">&#39;french&#39;</span><span class="p">,</span> <span class="s2">&quot;french set hello message in french.&quot;</span><span class="p">)</span>
 135
 136 <span class="k">def</span> <span class="nf">description</span><span class="p">():</span>
 137     <span class="k">return</span> <span class="n">_</span><span class="p">(</span><span class="s2">&quot;The help of hello.&quot;</span><span class="p">)</span>
 138
 139 <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="n">args</span><span class="p">,</span> <span class="n">runner</span><span class="p">,</span> <span class="n">logger</span><span class="p">):</span>
 140     <span class="c1"># Parse the options</span>
 141     <span class="p">(</span><span class="n">options</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">(</span><span class="n">args</span><span class="p">)</span>
 142     <span class="c1"># algorithm</span>
 143     <span class="k">if</span> <span class="ow">not</span> <span class="n">options</span><span class="o">.</span><span class="n">french</span><span class="p">:</span>
 144         <span class="n">logger</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">&#39;HELLO! WORLD!</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">)</span>
 145     <span class="k">else</span><span class="p">:</span>
 146         <span class="n">logger</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">&#39;Bonjour tout le monde!</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">)</span>
 147 </pre></div>
 148 </div>
 149 <p>A first call of hello:</p>
 150 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Get the help of hello:</span>
 151 ./sat --help hello
 152
 153 <span class="c1"># To get bonjour</span>
 154 ./sat hello --french
 155 Bonjour tout le monde!
 156
 157 <span class="c1"># To get hello</span>
 158 ./sat hello
 159 HELLO! WORLD!
 160
 161 <span class="c1"># To get the log</span>
 162 ./sat log
 163 </pre></div>
 164 </div>
 165 </div>
 166 </div>
 167
 168
 169           </div>
 170         </div>
 171       </div>
 172       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 173         <div class="sphinxsidebarwrapper">
 174             <p class="logo"><a href="index.html">
 175               <img class="logo" src="_static/sat_v5.0.png" alt="Logo"/>
 176             </a></p>
 177   <h3><a href="index.html">Table Of Contents</a></h3>
 178   <ul>
 179 <li><a class="reference internal" href="#">Add a user custom command</a><ul>
 180 <li><a class="reference internal" href="#introduction">Introduction</a></li>
 181 <li><a class="reference internal" href="#basic-requirements">Basic requirements</a></li>
 182 <li><a class="reference internal" href="#howto-access-salometools-config-and-other-commands">HowTo access salomeTools config and other commands</a></li>
 183 <li><a class="reference internal" href="#howto-logger">HowTo logger</a></li>
 184 <li><a class="reference internal" href="#hello-example">HELLO example</a></li>
 185 </ul>
 186 </li>
 187 </ul>
 188 <div class="relations">
 189 <h3>Related Topics</h3>
 190 <ul>
 191   <li><a href="index.html">Documentation overview</a><ul>
 192       <li>Previous: <a href="commands/generate.html" title="previous chapter">Command generate</a></li>
 193       <li>Next: <a href="commands/apidoc/modules.html" title="next chapter">src</a></li>
 194   </ul></li>
 195 </ul>
 196 </div>
 197   <div role="note" aria-label="source link">
 198     <h3>This Page</h3>
 199     <ul class="this-page-menu">
 200       <li><a href="_sources/write_command.rst.txt"
 201             rel="nofollow">Show Source</a></li>
 202     </ul>
 203    </div>
 204 <div id="searchbox" style="display: none" role="search">
 205   <h3>Quick search</h3>
 206     <div class="searchformwrapper">
 207     <form class="search" action="search.html" method="get">
 208       <input type="text" name="q" />
 209       <input type="submit" value="Go" />
 210       <input type="hidden" name="check_keywords" value="yes" />
 211       <input type="hidden" name="area" value="default" />
 212     </form>
 213     </div>
 214 </div>
 215 <script type="text/javascript">$('#searchbox').show(0);</script>
 216         </div>
 217       </div>
 218       <div class="clearer"></div>
 219     </div>
 220     <div class="footer">
 221       &copy;2018, CEA.
 222
 223       |
 224       Powered by <a href="http://sphinx-doc.org/">Sphinx 1.7.3</a>
 225       &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
 226
 227       |
 228       <a href="_sources/write_command.rst.txt"
 229           rel="nofollow">Page source</a>
 230     </div>
 231
 232
 233
 234
 235   </body>
 236 </html>