server Package — Personis 12.9 documentation

### Navigation

- index
- modules |
- previous |
- Personis 12.9 documentation »
- personis Package »

# server Package

## `server` Package

## `active` Module

class `personis.server.active.` `Access`(model=None, modeldir=None, user=None)

  Bases: `personis.server.base.Access`

  Access class with active additions

  Parameters: | model (str) – Name of the model to open - must resolve, with modeldir, to a valid directory modeldir (str) – Directory of the model user (str) – Username of person accessing. Should match model owner, but authorization is handled at server level.

  `subscribe`(context=[], view=None, subscription=None)

    Parameters: | context – is a list giving the path of context identifiers view – is either: an identifier of a view in the context specified a list of component identifiers or full path lists None indicating that the values of all components in the context be returned subscription – is a dictionary containing owner, password and subscription statement string

## `base` Module

model database stored in ”.model” in the model directory:

    Identifier  modelname
    Description     of the model
    owner       owner of the model
    password    md5 hash of owner password for this model
    apps        dictionary of app names and keys
        appname     dictionary of info about that app
            password    md5 hash of the apps access key (password)
            description of the app

context database stored in ”.context” in each context directory:

    Identifier  context name
    Description     of the context
    perms       a dictionary of permissions for apps
        appname     dictionary of permission info for that app
            permname    True/False value indicates permname permission for the app
                eg {"ask":False, "tell":True} can tell values but not ask
            "resolvers" list of resolvers that the app is allowed to use
                eg {"resolvers":["last1", "goal"]}

