wiki:rappture_python_api

Version 2 (modified by dkearney, 16 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:
RpUnits

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

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 zero (0) represents no basis for the unit.

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 1 will be returned and the conversion will be stored. on failure.

Notes:

  1. a basisNmae of zero (0) represents no basis for the unit.

find (searchName)

Purpose:

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

Input Arguments:

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

Return Value:

Integer handle representing the unit just defined.

Notes:

  1. a basisNmae of zero (0) represents no basis for the unit.

makeMetric (newBasis)

Purpose:

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

Input Arguments:

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

Return Value:

Integer handle representing the unit just defined.

Notes:

  1. a basisNmae of zero (0) represents no basis for the unit.

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 RpUnits

    cm_squared = RpUnits.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 RpUnits

    cm_squared = RpUnits.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 whole name of the current unit (base and exponent).

Notes:

None.

    import RpUnits

    cm_squared = RpUnits.define("cm2")

    result = cm_squared.getUnitsName()

    # result is cm2
    

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 RpUnits
    
    def m2a(meter):
        return (meter*(1.0e10))
    
    def a2m(ang):
        return (ang*(1.0e-10))
        
    meters = RpUnits.define("m")
    ang = RpUnits.define("A")
    
    RpUnits.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 RpUnits 

    meters = RpUnits.define("m")
    RpUnits.makeMetric(meters)

    centimeter = RpUnits.find("cm")

    result = centimeter.makeBasis(200)

    # result is 2.0