source: branches/uq/lang/python/README @ 6481

------------------------------------------------------------------------
 Rappture - Rapid APPlication infrastrucTURE
------------------------------------------------------------------------
 The Rappture toolkit provides the basic building blocks for many
 scientific applications.  These blocks can be composed using C++, or
 a high-level language, such as Python.  Having a set of blocks for
 basic I/O, meshing, and numerical methods, a scientist can then
 focus on developing his core algorithm.
------------------------------------------------------------------------
 AUTHORS:
   Michael J. McLennan, Purdue University
   Copyright (c) 2004-2012  HUBzero Foundation, LLC

 See the file "license.terms" for information on usage and
 redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES.
------------------------------------------------------------------------


 INSTALLATION
------------------------------------------------------------------------
 This part of the Rappture toolkit works with Python.  If you need to
 install Python on your system, visit the Download section of the site
 http://www.python.org.

 Assuming you already have Python installed, you can install Rappture
 as follows:

   % cd rappture/python
   % python setup.py install

 This will make Rappture a part of your normal Python installation, so
 you can use it in your own Python scripts, as shown below.


 GETTING STARTED
------------------------------------------------------------------------
 Here is a quick tutorial to get you started using Rappture in your
 Python scripts.

 Rappture applications load their data from a an XML driver file.
 In the tool.xml file, you should have something like

 <command> @tool/path/to/executable @driver </command>

The "@driver" pattern is replaced by the driver xml file generated by
Rappture.  This driver file will contain the values to use for the
parameters in your application.  See
https://nanohub.org/infrastructure/rappture/wiki/rappture_xml_elements
for more information.

The first thing your application should do is load the driver file.

   import Rappture
   rx = Rappture.PyXml('example.xml')

You can see the xml contents by doing
   print rx.xml()

 The "import" statement loads the Rappture toolkit into your Python
 application.  The next line creates a library object representing
 the data in the "example.xml" file.  The last line prints the
 contents of the XML library to the screen.

 You can access values within the XML by using the get() method.
 For example,

   import Rappture
   lib = Rappture.PyXml('example.xml')
   tval = lib.get('group(ambient).number(temp).current')
or alternatively
   tval = lib['group(ambient).number(temp).current'].value

 The get() method follows a path through the XML.  In this example,
 it looks for a <group id="ambient"> tag, and then finds the
 <number id="temp"> tag within it, then finds the <current> tag
 within it, and then returns the text between that and the closing
 </current> tag.

 You can also add new data to the XML by using the put() method.
 For example, we could change the temperature value that we queried
 above as follows:

   tval += 10
   lib.put('group(ambient).number(temp).current', tval)
or
   lib[group(ambient).number(temp).current'] = tval

 This changes the text within the <current>...</current> tag,
 replacing it with the new value, converted to a string if necessary.

 You can also append to an existing value.  For example,

   lib.put('group(ambient).number(temp).current', 'more text', append=1)

 This adds the string 'more text' after the value (tval) within the
 <current>...</current> tag.  Use of append in a loop is not
 recommended because it can be very slow.  It is faster to collect
 data in python and put it all at once.