class `personis.server.base.` `Access`(model=None, modeldir='', user='', password=None, debug=0)

  Bases: `personis.server.resolvers.Access`, `personis.server.ev_filters.Access`

  Parameters: | model – model name modeldir – model directory user – user name debug – password string
  Returns: | a user model access object
  Raise : |

  `ask`(context=[], view=None, resolver=None, showcontexts=None)

    Parameters: | context – a list giving the path of context identifiers view – either: - an identifier of a view in the context specified - a list of component identifiers or full path lists - None indicating that the values of all components in the context be returned resolver – a string containing the name of a resolver or resolver is a dictionary containing information about resolver(s) to be used and arguments the “resolver” key gives the name of a resolver to use, if not present the default resolver is used the “evidence_filter” key specifies an evidence filter eg ‘evidence_filter’ = “all” returns all evidence, “last10” returns last 10 evidence items, “last1” returns most recent evidence item, None returns no evidence showcontexts – if True, a tuple is returned containing (list of component objects, list of contexts in the current context, list of views in the current context, list of subscriptions in the current context)
    Returns: | a list of component objects
    Raise : |

  `checkpermission`(context=None, componentid=None, app=None, permname=None, permval=None)

    gets permissions for a context (if componentid is None) or a component # not implemented #### :return: True is the app has the nominated permission False if not

  `checksubs`(context, componentid)

    check subscriptions for componentid in current context. implemented in active

    Parameters: | context – a list giving the path to the required context componentid – identifier of the component
    Returns: |
    Raise : |

  `delcomponent`(context=[], componentid=None)

    Delete an existing component in a given context

    Parameters: | context – a list giving the path to the required context id – the id for a componen
    Returns: | None on success a string error message on error

  `delcontext`(context=[])

    Delete a context

  `deleteapp`(app=None)

    deletes an app

  `delview`(context=[], viewid=None)

    Delete an existing view within a given context

    Parameters: | context – a list giving the path to the required context viewid – view identifier
    Returns: | on success, None on failure, a string reporting the problem

  `existcontext`(context=[])

    Parameters: | context – a list giving the path to the required context
    Returns: | True if context exists False if the context doesn’t exist

  `export_model`(context=[], resolver=None, level=None)

    Export a model to a json representation

    Parameters: | context – a list giving the path of context identifiers this is the root of the um tree to export resolver – a string containing the name of a resolver or a dictionary containing information about resolver(s) to be used and arguments the “resolver” key gives the name of a resolver to use, if not present the default resolver is used the “evidence_filter” key specifies an evidence filter eg ‘evidence_filter’ = “all” returns all evidence, “last10” returns last 10 evidence items, “last1” returns most recent evidence item, None returns no evidence level –
    Returns: | returns a JSON encoded representation of the um tree
    Raise : |

  `getcontext`(context=[], getsize=False)

    Parameters: | context – a list giving the path to the required context
    Returns: | a dictionary containing information associated with the context
    Raise : |

  `getpermission`(context=None, componentid=None, app=None)

    gets permissions for a context (if componentid is None) or a component # not implemented yet ####

    Returns: | a tuple (ask,tell)

  `import_model`(context=[], partial_model=None)

    Import a model

    Parameters: | context – context to import partial model to if None, use root of model partial_model – string containing JSON representation of model dictionary OR a dictionary with elements: contextinfo - Description, Identifier, perms, resolver contexts - sub contexts components views subs
    Returns: |
    Raise : |

  `listapps`()

    returns an dictionary of apps that are registered key is app name, ‘description’ is app description

  `mkcomponent`(context=[], componentobj=None)

    Make a new component in a given context

    Parameters: | context – a list giving the path to the required context componentobj – (`Component`) a Component object with the context
    Returns: | None on success a string error message on error

  `mkcontext`(context=[], contextobj=None)

    Make a new context in a given context

    Parameters: | context – a list giving the path to the context that will hold the new context contextobj – a Context object
    Returns: | True if created ok, False otherwise

  `mkview`(context=[], viewobj=None)

    Make a new view in a given context

    Parameters: | context – a list giving the path to the required context viewobj – a View object

  `registerapp`(app=None, desc='', password=None, realm='password')

    registers a password for an app

    Parameters: | app – app name is a string (needs checking TODO) desc – the app description string app passwords are stored at the top level .model db realm – The type of access method. ‘oauth’ if it’s an app (like mneme or umbrowser) that can handle oauth. ‘password’ for the old password system.
    Returns: | returns a dictionary containing description and password(access key). If ‘password’ realm was requested, but no password given, returns None

  `set_goals`(context=[], componentid=None, goals=None)

    set the goal list for a component. requires “tell” permission

    Parameters: | context – a list giving the path to the required context componentid – identifier of the component goals – list of goal component paths
    Returns: |
    Raise : |

  `setcomponentoption`(context, componentid, **kwargs)

    Parameters: | context – a list giving the path to the required context componentid – name of the component to set items on **kwargs – a set of keyword arguments giving information to associate with the component
    Returns: | True on success False if the component doesn’t exist

  `setcontext`(context=[], **kwargs)

    Set the context

    Parameters: | context – a list giving the path to the required context **kwargs – a set of keyword arguments giving information to associate with the context
    Returns: | True on success False if the context doesn’t exist

  `setpermission`(context=None, componentid=None, app=None, permissions={})

    sets ask/tell permission for a context (if componentid is None) or a component

  `tell`(context=[], componentid=None, evidence=None, dosubs=True)

    Tell the model something

    Parameters: | context – a list giving the path to the required context componentid – identifier of the component evidence – (`Evidence`) object to add to the component
    Returns: |
    Raise : |

`personis.server.base.` `MkModel`(model=None, modeldir=None, user=None, description=None)

  make a model with name “model” in directory modeldir for “user” with “description”

  Parameters: | model – modeldir – user – description –
  Raise : |

## `cronserver` Module

