8. Python bindings for Ocarina

8.1. Ocarina Python bindings

Ocarina proposes Python bindings to its internal APIs. This binding is available if configured properly, first at compile-time, then at run-time.

At compile time, Ocarina must be configured with shared libraries support. Refer to the Installation;

At run-time, the following environment variables must be set up:

% export PATH=`ocarina-config --prefix`/bin:$PATH
% export OCARINA_PATH=`ocarina-config --prefix`
% export LD_LIBRARY_PATH=$OCARINA_PATH/lib:$LD_LIBRARY_PATH
% export PYTHONPATH=$OCARINA_PATH/include/ocarina/runtime/python:$OCARINA_PATH/lib:$PYTHONPATH

8.2. Example

The following example illustrates the capabilities of the Python API, it implements a visitor that iterates of the AADL model elements:

#!/usr/bin/env python

# visitor.py: A simple script to visit all nodes of an AADL instance tree
#
# Note: this scripts require the docopt package

"""visitor.py: A simple script to visit all nodes of an AADL instance tree

Usage: visitor.py FILE
       visitor.py ( -h | --help )
       visitor.py --version

Arguments:
    FILE  AADL file to process

Options:
    -h, --help  Help information
    --version   Version information

"""

from docopt import docopt
import sys

###################################
args = sys.argv[1:]
# XXX: we have to do a back-up of the command-line arguments prior to
# importing Ocarina, as its initialization phase will erase sys.argv
# To be investigated, see github issue #45 for details
###################################

import ocarina
import lmp
from ocarina_common_tools import *
import libocarina_python

def visitor (component, level):
    """
    This function visits an AADL component, and prints information
    about its features, subcomponents and properties.

    Args:
    component (str):  the NodeId of the component
    level (int): indentation level

    """

    print ' ' * level,'Visiting ',lmp.getInstanceName(component)[0]

    features=ocarina.AIN.Features(component)[0];
    if features is not None :
        print ' ' * level,' -> features:',features
        for feature in features :
            print ' ' * level,'   -> feature:',feature,', ',lmp.getInstanceName(feature)[0]
            print ' ' * level,'      source feature: ', lmp.getInstanceName(ocarina.getSourcePorts(feature)[0])[0]
            print ' ' * level,'      destination feature: ', lmp.getInstanceName(ocarina.getDestinationPorts(feature)[0])[0]

    properties = ocarina.AIN.Properties(component)[0];
    if properties is not None :
        print ' ' * level,' -> properties:'
        for property in properties:
            print ' ' * level,'   ',ocarina.getPropertyValue(component,property)[0]

    subcomponents=ocarina.AIN.Subcomponents(component)[0];
    if subcomponents is not None :
        print ' ' * level,' -> subcomponents:',subcomponents
        for subcomponent in subcomponents :
            print ' ' * level,'   -> ',subcomponent,",",lmp.getInstanceName(subcomponent)[0]
            visitor(str(ocarina.AIN.Corresponding_Instance(subcomponent)[0]),level+3)

    print ' ' * level,'end of visit of ',component

def main ():
    # read  command line arguments

    arguments = docopt(__doc__, args, version="visitor.py 0.1")

    # build the repository path
    repo = arguments['FILE']

    err = ocarina.load(repo);       # load a file
    err = ocarina.analyze();        # analyze models
    err = ocarina.instantiate("");  # instantiate system

    print '----------------------------------------------------'
    print 'Visit AADL Instance tree'
    print '----------------------------------------------------'

    root=lmp.getRoot()[0]
    visitor(root,0)

if __name__ == "__main__":
    main ()

8.3. Python API description

The following lists all functions defined in the ocarina module

8.3.1. ocarina – Python binding to the Ocarina AADL processor

This module provides direct access to top-level functions of Ocarina to load, parse, instantiate AADL models, and to invoke backends.

ocarina.ocarina.Backends = ('polyorb_hi_ada', 'polyorb_hi_c', 'real_theorem')

List of supported backends, used by generate

class ocarina.ocarina.Enum

ocarina.ocarina.add_real_library(libraryname)

Parameters:libraryname (string) – name of the REAL library file to include

ocarina.ocarina.analyze()

Analyze models

ocarina.ocarina.generate(generator)

Generate code

Parameters:generator – one supported backends, from Backends

For instance, to use the PolyORB-HI/Ada backend, you may use the following

>>> generate (Backends.polyorb_hi_ada)

ocarina.ocarina.getDestinationPorts(nodeId)

Get the destination port associated to the feature_nodeId passed as parameter, in the case feature_nodeId participates in a connection.

ocarina.ocarina.getPropertyValue(nodeId, propertyId)

Get the value of the property

ocarina.ocarina.getPropertyValueByName(nodeId, propertyString)

Get the value of the property propertyString applied to model element nodeId.

ocarina.ocarina.getSourcePorts(feature_nodeId)

Get the source port associated to the feature_nodeId passed as parameter, in the case feature_nodeId participates in a connection.

