wiki:rappture_python_api

Version 4 (modified by dkearney, 15 years ago) (diff)

--

Rappture/Python? API

Currently in development are the python bindings to the Rappture Development Toolkit.

Rappture/Python? Function Index:

-- Rappture I/O --

Module Name:
Rappture

The module defines the following object type:
library (path)

Methods defined for Rappture library objects:
element (path, as)
children (path, as)
get (path)
put (path, value, id=None, append=0)
remove (path)
xml ()

-- Rappture Units --

Module Name:
Rappture.Units

The module defines the following object interfaces:
define (unitsName, basis)
defineConv (fromUnit, toUnit, forwConvFxnPtr, backConvFxnPtr)
find (searchName)
makeMetric (newBasis)
convert (fromVal, to, units)

Methods defined for RpUnits objects:
getUnits ()
getUnitsName ()
getExponent ()
convert (toUnit, value)
makeBasis (value)


Code Synopsis & Examples:

library (path)

Purpose:

Create a Rappture I/O object using the xml file located at path as the object reference.

Input Arguments:

  1. path - path of xml file to be opened with Rappture.

Return Value:

Rappture I/O object referencing path as its library.

Notes:

None

element (path, as)

Purpose:

Retrieve the xml object, located at path, from the Rappture I/O library. as represents the form in which the Rappture I/O object should be returned to the caller.

Input Arguments:

  1. path - xml path (location) of the element to be retrieved.
  2. as - .

Return Value:

.

Notes:

  1. .

children (path, as)

Purpose:

Retrieve the children located at path in the DOM xml tree and return the object in the format described by as.

Input Arguments:

  1. path - xml path (location) of the children to be retrieved.
  2. as - format in which to return the children.

Return Value:

Rappture Object describing the children at the xml DOM location path.

Notes:

  1. .

get (path)

Purpose:

.

Input Arguments:

  1. path - xml path (location) of the element to be retrieved.

Return Value:

.

Notes:

  1. .

put (path, value, id=None, append=0)

Purpose:

.

Input Arguments:

.
.

Return Value:

.

Notes:

  1. .

remove (path)

Purpose:

.

Input Arguments:

  1. .

Return Value:

.

Notes:

  1. .

xml ()

Purpose:

Retrieve the xml text of the Rappture I/O Object.

Input Arguments:

None.

Return Value:

Rappture I/O Object holding xml text.

Notes:

  1. .

define (unitsName, basis)

Purpose:

define a unit by the symbol of unitName which has basis identified by the integer unit handle basis.

Input Arguments:

  1. character unitName - character array of the unit symbol.
  2. integer basis - user (handle) reference to the Rappture defined unit representing the basis.

Return Value:

Integer handle representing the unit just defined.

Notes:

  1. a basis of None represents no basis for the unit.
    import Rappture.Units

    meters = Rappture.Units.define("m")

    # meters is a Rappture Units Object.

defineConv (fromUnit, toUnit, forwConvFxnPtr, backConvFxnPtr)

Purpose:

Define how to convert between fromUnit and toUnit using the functions forwConvFxnPtr and backConvFxnPtr. forwConvFxnPtr is the function used to convert from fromUnit to toUnit. backConvFxnPtr is the function used to convert from toUnit to fromUnit.

Input Arguments:

  1. fromUnit - character array of the unit symbol.
  2. toUnit - user (handle) reference to the Rappture defined unit representing the basis.
  3. forwConvFxnPtr - function to convert from fromUnit to toUnit
  4. backConvFxnPtr - function to convert from toUnit to fromUnit

Return Value:

on success, a Rappture Units Object will be returned and the conversion will be stored. None is returned on failure.

Notes:

  1. see also convert(toUnit,value) member function near bottom of page.
    import Rappture.Units

    def m2a(meter):
        return (meter*(1.0e10))

    def a2m(ang):
        return (ang*(1.0e-10))

    meters = Rappture.Units.define("m")
    ang = Rappture.Units.define("A")

    Rappture.Units.defineConv(meters,ang,m2a,a2m)

    

find (searchName)

Purpose:

