Application Program Interface — Personis 12.9 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Personis 12.9 documentation »

# Application Program Interface

See personis Package for API documentation.

## Examples

Models can be accessed either locally in the filesystem, or via a server.

Local access is via the base module.

Basic accretion operation - tell some evidence

The following example shows the use of base to tell a piece of evidence containing a name string to a component in the model. The source of the evidence is “contactapp” which will have been given access to the model by the owner.

    import base

    # access the model in the filesystem
    # model name is "alice", model is stored in directory "Models"
    um = base.Access(model="alice", modeldir='Models', user='contactapp')

    # create a piece of evidence with Alice as value
    ev = Personis_base.Evidence(evidence_type="explicit", value="Alice")

    # tell this as user alice's first name into component "firstname", context "Personal"
    um.tell(context=["Personal"], componentid="firstname", evidence=ev)

Basic resolution operation - ask for a value

This example *ask*s for the value of a component using the default resolver that uses the most recent piece of evidence.

    import base

    um = base.Access(model="alice", modeldir='Models', user='contactapp')

    # now ask for the value of the component using the default resolver and the last piece of evidence
    reslist = um.ask(context=["Personal"], view=["firstname"], resolver=dict(evidence_filter="last1"))

A view is just a list of components. The list can be explicit in the ask request or we can give a view a name and store it in the model.

For example:

    # now ask for the value of two components using a view
    reslist = um.ask(context=["Personal"], view=["firstname", "lastname"], resolver=dict(evidence_filter="last1"))

We can make a view using a view object and the mkview method. For example:

    import base

    um = base.Access(model="alice", modeldir='Models', user='contactapp')

    vobj = Personis_base.View(Identifier="fullname", component_list=["firstname", "lastname"])
    um.mkview(context=["Personal"], viewobj=vobj)

    reslist= um.ask(context=["Personal"], view = 'fullname', resolver={'evidence_filter':"all"})

The values are returned by an ask request in a list of component objects, one for eachc component value requested. The component objects have the attributes described in the documentation above but this includes a value attribute which is the resolved value for the component. Eg:

    reslist = um.ask(context=["Personal"], view=["firstname"], resolver=dict(evidence_filter="last1"))
    print "Firstname:", reslist[0].value

Creating new contexts and components

The mkcontext and mkcomponent methods, along with the Component and Context objects, are used to build new elements in the model. Here is an example of creating and then deleting a context:

    # assume we have accessed the model
    print "creating context 'Deltest' in context 'Personal'"
    cobj = base.Context(Identifier="Deltest", Description="testing context deletion")
    # now make the new context
    um.mkcontext(context=["Personal"], contextobj=cobj)

    print "now delete it"
    um.delcontext(context=["Personal", "Deltest"]):

and here is an example of creating and then deleting a component:

    cobj = base.Component(Identifier="age", component_type="attribute", Description="age", goals=[['Personal', 'Health', 'weight']], value_type="number")

    um.mkcomponent(context=["Personal"], componentobj=cobj)

    # tell some evidence to the new component
    ev = Personis_base.Evidence(evidence_type="explicit", value=17)
    um.tell(context=["Personal"], componentid='age', evidence=ev)
    reslist = um.ask(context=["Personal"], view=['age'], resolver={'evidence_filter':"all"})
    print "Age:", reslist[0].value

    # delete the component
    resd = um.delcomponent(context=["Personal"], componentid = "age")

Navigating the Model

If you want to discover what contexts are present in the model there is a variant on the ask method that allows you to get a list of all the contexts, components, views and subscriptions that are contained in a given context. Just add the parameter “showcontexts=True” to the ask call. Using this call you can start at the root context and walk the tree of contexts discovering the full contents of the model. Eg:

    print "Show the root context"
    info = um.ask(context=[""], showcontexts=True)

The return value is a tuple containing (componentlist, contextlist, viewlist, sublist), where each part of the tuple is a list of objects.

Subscriptions: rules for action

A feature of Personis is the ability to add a rule to a component that is examined when ever a tell operation is performed on the component. The rule typically examines a resolved value of the component, matching against a pattern. If the pattern is matched an action is initiated. The action can be a tell operation to tell some evidence to a component, or a notify operation that will construct a URL and fetch it, thus initiating some action at an external web site. Rules can be deleted using the delete_sub method.

Note that you need to use active instead of base as that is where the subscription methods are found.

For example:

    import base
    import active

    um = Personis_a.Access(model="alice", modeldir='Models', user='contactapp')

    # subscription rule that will match firstname against a wildcard pattern (regular expression):
    sub = """
    <default!./Personal/firstname> ~ '.*' :
             NOTIFY 'http://www.myweb.me/~alice/action.cgi?' 'firstname=' <./Personal/firstname>
    """

    # a token identifying the rule is returned
    subtoken = um.subscribe(context=["Personal"], view=['firstname'], subscription={'user':'alice', 'password':'secret', 'statement':sub})

    ev = Personis_base.Evidence(evidence_type="explicit", value="Alice")
    # do a tell. This should cause the action.cgi script to be invoked with the firstame
    um.tell(context=["Personal"], componentid='firstname', evidence=ev)

    # delete the rule
    um.delete_sub(context=["Personal"], componentid='lastname', subname=subtoken)

Import and Export of Models

Models can be imported and exported in JSON (JavaScript Object Notation) form using the export_model and import_model methods:

    import base
    import active

    um = active.Access(model="alice", modeldir='Models', user='contactapp')

    # export a model sub tree to JSON
    # note that all evidence will also be exported.
    modeljson = um.export_model(["Personal"], evidence_filter="all")
    print modeljson

    # import the same model tree but into a different context.
    um.import_model(context=["Temp"], partial_model=modeljson)

### Navigation

- index
- modules |
- next |
- previous |
- Personis 12.9 documentation »