ocarina.ocarina.instantiate(root_system)

Instantiate model, starting from root_system

Parameters:root_system (string) – name of the root system to instantiate

ocarina.ocarina.load(filename)

Load a file

Parameters:filename (string) – name of the file to be loaded, using Ocarina search path

E.g. to load “foo.aadl”:

>>> load("foo.aadl")

ocarina.ocarina.reset()

Reset Ocarina internal state

Note: this function must be called before processing a new set of models.

ocarina.ocarina.set_real_theorem(theorem_name)

Set main REAL theorem

Parameters:theorem_name (string) – name of the theorem

ocarina.ocarina.status()

Print Ocarina status

ocarina.ocarina.version()

Print Ocarina version

8.3.2. lmp – Port of Ellidiss LMP to Ocarina Python API

This module is an adaptation of Ellidiss LMP “Logical Model Processing” to Python.

ocarina.lmp.getAliasDeclarations()

Return the list of all the alias declaration defined in the current AADL project

ocarina.lmp.getAnnexes()

Return the list of all the annexes defined in the current AADL project

ocarina.lmp.getComponentFullname(nodeId)

Get the full qualified name of an AADL component

Parameters:nodeId – the id of the component whose full qualified name is searched

For instance, to retrieve the full qualified name of MyComponent, retrieve its id (nodeId) and use the following

>>> getComponentFullname (nodeId)

ocarina.lmp.getComponentImplementations(category)

Return a list of component implementations defined in the current AADL project

Parameters:category – one of the AADL category defined in the standard

For instance, to retrieve all the system implementations from the current project, you may use the following

>>> getComponentImplementations (System)

ocarina.lmp.getComponentName(nodeId)

Get the name of an AADL component

Parameters:nodeId – the id of the component whose name is searched

For instance, to retrieve the name of MyComponent, retrieve its id (nodeId) and use the following

>>> getComponentName (nodeId)

ocarina.lmp.getComponentTypes(category)

Return a list of component types defined in the current AADL project

Parameters:category – one of the AADL category defined in the standard

For instance, to retrieve all the system types from the current project, you may use the following

>>> getComponentTypes (System)

ocarina.lmp.getFlowImplementations()

Return the list of all the flow implementation defined in the current AADL project

ocarina.lmp.getFlowSpecifications()

Return the list of all the flow specification defined in the current AADL project

ocarina.lmp.getImportDeclarations()

Return the list of all the import declarations used in the current AADL project

ocarina.lmp.getInModes()

Return the list of all the in mode used in the current AADL project

ocarina.lmp.getInstanceName(nodeId)

Get the name of an AADL instance

Parameters:nodeId – the id of the instance whose name is searched

For instance, to retrieve the name of MyInstance, retrieve its id (nodeId) and use the following

>>> getInstanceName (nodeId)

ocarina.lmp.getInstances(category)

Return a list of instances defined in the current AADL project

Parameters:category – one of the AADL category defined in the standard

For instance, to retrieve all the system instances from the current project, you may use the following

>>> getInstances (System)

ocarina.lmp.getModeTransitions()

Return the list of all the mode transition defined in the current AADL project

ocarina.lmp.getModes()

Return the list of all the modes defined in the current AADL project

ocarina.lmp.getNodeId(name)

Get the Id of a component from its name

Parameters:name – the AADL name of the node whose id is queried

For instance, to retrieve the id of MyHome, you may use the following

>>> getNodeId (MyHome)

ocarina.lmp.getPackages()

Return the list of all the packages defined in the current AADL project

ocarina.lmp.getPropertyConstants(propertySetId)

Return the list of all the constant property defined in the provided property set

Parameters:propertySetId – the nodeId of the property set in the current AADL project to search in

For instance, to retrieve all the constant property from property set propertySet, retrieve its id (propertySetId) and use the following

>>> getPropertyConstants (propertySetId)

ocarina.lmp.getPropertyDefinitions(propertySetId)

Return the list of all the property declaration defined in the provided property set

Parameters:propertySetId – the nodeId of the property set in the current AADL project to search in

For instance, to retrieve all the property declaration from property set propertySet, retrieve its id (propertySetId) and use the following

>>> getPropertyDefinitions (propertySetId)

ocarina.lmp.getPropertySets()

Return the list of all the property set defined in the current AADL project

ocarina.lmp.getPropertyTypes(propertySetId)

Return the list of all the property types defined in the provided property set

Parameters:propertySetId – the nodeId of the property set in the current AADL project to search in

For instance, to retrieve all the property types from property set propertySet, retrieve its id (propertySetId) and use the following

>>> getPropertyTypes (propertySetId)

ocarina.lmp.getPrototypeBindings()

Return the list of all the prototype bindings defined in the current AADL project

ocarina.lmp.getPrototypes()

Return the list of all the prototypes defined in the current AADL project

ocarina.lmp.getRoot()

Get the Id of the current root instantiated model