Changes between Version 7 and Version 8 of rappture_python_new_api


Ignore:
Timestamp:
Jan 24, 2017 4:37:33 PM (7 years ago)
Author:
mmh
Comment:

Update and fix formatting

Legend:

Unmodified
Added
Removed
Modified

  • rappture_python_new_api

    v7 v8  
    11{{{
    2 #!rst
    3 ==================================
    4 Writing Scientific Tools in Python
    5 ==================================
    6 
    7 By default, hubs have basic scientific Python modules installed.
    8 A very large collection of scientific Python modules is available in the **anaconda** package.  This package
    9 will be loaded by default in the near future as it will be required by new versions of Rappture.
    10 
    11 If **anaconda** is loaded, the command "conda list" will display the available modules.  If you need modules
    12 that are not installed, request it to be added by filing a Trouble Ticket.
    13 
    14 =======================
    15 New Rappture Python API
    16 =======================
    17 This is a new Python API, which extends the old API, improving
    18 readability and providing a more "Pythonic" feel.  It is an extension
    19 to the old API, which is located `here <https://nanohub.org/infrastructure/rappture/wiki/rappture_python_api>`_
    20 
    21 
    22 ''NOTE:''  Many of the examples included in the Rappture code distribution have been updated to include Python examples using this API.  You can  copy them into your working directory within a nanoHUB workspace from {{{/apps/rappture/current/examples}}}.
    23 
    24 
    25 Opening an XML File
    26 -------------------
    27 
    28 Tools written in Python will be typically called with the name of the output XML file
     2#!html
     3
     4<div class="document" id="new-rappture-python-api">
     5<h1 class="title">New Rappture Python API</h1>
     6
     7<p>This is a new Python API, which extends the old API, improving
     8readability and providing a more &quot;Pythonic&quot; feel.  It is an extension
     9to the old API, which is located <a class="reference external" href="https://nanohub.org/infrastructure/rappture/wiki/rappture_python_api">here</a></p>
     10<div class="section" id="opening-an-xml-file">
     11<h1>Opening an XML File</h1>
     12<p>Tools written in Python will be typically called with the name of the output XML file
    2913as the first command line argument. You will need to open the file with the
    30 PyXml() function.
    31 
    32 .. code-block:: python
    33 
    34     import Rappture
    35     io = Rappture.PyXml(sys.argv[1])
    36 
    37 .. note::
    38 
    39     If you get "AttributeError: 'module' object has no attribute 'PyXml'"
    40     that means you are using an older version of Rappture without the new
    41     API.
    42 
    43 Closing the XML File
    44 --------------------
    45 
    46 When your tool is finished, before it exits, the PyXml instance must
    47 call close().
    48 
    49 .. code-block:: python
    50 
    51     io.close()
    52 
    53 
    54 Getting Started
    55 ---------------
    56 
    57 Here is a simple xml input file we will use for the examples.  Save
    58 it into 'driver.xml'
    59 
    60 .. code-block:: xml
    61 
    62     <run>
    63         <input>
    64             <number id="Ef">
    65                 <units>eV</units>
    66                 <min>-10eV</min>
    67                 <max>10eV</max>
    68                 <default>0eV</default>
    69                 <current>3eV</current>
    70             </number>
    71         </input>
    72     </run>
    73 
    74 Now save this code into a file 'my_tool.py'
    75 
    76 .. code-block:: python
    77 
    78     import Rappture
    79     import sys
    80 
    81     rx = Rappture.PyXml(sys.argv[1])
    82     print rx['input.number(Ef).current'].value
    83     rx.close()
    84 
    85 Running it, we get::
    86 
    87     > python my_tool.py driver.xml
    88     3eV
    89     =RAPPTURE-RUN=>run1431956733728770.xml
    90 
    91 The last line came from Rappture.  It is the output xml filename. This file
     14PyXml() function.</p>
     15<pre class="code python literal-block">
     16<span class="keyword namespace">import</span> <span class="name namespace">Rappture</span>
     17<span class="name">io</span> <span class="operator">=</span> <span class="name">Rappture</span><span class="operator">.</span><span class="name">PyXml</span><span class="punctuation">(</span><span class="name">sys</span><span class="operator">.</span><span class="name">argv</span><span class="punctuation">[</span><span class="literal number integer">1</span><span class="punctuation">])</span>
     18</pre>
     19<div class="note">
     20<p class="first admonition-title">Note</p>
     21<p class="last">If you get &quot;AttributeError: 'module' object has no attribute 'PyXml'&quot;
     22that means you are using an older version of Rappture without the new
     23API.</p>
     24</div>
     25</div>
     26<div class="section" id="closing-the-xml-file">
     27<h1>Closing the XML File</h1>
     28<p>When your tool is finished, before it exits, the PyXml instance must
     29call close().</p>
     30<pre class="code python literal-block">
     31<span class="name">io</span><span class="operator">.</span><span class="name">close</span><span class="punctuation">()</span>
     32</pre>
     33</div>
     34<div class="section" id="getting-started">
     35<h1>Getting Started</h1>
     36<p>Here is a simple xml input file we will use for the examples.  Save
     37it into 'driver.xml'</p>
     38<pre class="code xml literal-block">
     39<span class="name tag">&lt;run&gt;</span>
     40    <span class="name tag">&lt;input&gt;</span>
     41        <span class="name tag">&lt;number</span> <span class="name attribute">id=</span><span class="literal string">&quot;Ef&quot;</span><span class="name tag">&gt;</span>
     42            <span class="name tag">&lt;units&gt;</span>eV<span class="name tag">&lt;/units&gt;</span>
     43            <span class="name tag">&lt;min&gt;</span>-10eV<span class="name tag">&lt;/min&gt;</span>
     44            <span class="name tag">&lt;max&gt;</span>10eV<span class="name tag">&lt;/max&gt;</span>
     45            <span class="name tag">&lt;default&gt;</span>0eV<span class="name tag">&lt;/default&gt;</span>
     46            <span class="name tag">&lt;current&gt;</span>3eV<span class="name tag">&lt;/current&gt;</span>
     47        <span class="name tag">&lt;/number&gt;</span>
     48    <span class="name tag">&lt;/input&gt;</span>
     49<span class="name tag">&lt;/run&gt;</span>
     50</pre>
     51<p>Now save this code into a file 'my_tool.py'</p>
     52<pre class="code python literal-block">
     53<span class="keyword namespace">import</span> <span class="name namespace">Rappture</span>
     54<span class="keyword namespace">import</span> <span class="name namespace">sys</span>
     55
     56<span class="name">rx</span> <span class="operator">=</span> <span class="name">Rappture</span><span class="operator">.</span><span class="name">PyXml</span><span class="punctuation">(</span><span class="name">sys</span><span class="operator">.</span><span class="name">argv</span><span class="punctuation">[</span><span class="literal number integer">1</span><span class="punctuation">])</span>
     57<span class="keyword">print</span> <span class="name">rx</span><span class="punctuation">[</span><span class="literal string single">'input.number(Ef).current'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     58<span class="name">rx</span><span class="operator">.</span><span class="name">close</span><span class="punctuation">()</span>
     59</pre>
     60<p>Running it, we get:</p>
     61<pre class="literal-block">
     62&gt; python my_tool.py driver.xml
     633eV
     64=RAPPTURE-RUN=&gt;run1431956733728770.xml
     65</pre>
     66<p>The last line came from Rappture.  It is the output xml filename. This file
    9267is the driver file, plus any changes your tool made (in this case, none) and
    93 some additional information about the run, including username, hostname, and time.
    94 
    95 Reading Values
    96 --------------
    97 
    98 The previous example showed the simplest case of reading from the driver file.
     68some additional information about the run, including username, hostname, and time.</p>
     69</div>
     70<div class="section" id="reading-values">
     71<h1>Reading Values</h1>
     72<p>The previous example showed the simplest case of reading from the driver file.
    9973The driver file is in XML format.  Each node in an XML file can contain either
    10074information or other nodes.  Nodes are specified by their path relative to the
    101 root or other nodes.  If you try this:
    102 
    103 .. code-block:: python
    104 
    105     print io['input.number(Ef).current']
    106 
    107 You will get a node reference, which looks something like::
    108 
    109     <Rappture.library object at 0x7fa9c3c3e168>['input.number(Ef).current']
    110 
    111 If you want the value at that path, you must ask for it by using the "value" method.
    112 
    113 .. code-block:: python
    114 
    115     print io['input.number(Ef).current'].value
    116 
    117 Outputs::
    118 
    119     3eV
    120 
    121 Nodes are very useful because the allow us to use shorter, more readable
     75root or other nodes.  If you try this:</p>
     76<pre class="code python literal-block">
     77<span class="keyword">print</span> <span class="name">io</span><span class="punctuation">[</span><span class="literal string single">'input.number(Ef).current'</span><span class="punctuation">]</span>
     78</pre>
     79<p>You will get a node reference, which looks something like:</p>
     80<pre class="literal-block">
     81&lt;Rappture.library object at 0x7fa9c3c3e168&gt;['input.number(Ef).current']
     82</pre>
     83<p>If you want the value at that path, you must ask for it by using the &quot;value&quot; method.</p>
     84<pre class="code python literal-block">
     85<span class="keyword">print</span> <span class="name">io</span><span class="punctuation">[</span><span class="literal string single">'input.number(Ef).current'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     86</pre>
     87<p>Outputs:</p>
     88<pre class="literal-block">
     893eV
     90</pre>
     91<p>Nodes are very useful because the allow us to use shorter, more readable
    12292path names.  For example if you want to read all the information about
    123 variable 'Ef' from the driver file:
    124 
    125 .. code-block:: python
    126 
    127     ef = io['input.number(Ef)']
    128     print ef['units'].value
    129     print ef['min'].value
    130     print ef['max'].value
    131     print ef['default'].value
    132     print ef['current'].value
    133 
    134 Outputs::
    135 
    136     eV
    137     -10eV
    138     10eV
    139     0eV
    140     3eV
    141 
    142 You can also ask for the pathname of the node.
    143 
    144 .. code-block:: python
    145 
    146     ef = io['input.number(Ef)']
    147     print ef['current'].name
    148 
    149 ::
    150 
    151     input.number(Ef).current
    152 
    153 
    154 Converting Values
    155 -----------------
    156 
    157 All values read from the driver file are strings.  Most will have units.
     93variable 'Ef' from the driver file:</p>
     94<pre class="code python literal-block">
     95<span class="name">ef</span> <span class="operator">=</span> <span class="name">io</span><span class="punctuation">[</span><span class="literal string single">'input.number(Ef)'</span><span class="punctuation">]</span>
     96<span class="keyword">print</span> <span class="name">ef</span><span class="punctuation">[</span><span class="literal string single">'units'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     97<span class="keyword">print</span> <span class="name">ef</span><span class="punctuation">[</span><span class="literal string single">'min'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     98<span class="keyword">print</span> <span class="name">ef</span><span class="punctuation">[</span><span class="literal string single">'max'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     99<span class="keyword">print</span> <span class="name">ef</span><span class="punctuation">[</span><span class="literal string single">'default'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     100<span class="keyword">print</span> <span class="name">ef</span><span class="punctuation">[</span><span class="literal string single">'current'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     101</pre>
     102<p>Outputs:</p>
     103<pre class="literal-block">
     104eV
     105-10eV
     10610eV
     1070eV
     1083eV
     109</pre>
     110<p>You can also ask for the pathname of the node.</p>
     111<pre class="code python literal-block">
     112<span class="name">ef</span> <span class="operator">=</span> <span class="name">io</span><span class="punctuation">[</span><span class="literal string single">'input.number(Ef)'</span><span class="punctuation">]</span>
     113<span class="keyword">print</span> <span class="name">ef</span><span class="punctuation">[</span><span class="literal string single">'current'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">name</span>
     114</pre>
     115<pre class="literal-block">
     116input.number(Ef).current
     117</pre>
     118</div>
     119<div class="section" id="converting-values">
     120<h1>Converting Values</h1>
     121<p>All values read from the driver file are strings.  Most will have units.
    158122To use them in your simulation, you will need integers or floating point numbers.
    159123And you must be sure they are in the required units.
    160 We do this by calling Rappture.Units.convert().
    161 
    162 .. code-block:: python
    163 
    164     ef = io['input.number(Ef)']
    165     ef_str = ef['current'].value
    166 
    167     ev = Rappture.Units.convert(ef_str, to="eV", units="off")
    168     print "ev=", ev
    169 
    170     mev = Rappture.Units.convert(ef_str, to="meV", units="off")
    171     print "mev=", mev
    172 
    173 ::
    174 
    175     ev= 3.0
    176     mev= 3000.0
    177 
    178 
    179 Writing Values
    180 --------------
    181 
    182 As with reading, we use nodes and pathnames.  Values are automatically
     124We do this by calling Rappture.Units.convert().</p>
     125<pre class="code python literal-block">
     126<span class="name">ef</span> <span class="operator">=</span> <span class="name">io</span><span class="punctuation">[</span><span class="literal string single">'input.number(Ef)'</span><span class="punctuation">]</span>
     127<span class="name">ef_str</span> <span class="operator">=</span> <span class="name">ef</span><span class="punctuation">[</span><span class="literal string single">'current'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     128
     129<span class="name">ev</span> <span class="operator">=</span> <span class="name">Rappture</span><span class="operator">.</span><span class="name">Units</span><span class="operator">.</span><span class="name">convert</span><span class="punctuation">(</span><span class="name">ef_str</span><span class="punctuation">,</span> <span class="name">to</span><span class="operator">=</span><span class="literal string double">&quot;eV&quot;</span><span class="punctuation">,</span> <span class="name">units</span><span class="operator">=</span><span class="literal string double">&quot;off&quot;</span><span class="punctuation">)</span>
     130<span class="keyword">print</span> <span class="literal string double">&quot;ev=&quot;</span><span class="punctuation">,</span> <span class="name">ev</span>
     131
     132<span class="name">mev</span> <span class="operator">=</span> <span class="name">Rappture</span><span class="operator">.</span><span class="name">Units</span><span class="operator">.</span><span class="name">convert</span><span class="punctuation">(</span><span class="name">ef_str</span><span class="punctuation">,</span> <span class="name">to</span><span class="operator">=</span><span class="literal string double">&quot;meV&quot;</span><span class="punctuation">,</span> <span class="name">units</span><span class="operator">=</span><span class="literal string double">&quot;off&quot;</span><span class="punctuation">)</span>
     133<span class="keyword">print</span> <span class="literal string double">&quot;mev=&quot;</span><span class="punctuation">,</span> <span class="name">mev</span>
     134</pre>
     135<pre class="literal-block">
     136ev= 3.0
     137mev= 3000.0
     138</pre>
     139</div>
     140<div class="section" id="writing-values">
     141<h1>Writing Values</h1>
     142<p>As with reading, we use nodes and pathnames.  Values are automatically
    183143converted into apropriate strings.  You can check this by reading the value
    184144or inspecting the generated xml.  The generated xml is available in the
    185 output xml file, or you can call the xml() method.
    186 
    187 .. code-block:: python
    188 
    189     h1 = io['output.histogram(example1)']
    190     h1['about.label'] = 'Name Value Histogram'
    191 
    192     labels = ['Tigers', 'Bears', 'Lions', 'Monkeys', 'Hawks',
    193               'Elephants', 'Foxes', 'Geckos', 'Zebras', 'Giraffes']
    194     values = [5, 7, 3, 15, 8, 6, 18, 4, 9, 2]
    195 
    196     h1['component.xy'] = (labels, values)
    197 
    198     # read back the values to see that the (labels, values)
    199     # tuple has been converted into interleaved strings as required
    200     # by https://nanohub.org/infrastructure/rappture/wiki/rp_xml_ele_histogram
    201     #
    202     print h1['component.xy'].value
    203 
    204     # If we want to see all the generated xml...
    205     print h1.xml()
    206 
    207 ::
    208 
    209     "Tigers" 5
    210     "Bears" 7
    211     "Lions" 3
    212     "Monkeys" 15
    213     "Hawks" 8
    214     "Elephants" 6
    215     "Foxes" 18
    216     "Geckos" 4
    217     "Zebras" 9
    218     "Giraffes" 2
    219 
    220 
    221 And the xml part looks like this:
    222 
    223 .. code-block:: xml
    224 
    225    <histogram id="example1">
    226         <about>
    227             <label>Name Value Histogram</label>
    228         </about>
    229         <component>
    230             <xy>&quot;Tigers&quot; 5
    231     &quot;Bears&quot; 7
    232     &quot;Lions&quot; 3
    233     &quot;Monkeys&quot; 15
    234     &quot;Hawks&quot; 8
    235     &quot;Elephants&quot; 6
    236     &quot;Foxes&quot; 18
    237     &quot;Geckos&quot; 4
    238     &quot;Zebras&quot; 9
    239     &quot;Giraffes&quot; 2</xy>
    240         </component>
    241     </histogram>
    242 
    243 
    244 In general, ints and floats are converted to strings, and lists, tuples, and arrays are converted into interleaved
     145output xml file, or you can call the xml() method.</p>
     146<pre class="code python literal-block">
     147<span class="name">h1</span> <span class="operator">=</span> <span class="name">io</span><span class="punctuation">[</span><span class="literal string single">'output.histogram(example1)'</span><span class="punctuation">]</span>
     148<span class="name">h1</span><span class="punctuation">[</span><span class="literal string single">'about.label'</span><span class="punctuation">]</span> <span class="operator">=</span> <span class="literal string single">'Name Value Histogram'</span>
     149
     150<span class="name">labels</span> <span class="operator">=</span> <span class="punctuation">[</span><span class="literal string single">'Tigers'</span><span class="punctuation">,</span> <span class="literal string single">'Bears'</span><span class="punctuation">,</span> <span class="literal string single">'Lions'</span><span class="punctuation">,</span> <span class="literal string single">'Monkeys'</span><span class="punctuation">,</span> <span class="literal string single">'Hawks'</span><span class="punctuation">,</span>
     151          <span class="literal string single">'Elephants'</span><span class="punctuation">,</span> <span class="literal string single">'Foxes'</span><span class="punctuation">,</span> <span class="literal string single">'Geckos'</span><span class="punctuation">,</span> <span class="literal string single">'Zebras'</span><span class="punctuation">,</span> <span class="literal string single">'Giraffes'</span><span class="punctuation">]</span>
     152<span class="name">values</span> <span class="operator">=</span> <span class="punctuation">[</span><span class="literal number integer">5</span><span class="punctuation">,</span> <span class="literal number integer">7</span><span class="punctuation">,</span> <span class="literal number integer">3</span><span class="punctuation">,</span> <span class="literal number integer">15</span><span class="punctuation">,</span> <span class="literal number integer">8</span><span class="punctuation">,</span> <span class="literal number integer">6</span><span class="punctuation">,</span> <span class="literal number integer">18</span><span class="punctuation">,</span> <span class="literal number integer">4</span><span class="punctuation">,</span> <span class="literal number integer">9</span><span class="punctuation">,</span> <span class="literal number integer">2</span><span class="punctuation">]</span>
     153
     154<span class="name">h1</span><span class="punctuation">[</span><span class="literal string single">'component.xy'</span><span class="punctuation">]</span> <span class="operator">=</span> <span class="punctuation">(</span><span class="name">labels</span><span class="punctuation">,</span> <span class="name">values</span><span class="punctuation">)</span>
     155
     156<span class="comment single"># read back the values to see that the (labels, values)</span>
     157<span class="comment single"># tuple has been converted into interleaved strings as required</span>
     158<span class="comment single"># by https://nanohub.org/infrastructure/rappture/wiki/rp_xml_ele_histogram</span>
     159<span class="comment single">#</span>
     160<span class="keyword">print</span> <span class="name">h1</span><span class="punctuation">[</span><span class="literal string single">'component.xy'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     161
     162<span class="comment single"># If we want to see all the generated xml...</span>
     163<span class="keyword">print</span> <span class="name">h1</span><span class="operator">.</span><span class="name">xml</span><span class="punctuation">()</span>
     164</pre>
     165<pre class="literal-block">
     166&quot;Tigers&quot; 5
     167&quot;Bears&quot; 7
     168&quot;Lions&quot; 3
     169&quot;Monkeys&quot; 15
     170&quot;Hawks&quot; 8
     171&quot;Elephants&quot; 6
     172&quot;Foxes&quot; 18
     173&quot;Geckos&quot; 4
     174&quot;Zebras&quot; 9
     175&quot;Giraffes&quot; 2
     176</pre>
     177<p>And the xml part looks like this:</p>
     178<pre class="code xml literal-block">
     179<span class="name tag">&lt;histogram</span> <span class="name attribute">id=</span><span class="literal string">&quot;example1&quot;</span><span class="name tag">&gt;</span>
     180     <span class="name tag">&lt;about&gt;</span>
     181         <span class="name tag">&lt;label&gt;</span>Name Value Histogram<span class="name tag">&lt;/label&gt;</span>
     182     <span class="name tag">&lt;/about&gt;</span>
     183     <span class="name tag">&lt;component&gt;</span>
     184         <span class="name tag">&lt;xy&gt;</span><span class="name entity">&amp;quot;</span>Tigers<span class="name entity">&amp;quot;</span> 5
     185 <span class="name entity">&amp;quot;</span>Bears<span class="name entity">&amp;quot;</span> 7
     186 <span class="name entity">&amp;quot;</span>Lions<span class="name entity">&amp;quot;</span> 3
     187 <span class="name entity">&amp;quot;</span>Monkeys<span class="name entity">&amp;quot;</span> 15
     188 <span class="name entity">&amp;quot;</span>Hawks<span class="name entity">&amp;quot;</span> 8
     189 <span class="name entity">&amp;quot;</span>Elephants<span class="name entity">&amp;quot;</span> 6
     190 <span class="name entity">&amp;quot;</span>Foxes<span class="name entity">&amp;quot;</span> 18
     191 <span class="name entity">&amp;quot;</span>Geckos<span class="name entity">&amp;quot;</span> 4
     192 <span class="name entity">&amp;quot;</span>Zebras<span class="name entity">&amp;quot;</span> 9
     193 <span class="name entity">&amp;quot;</span>Giraffes<span class="name entity">&amp;quot;</span> 2<span class="name tag">&lt;/xy&gt;</span>
     194     <span class="name tag">&lt;/component&gt;</span>
     195 <span class="name tag">&lt;/histogram&gt;</span>
     196</pre>
     197<p>In general, ints and floats are converted to strings, and lists, tuples, and arrays are converted into interleaved
    245198strings.  If x and y are lists or arrays, then (x, y) or [x, y] would be inserted into the xml as strings
    246 representing x[0], y[0], x[1], y[1], ...
    247 
    248 If the argument is a multidimensional array, it is flattened (serialized)
     199representing x[0], y[0], x[1], y[1], ...</p>
     200<p>If the argument is a multidimensional array, it is flattened (serialized)
    249201in the Fortran order, where the first ('x') index changes fastest.  This is
    250 what Rappture normally requires for fields and meshes.
    251 
    252 See the rappture examples for more information.
    253 
    254 .. note::
    255 
    256     Many of the old examples showed writing values by iterating through lists and appending values
    257     to the node.  That will still work, although it is extremely slow.  The more efficient,
    258     and easier way is to write out entire lists or arrays at once.
    259 
    260 Debugging
    261 ---------
    262 
    263 When debugging a tool that is started by the Rappture GUI(instead of running from the command
     202what Rappture normally requires for fields and meshes.</p>
     203<p>See the rappture examples for more information.</p>
     204<div class="note">
     205<p class="first admonition-title">Note</p>
     206<p class="last">Many of the old examples showed writing values by iterating through lists and appending values
     207to the node.  That will still work, although it is extremely slow.  The more efficient,
     208and easier way is to write out entire lists or arrays at once.</p>
     209</div>
     210</div>
     211<div class="section" id="debugging">
     212<h1>Debugging</h1>
     213<p>When debugging a tool that is started by the Rappture GUI(instead of running from the command
    264214line as we have in these examples), the Rappture GUI will not display output from prints.  You can
    265 redirect output to files for easier debugging by putting this at the top of your code.
    266 
    267 .. code-block:: python
    268 
    269     import sys
    270     sys.stderr = open('tool.err', 'w')
    271     sys.stdout = open('tool.out', 'w')
    272 
    273 
    274 
    275 REFERENCE
    276 =========
    277 
    278 Opening
    279 -------
    280 
    281 - node = Rappture.PyXml(driver_filename)
    282     *driver_filename*
    283         The XML driver file.
    284     *Returns*
    285         A node reference set to the root (top) of the xml.
    286 
    287 Closing
    288 -------
    289 
    290 - node.close()
    291     Writes out the XML.
    292 
    293 Reading
    294 -------
    295 
    296 - node[path]
    297     *node*
    298         A node reference
    299     *path*
    300         A string indicating an XML path.
    301     *Returns*
    302         A new node reference.
    303 
    304 - node[path].value
    305     *node*
    306         A node reference
    307     *path*
    308         A string indicating an XML path.
    309     *Returns*
    310         A string representing the value at the node.
    311 
    312 - node[path].name
    313     *node*
    314         A node reference
    315     *path*
    316         A string indicating an XML path.
    317     *Returns*
    318         The xml path as a string.
    319 
    320 - node.get(path)
    321     [Deprecated. For compatibility with the old API.]
    322 
    323     *node*
    324         A node reference
    325     *path*
    326         A string indicating an XML path.
    327     *Returns*
    328         A string representing the value at the node.
    329 
    330 Writing
    331 -------
    332 
    333 - node[path] = value
    334     Encodes *value* as a string and writes it to the
    335     xml path *path* relative to *node*.
    336 
    337     *node*
    338         A node reference
    339     *path*
    340         A string indicating an XML path.
    341     *value*
    342         Data to write.
    343 
    344 - node.put(path, value, append, type, compress)
    345     Encodes *value* as a string and writes it to the
    346     xml path *path* relative to *node*. This syntax
    347     allows some rare additional options.  The previous
    348     syntax is prefered for readability.
    349 
    350     *node*
    351         A node reference
    352     *path*
    353         A string indicating an XML path.
    354     *value*
    355         Data to write.
    356     *append*
    357         Append this to the current value at the node, if there
    358         is one.  Not recommended. It is far more efficient to
    359         build strings and lists in Python and write them in one
    360         operation.
    361     *type*
    362         'string' (default) or 'file'.  If set to 'file', then *value*
    363         is a filename and the data from it is copied to the xml node.
    364     *compress*
    365         True or False (default). If True, data is gzipped
    366         and base64 encoded.
    367 
    368 Examples:
    369 
    370 .. code-block:: python
    371 
    372     rx.put('current', 'results.txt', type='file')
    373     rx.put('current', 'results.txt', type='file', compress=True)
    374 
    375 
    376 Progress Bar
    377 ------------
    378 
    379 - Rappture.Utils.progress(percent, message)
    380     Updates the Rappture GUI progress bar.
    381 
    382     *percent*
    383         Int or float from 0 to 100 indicating completion percentage.
    384     *message*
    385         String. Message to display.
    386 
    387 
    388 Encoding/Decoding
    389 -----------------
    390 
    391 Some special tools may require manipulation of external binary data.
    392 
    393 
    394 .. code-block:: python
    395 
    396     from Rappture import PyXml, RPENC_Z, RPENC_B64, RPENC_ZB64
    397     from Rappture.encoding import encode, decode, isbinary
    398 
    399     # string with embedded non-ascii char
    400     instr = "foobar\n012\0"
    401 
    402     # compress and uncompress, for testing
    403     x = encode(instr, RPENC_Z)
    404     outstr = decode(x, 0)
    405 
    406     # check
    407     assert instr == outstr
    408     assert isbinary(instr) == True
     215redirect output to files for easier debugging by putting this at the top of your code.</p>
     216<pre class="code python literal-block">
     217<span class="keyword namespace">import</span> <span class="name namespace">sys</span>
     218<span class="name">sys</span><span class="operator">.</span><span class="name">stderr</span> <span class="operator">=</span> <span class="name builtin">open</span><span class="punctuation">(</span><span class="literal string single">'tool.err'</span><span class="punctuation">,</span> <span class="literal string single">'w'</span><span class="punctuation">)</span>
     219<span class="name">sys</span><span class="operator">.</span><span class="name">stdout</span> <span class="operator">=</span> <span class="name builtin">open</span><span class="punctuation">(</span><span class="literal string single">'tool.out'</span><span class="punctuation">,</span> <span class="literal string single">'w'</span><span class="punctuation">)</span>
     220</pre>
     221</div>
     222<hr class="docutils" />
     223<div class="section" id="running-rappture-tools-from-python">
     224<h1>RUNNING RAPPTURE TOOLS FROM PYTHON</h1>
     225<p>If you want to write a Python program that runs Rappture tools, you can do it with the above API and
     226the Rappture Tool class.  For example, to run a published tool named &quot;complam&quot;:</p>
     227<pre class="code python literal-block">
     228<span class="keyword namespace">import</span> <span class="name namespace">Rappture</span>
     229<span class="name">io</span> <span class="operator">=</span> <span class="name">Rappture</span><span class="operator">.</span><span class="name">Tool</span><span class="punctuation">(</span><span class="literal string double">&quot;complam&quot;</span><span class="punctuation">)</span>
     230
     231<span class="comment single"># Set input values for the Complam tool</span>
     232<span class="name">material</span> <span class="operator">=</span> <span class="name">io</span><span class="punctuation">[</span><span class="literal string single">'input.group(tabs).group(Material)'</span><span class="punctuation">]</span>
     233<span class="name">material</span><span class="punctuation">[</span><span class="literal string single">'number(E1).current'</span><span class="punctuation">]</span> <span class="operator">=</span> <span class="name">E1</span> <span class="operator">/</span> <span class="literal number float">1e9</span>
     234<span class="name">material</span><span class="punctuation">[</span><span class="literal string single">'number(E2).current'</span><span class="punctuation">]</span> <span class="operator">=</span> <span class="name">E2</span> <span class="operator">/</span> <span class="literal number float">1e9</span>
     235
     236<span class="comment single"># run the tool</span>
     237<span class="name">io</span><span class="operator">.</span><span class="name">run</span><span class="punctuation">()</span>
     238
     239<span class="comment single"># read the results</span>
     240<span class="name">ex</span> <span class="operator">=</span> <span class="name">io</span><span class="punctuation">[</span><span class="literal string single">'output.number(Ex).current'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     241<span class="name">nu</span> <span class="operator">=</span> <span class="name">io</span><span class="punctuation">[</span><span class="literal string single">'output.number(nu).current'</span><span class="punctuation">]</span><span class="operator">.</span><span class="name">value</span>
     242</pre>
     243<div class="section" id="reference">
     244<h2>REFERENCE</h2>
     245</div>
     246</div>
     247<div class="section" id="opening">
     248<h1>Opening</h1>
     249<ul>
     250<li><dl class="first docutils">
     251<dt>node = Rappture.PyXml(driver_filename)</dt>
     252<dd><dl class="first last docutils">
     253<dt><em>driver_filename</em></dt>
     254<dd><p class="first last">The XML driver file.</p>
     255</dd>
     256<dt><em>Returns</em></dt>
     257<dd><p class="first last">A node reference set to the root (top) of the xml.</p>
     258</dd>
     259</dl>
     260</dd>
     261</dl>
     262</li>
     263</ul>
     264</div>
     265<div class="section" id="closing">
     266<h1>Closing</h1>
     267<ul>
     268<li><dl class="first docutils">
     269<dt>node.close(status=0)</dt>
     270<dd><p class="first last">Sets the output status field and writes out the XML.</p>
     271</dd>
     272</dl>
     273</li>
     274</ul>
     275</div>
     276<div class="section" id="reading">
     277<h1>Reading</h1>
     278<ul>
     279<li><dl class="first docutils">
     280<dt>node[path]</dt>
     281<dd><dl class="first last docutils">
     282<dt><em>node</em></dt>
     283<dd><p class="first last">A node reference</p>
     284</dd>
     285<dt><em>path</em></dt>
     286<dd><p class="first last">A string indicating an XML path.</p>
     287</dd>
     288<dt><em>Returns</em></dt>
     289<dd><p class="first last">A new node reference.</p>
     290</dd>
     291</dl>
     292</dd>
     293</dl>
     294</li>
     295<li><dl class="first docutils">
     296<dt>node[path].value</dt>
     297<dd><dl class="first last docutils">
     298<dt><em>node</em></dt>
     299<dd><p class="first last">A node reference</p>
     300</dd>
     301<dt><em>path</em></dt>
     302<dd><p class="first last">A string indicating an XML path.</p>
     303</dd>
     304<dt><em>Returns</em></dt>
     305<dd><p class="first last">A string representing the value at the node.</p>
     306</dd>
     307</dl>
     308</dd>
     309</dl>
     310</li>
     311<li><dl class="first docutils">
     312<dt>node[path].name</dt>
     313<dd><dl class="first last docutils">
     314<dt><em>node</em></dt>
     315<dd><p class="first last">A node reference</p>
     316</dd>
     317<dt><em>path</em></dt>
     318<dd><p class="first last">A string indicating an XML path.</p>
     319</dd>
     320<dt><em>Returns</em></dt>
     321<dd><p class="first last">The xml path as a string.</p>
     322</dd>
     323</dl>
     324</dd>
     325</dl>
     326</li>
     327<li><dl class="first docutils">
     328<dt>node.get(path)</dt>
     329<dd><p class="first">[Deprecated. For compatibility with the old API.]</p>
     330<dl class="last docutils">
     331<dt><em>node</em></dt>
     332<dd><p class="first last">A node reference</p>
     333</dd>
     334<dt><em>path</em></dt>
     335<dd><p class="first last">A string indicating an XML path.</p>
     336</dd>
     337<dt><em>Returns</em></dt>
     338<dd><p class="first last">A string representing the value at the node.</p>
     339</dd>
     340</dl>
     341</dd>
     342</dl>
     343</li>
     344</ul>
     345</div>
     346<div class="section" id="writing">
     347<h1>Writing</h1>
     348<ul>
     349<li><dl class="first docutils">
     350<dt>node[path] = value</dt>
     351<dd><p class="first">Encodes <em>value</em> as a string and writes it to the
     352xml path <em>path</em> relative to <em>node</em>.</p>
     353<dl class="last docutils">
     354<dt><em>node</em></dt>
     355<dd><p class="first last">A node reference</p>
     356</dd>
     357<dt><em>path</em></dt>
     358<dd><p class="first last">A string indicating an XML path.</p>
     359</dd>
     360<dt><em>value</em></dt>
     361<dd><p class="first last">Data to write.</p>
     362</dd>
     363</dl>
     364</dd>
     365</dl>
     366</li>
     367<li><dl class="first docutils">
     368<dt>node.put(path, value, append, type, compress)</dt>
     369<dd><p class="first">Encodes <em>value</em> as a string and writes it to the
     370xml path <em>path</em> relative to <em>node</em>. This syntax
     371allows some rare additional options.  The previous
     372syntax is prefered for readability.</p>
     373<dl class="last docutils">
     374<dt><em>node</em></dt>
     375<dd><p class="first last">A node reference</p>
     376</dd>
     377<dt><em>path</em></dt>
     378<dd><p class="first last">A string indicating an XML path.</p>
     379</dd>
     380<dt><em>value</em></dt>
     381<dd><p class="first last">Data to write.</p>
     382</dd>
     383<dt><em>append</em></dt>
     384<dd><p class="first last">Append this to the current value at the node, if there
     385is one.  Not recommended. It is far more efficient to
     386build strings and lists in Python and write them in one
     387operation.</p>
     388</dd>
     389<dt><em>type</em></dt>
     390<dd><p class="first last">'string' (default) or 'file'.  If set to 'file', then <em>value</em>
     391is a filename and the data from it is copied to the xml node.</p>
     392</dd>
     393<dt><em>compress</em></dt>
     394<dd><p class="first last">True or False (default). If True, data is gzipped
     395and base64 encoded.</p>
     396</dd>
     397</dl>
     398</dd>
     399</dl>
     400</li>
     401</ul>
     402<p>Examples:</p>
     403<pre class="code python literal-block">
     404<span class="name">rx</span><span class="operator">.</span><span class="name">put</span><span class="punctuation">(</span><span class="literal string single">'current'</span><span class="punctuation">,</span> <span class="literal string single">'results.txt'</span><span class="punctuation">,</span> <span class="name builtin">type</span><span class="operator">=</span><span class="literal string single">'file'</span><span class="punctuation">)</span>
     405<span class="name">rx</span><span class="operator">.</span><span class="name">put</span><span class="punctuation">(</span><span class="literal string single">'current'</span><span class="punctuation">,</span> <span class="literal string single">'results.txt'</span><span class="punctuation">,</span> <span class="name builtin">type</span><span class="operator">=</span><span class="literal string single">'file'</span><span class="punctuation">,</span> <span class="name">compress</span><span class="operator">=</span><span class="name builtin pseudo">True</span><span class="punctuation">)</span>
     406</pre>
     407</div>
     408<div class="section" id="progress-bar">
     409<h1>Progress Bar</h1>
     410<ul>
     411<li><dl class="first docutils">
     412<dt>Rappture.Utils.progress(percent, message)</dt>
     413<dd><p class="first">Updates the Rappture GUI progress bar.</p>
     414<dl class="last docutils">
     415<dt><em>percent</em></dt>
     416<dd><p class="first last">Int or float from 0 to 100 indicating completion percentage.</p>
     417</dd>
     418<dt><em>message</em></dt>
     419<dd><p class="first last">String. Message to display.</p>
     420</dd>
     421</dl>
     422</dd>
     423</dl>
     424</li>
     425</ul>
     426</div>
     427<div class="section" id="encoding-decoding">
     428<h1>Encoding/Decoding</h1>
     429<p>Some special tools may require manipulation of external binary data.</p>
     430<pre class="code python literal-block">
     431<span class="keyword namespace">from</span> <span class="name namespace">Rappture</span> <span class="keyword namespace">import</span> <span class="name">PyXml</span><span class="punctuation">,</span> <span class="name">RPENC_Z</span><span class="punctuation">,</span> <span class="name">RPENC_B64</span><span class="punctuation">,</span> <span class="name">RPENC_ZB64</span>
     432<span class="keyword namespace">from</span> <span class="name namespace">Rappture.encoding</span> <span class="keyword namespace">import</span> <span class="name">encode</span><span class="punctuation">,</span> <span class="name">decode</span><span class="punctuation">,</span> <span class="name">isbinary</span>
     433
     434<span class="comment single"># string with embedded non-ascii char</span>
     435<span class="name">instr</span> <span class="operator">=</span> <span class="literal string double">&quot;foobar</span><span class="literal string escape">\n</span><span class="literal string double">012</span><span class="literal string escape">\0</span><span class="literal string double">&quot;</span>
     436
     437<span class="comment single"># compress and uncompress, for testing</span>
     438<span class="name">x</span> <span class="operator">=</span> <span class="name">encode</span><span class="punctuation">(</span><span class="name">instr</span><span class="punctuation">,</span> <span class="name">RPENC_Z</span><span class="punctuation">)</span>
     439<span class="name">outstr</span> <span class="operator">=</span> <span class="name">decode</span><span class="punctuation">(</span><span class="name">x</span><span class="punctuation">,</span> <span class="literal number integer">0</span><span class="punctuation">)</span>
     440
     441<span class="comment single"># check</span>
     442<span class="keyword">assert</span> <span class="name">instr</span> <span class="operator">==</span> <span class="name">outstr</span>
     443<span class="keyword">assert</span> <span class="name">isbinary</span><span class="punctuation">(</span><span class="name">instr</span><span class="punctuation">)</span> <span class="operator">==</span> <span class="name builtin pseudo">True</span>
     444</pre>
     445</div>
     446</div>
    409447
    410448}}}