search the dictionary of stored units for a unit identified by the symbol searchName.

Input Arguments:

  1. searchName - character array representation of the symbol of the unit being searched for.

Return Value:

Rappture Units Object representing the unit being searched for, on success. On Failure, the Python None Object is returned.

Notes:

  1. .
    import Rappture.Units
    
    meters = Rappture.Units.define("m")
    meters2 = Rappture.Units.find("m")

    result = meters2.getUnitsName()

    # result is "m"

makeMetric (newBasis)

Purpose:

Create the metric extentions and conversion functions for the unit newBasis, thus making it a new basis.

Input Arguments:

  1. newBasis - Rapture Units Object.

Return Value:

Return 1 on success. Return 0 on failure.

Notes:

  1. .
    import Rappture.Units
    
    meters = Rappture.Units.define("m")
    Rappture.Units.makeMetric(meters)

    centimeter = Rappture.Units.find("cm")

    result = centimeter.getUnitsName()

    # result is "cm"

convert (fromVal,to,units)

Purpose:

Convert a string, (fromVal) containing a numeric value and option units, to the units specified in the second argument (to).

Input Arguments:

  1. fromVal - String with numeric portion and optional units (ie. "3m" or "3").
  2. to - String name of the units you want to convert to.
  3. units - String "on" or "off" to tell if you want units to show up in the result.

Return Value:

Return converted value as a string if units="on" or double if units="off" on success. Return None on failure. units are set to on by default.

Notes:

  1. .
    import Rappture.Units
    
    result = Rappture.Units.convert("3cm","m")
    # result is "0.03m"

    result = Rappture.Units.convert("300K",to="F", units="off")
    # result is "80.329999999999998"

    result = Rappture.Units.convert("3cm",to="A")
    # result is "3e+08A"

    result = Rappture.Units.convert("3","m")
    # result is "3m"

    result = Rappture.Units.convert("3","m", units="off")
    # result is "3.0"

getUnits ()

Purpose:

Retrieve the base name of the current unit (base without exponent).

Input Arguments:

None.

Return Value:

PyString? contining the base name of the current unit (base without exponent).

Notes:

None.

    import Rappture.Units

    cm_squared = Rappture.Units.define("cm2")

    result = cm_squared.getUnits()

    # result is "cm"
    

getUnitsName ()

Purpose:

Retrieve the whole name of the current unit (base and exponent).

Input Arguments:

None.

Return Value:

PyString? contining the whole name of the current unit (base and exponent).

Notes:

None.

    import Rappture.Units

    cm_squared = RapptureUnits.define("cm2")

    result = cm_squared.getUnitsName()

    # result is "cm2"
    

getExponent ()

Purpose:

Retrieve the exponent of the current unit (no base, just exponent.

Input Arguments:

None.

Return Value:

PyFloat? contining the exponent of the current unit (no base, just exponent).

Notes:

None.

    import Rappture.Units

    cm_squared = Rappture.Units.define("cm2")

    result = cm_squared.getExponent()

    # result is 2.0
    

convert (toUnit, value)

Purpose:

convert value from the current unit to toUnit.

Input Arguments:

  1. toUnit - Rappture Unit object.
  2. value - value to be converted to toUnit.

Return Value:

PyFloat? Object representing the converted value.

Notes:

None.

    import Rappture.Units
    
    def m2a(meter):
        return (meter*(1.0e10))
    
    def a2m(ang):
        return (ang*(1.0e-10))
        
    meters = Rappture.Units.define("m")
    ang = Rappture.Units.define("A")
    
    Rappture.Units.defineConv(meters,ang,m2a,a2m)

    result = meters.convert(ang,1e-10)

    # result is 1.0

makeBasis (value)

Purpose:

convert the value from the current unit to its basis.

Input Arguments:

  1. value - value to be converted to the current unit's basis.

Return Value:

PyFloat? Object representing the converted value.

Notes:

None.

    import Rappture.Units 

    meters = Rappture.Units.define("m")
    Rappture.Units.makeMetric(meters)

    centimeter = Rappture.Units.find("cm")

    result = centimeter.makeBasis(200)

    # result is 2.0