class `personis.server.cronserver.` `crontab_parser`(max_=60)

  Bases: `object`

  Parser for crontab expressions. Any expression of the form ‘groups’ (see BNF grammar below) is accepted and expanded to a set of numbers. These numbers represent the units of time that the crontab needs to run on:

      digit   :: '0'..'9'
      dow     :: 'a'..'z'
      number  :: digit+ | dow+
      steps   :: number
      range   :: number ( '-' number ) ?
      numspec :: '*' | range
      expr    :: numspec ( '/' steps ) ?
      groups  :: expr ( ',' expr ) *

  The parser is a general purpose one, useful for parsing hours, minutes and day_of_week expressions. Example usage:

      >>> minutes = crontab_parser(60).parse("*/15")
      [0, 15, 30, 45]
      >>> hours = crontab_parser(24).parse("*/4")
      [0, 4, 8, 12, 16, 20]
      >>> day_of_week = crontab_parser(7).parse("*")
      [0, 1, 2, 3, 4, 5, 6]

## `ev_filters` Module

class `personis.server.ev_filters.` `Access`

  Evidence filter mixin for Personis Access

  Contains evidence filter methods that are used before a resolver runs To add a new filter, add the method to this class and add an entry to the self.evidencefilterlist dictionary

  `goal_filter`(elist=None, arguments=None)

    return elements with flag “goal”

  `last10_filter`(elist=None, arguments=None)

    return last 10 evidence items

  `last1_filter`(elist=None, arguments=None)

    return last 1 evidence item

  `recent_count_filter`(elist=None, arguments=None)

    return the last arguments[“recent_count”] elements

  `since_time_filter`(elist=None, arguments=None)

    return elements with creation_time after arguments[“since_time”]

class `personis.server.ev_filters.` `Evidence_list`(elist=None, model=None, componentid=None)
  `close`()

## `exceptions` Module

Exceptions used in the Personis System

exception `personis.server.exceptions.` `ModelNotFoundError`

  Bases: `exceptions.IOError`

  Used to indicate that no model can be found for given modelname

exception `personis.server.exceptions.` `ModelServerError`

  Bases: `exceptions.IOError`

  Used to indicate that the required model server is returning an error

## `jsoncall` Module

## `mkmodel` Module

Personis_mkmodel - library functions used to create sets of models.
  Used by the program mkmodel

mkmodel takes a definition of a model (stored in modeldefinitionfile) and creates a model in modeldirectory for each model

`personis.server.mkmodel.` `domodeldef`(mdefstring)

  function to parse a modeldef statement arg is a string containing the mdef statement

`personis.server.mkmodel.` `mkmodel_um`(um, lines, debug=1)

  Create a model from the model definition in the string “lines”

## `resolvers` Module

class `personis.server.resolvers.` `Access`

  Resolver mixin for Personis Access

  Contains resolver methods that can be specified on an “ask” operation To add a new resolver, add the method to this class and add an entry to the self.resolverlist dictionary

  `GoalResolver`(model=None, component=None, context=None, resolver_args=None)

    resolver function used if none specified sets component value to the value from the last piece of given, goal evidence

  `RecentResolver`(model=None, component=None, context=None, resolver_args=None)

    resolver function used if none specified sets component value to the value from the last piece of given, goal evidence

## `server` Module

class `personis.server.server.` `Server`(modeldir='models', adminsfile='admins.yaml', clients=None, access_tokens='./access_tokens.dat', client_secrets='client_secrets_google.json')

  The personis server

  Parameters: | modeldir (str) – Directory containing the user models adminsfile (str) – Path to list of people who can administrate the server clients (str) – Path to son file of oauth client details access_tokens (str) – Path of file containint the oauth access tokens client_secrets (str) – Path to json file containing client info for this server (as a client) to access google APIs

  `allow`()

    In the case that they do want the client to use personis on their behalf, we register the client in um, and redirect back to the client with a temporary authorization key. (Accessed by a user with a web browser, redirected from /logged_in)

  `authorize`(client_id, redirect_uri, scope, access_type, response_type='code', approval_prompt='auto', state=None)

    This is the entry point for client authentication against Personis. (accessed by a user with a web browser, redirected from a client). Personis becomes an oauth2 server at this point. The session now contains the client_id but not much else. Only for oauth use. Don’t come in this way if you want to use list_clients!!

  `logged_in`(code)

    Step 2 of the oauth dance. At this point Google has said this is a known user. We then go and get more user info about them from google, save the info in a persistant store, create a model if none exists, and then ask them if they’re happy to let the client they’re using access personis on their behalf. (Accessed by the user with a web browser redirected from /authorized)

  `login`()

    Step 1.5. This is where clients of the personis web interface enter. there is no client_id etc because personis is not being used as an oauth server.

  `request_token`(client_id, client_secret, grant_type, code=None, redirect_uri=None, scope=None, refresh_token=None)

    The client (mneme) has a temporary key (see /allow) but the key has been to web browsers and back so it is not safe. It must be exchanged by the client taking to personis directly (no web browser involvement) for a real token. Tokens have expiration dates etc. (Accessed by the client (Mneme, etc) on behalf of a user.) NOTE! This should only be exported over TLS/SSL (ahem!)

`personis.server.server.` `runServer`(modeldir, config, admins, clients, tokens, loglevel=20, exit_queue=None, client_secrets='client_secrets_google.json')

  Utility to run the personis server.

  Parameters: | modeldir (str) – Directory containing the user models config (str) – Path to cherrypy server config file admins (str) – Path to list of people who can administrate the server clients (str) – Path to son file of oauth client details tokens (str) – Path of file containint the oauth access tokens client_secrets (str) – Path to json file containing client info for this server (as a client) to access google APIs

## `subscription` Module

Functions for handling subscriptions

Uses the pyparsing module to parse and execute the subscription statement.

Run as a standalone program for testing.

Subscription statement grammar:

> resolvername := ID evidencetype := ID componentval := ‘<’ [ resolvername ‘!’ ] component ‘>’ componentname := ID | componentval modelname := ‘.’ | componentname component := modelname [ ‘/’ componentname ]* cronspec := ‘[‘ QUOTEDSTRING ‘]’ item := component | QUOTEDSTRING patternmatch := item ‘~’ item tell := ‘TELL’ item ‘,’ evidencetype ‘:’ item tellchanged := ‘TELLCHANGED’ item ‘,’ evidencetype ‘:’ item notify := ‘NOTIFY’ item [item]* action := tell | tellchanged | notify statement := [ cronspec ] patternmatch ‘:’ action

Note:
  a cronspec string is similar to a crontab entry: “minute hour day_of_month month day_of_week”

Examples:

> <froomBT/seen> ~ ‘.*’ : TELL <froomBT/seen>/location, <froomBT/location>” <froomBT/seen> ~ ‘.*’ : NOTIFY ‘http://www/qqq.cgi‘” <froomBT/seen> ~ ‘.*’ : TELL bob/personal/location, explicit:<froomBT/location> <bob/personal/location> ~ ‘.*’ : NOTIFY ‘http://www.it.usyd.edu.au/~bob/Personis/tst.cgi‘ [“/15 * * * *”] <bob/personal/location> ~ ‘.‘ : NOTIFY ‘http://www.it.usyd.edu.au/~bob/Personis/tst.cgi‘ <default!bob/personal/location> ~ ‘.*’ : NOTIFY ‘http://www.it.usyd.edu.au/~bob/Personis/tst.cgi‘ <default!bob/personal/location> ~ ‘.*’ : NOTIFY ‘http://www.it.usyd.edu.au/~bob/Personis/tst.cgi‘ <bobPhone/seenby> ~ ‘.*’ : TELL bobPhone/location, explicit:<<bobPhone/seenby>/location> <default!./personal/location> ~ ‘.*’ : NOTIFY ‘http://www.it.usyd.edu.au/~bob/Personis/tst.cgi?’ ‘location=’ <./personal/location> ‘&name=’ <./personal/firstname>

`personis.server.subscription.` `dosub`(sub, um)

  function to parse and execute a subscription statement takes one dictionary argument containing: user, password to be used in Access’ing the model and statement, a string containing the subscription statement

## `util` Module

### Navigation

- index
- modules |
- previous |
- Personis 12.9 documentation »
- personis Package »