API — Ringo 0.15.1 documentation

### Navigation

- index
- modules |
- previous |
- Ringo 0.15.1 documentation »

# API

## Model

### BaseList

class `ringo.model.base.` `BaseList`(clazz, db, cache='', items=None)
  `__init__`(clazz, db, cache='', items=None)

    A List object of. A list can be filterd, and sorted.

    Clazz: | Class of items which will be loaded.
    Db: | DB connection used to load the items.
    Cache: | Name of the cache region. If empty then no caching is done.
    Items: | Set items of the Baselist. If provided no items will be

    loaded.

  `sort`(field, order, expand=False)

    Will return a sorted item list. Sorting is done based on the string version of the value in the sort field.

    Field: | Name of the field on which the sort will be done
    Order: | If “desc” then the order will be reverted.
    Expand: | If True, then the sorting will be done on the expanded values.
    Returns: | Sorted item list

  `pageinate`(page=0, size=None)

    This function will set some internal values for the pagination function based on the given params.

    Page: | Integer of the current page
    Size: | Items per page
    Returns: |

  `filter`(filter_stack)

    This function will filter the list of items by only leaving those items in the list which match all search criterias in the filter stack. The list will get reduced with every iteration on the filter stack.

    For each filter in the stack the function will first look for an optional operator which must be the first word of the search expression. If a operator can be found the search will be done with the given operator. Otherwise the search word will be compiled to the regular expression.

    Then all items are iterated. For each item the function will try to match the value of either all, or from the configued search field with the regular expression or configured operator. If the value matches, then the item is kept in the list.

### BaseFactory

class `ringo.model.base.` `BaseFactory`(clazz)
  `__init__`(clazz)

    Factory to create of load instances of the clazz.

    Clazz: | The clazz of which new items will be created

  `create`(user)

    Will create a new instance of clazz. The instance is it is not saved persistent at this moment. The method will also take care of setting the correct ownership.

    User: | User instance will own the new created item
    Returns: | Instance of clazz

  `load`(id, db=None, cache='', uuid=False)

    Loads the item with id from the database and returns it.

    Id: | ID of the item to be loaded
    Db: | DB session to load the item
    Cache: | Name of the cache region. If empty then no caching is done.
    Uuid: | If true the given id is a uuid. Default to false
    Returns: | Instance of clazz

### BaseItem

class `ringo.model.base.` `BaseItem`
  `render`()

    This function can be used to render a different representation of the item. On default it also returns the simple string representation. Usefull to build some HTML used in links e.g overviews and lists

  `get_value`(name, form_id='read', expand=False)

    Return the value of the given attribe of the item. Unlike accessing the raw value through the attribite directly this function will apply all configured transformations to the value before returing it.

  `get_values`(include_relations=False, serialized=False)

    Will return a dictionary with the values of the item. If include_relations is true, than the realtion values are included. Else only scalar values are included

  `set_values`(values)

    Will set the values of the items attributes to the given values in the dictionary. Attributes beginning with “_” are considred private and are ignored.

    This function will not handle saving the changed data. This can be by either calling the save method of the item, or automatically at the transactions end if autocommit is enabled.

    Please note that setting the values for foreign key attributes might not work as expected. This is especially true for foreign keys to already existing items. You are not able to change a existing relation in the items by changing the foreign key value (You must do this by setting the related item). In this case the value for the foreign key seems to be ignored and replaced by the one of the actual related item. In contrast you can set a new relation by setting the foreign key if this is a new relation.

    Values: | Dictionary with values to be set

  `save`(data, request=None)

    Will save the given data into the item. If the current item has no value for the id attribute it is assumed that this item must be added to the database as a new item. In this case you need to provide a dbsession as the new item is not linked to any dbsession yet.

    Please note, that you must ensure that the submitted values are validated. This function does no validation on the submitted data.

    Data: | Dictionary with key value pairs.
    Request: | Current request session. Used when saving new items.
    Returns: | item with new data.

### Modul

class `ringo.model.modul.` `ModulItem`(**kwargs)
  `get_clazz`()

    Returns the clazz defined in the clazzpath attribute

  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

  `has_action`(url)

    Will return True if the modul has a ActionItem configured with given url. Else false.

  `get_str_repr`()

    Return a tupel with format str and a list of fields.

class `ringo.model.modul.` `ActionItem`(**kwargs)
  `bundle`

    Flag to indicate if the action should be available in the bundled actions

  `display`

    Optional. Configure where the action will be displayed. If display is ‘secondary’ the action will be rendererd in the advanced dropdown context menu. Default is ‘primary’

  `permission`

    Optional. Configure an alternative permission the user must have to be allowed to call this action. Known values are ‘list’, ‘create’, ‘read’, ‘update’, ‘delete’, ‘import’, ‘export’. If empty the permission system will use the the lowered name of the action.

  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

### Usermanagement

class `ringo.model.user.` `User`(**kwargs)
  `has_role`(role, include_group_roles=True)

    Return True if the user has the given role. Else False” :user: User instance :include_group_roles: Boolean flag to configure if the roles of the groups the user is member of should be checked too. Defaults to True. :returns: True or False

  `get_roles`(include_group_roles=True)

    Returns a list of roles the user has. The list contains Role object and are collected by loading roles directly attached to the user plus optionally roles attached to the groups the user is member of

    Include_group_roles:
    | Booloan flag to configure if the roles of

    the groups the user is member of should be included in the list. Defaults to True. :returns: List of Role instances

  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class `ringo.model.user.` `Usergroup`(**kwargs)
  `get_roles`()

    Returns a list of roles the group has. The list contains Role object and are collected by loading roles directly attached to the group.

    Returns: | List of Role instances

  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class `ringo.model.user.` `Role`(**kwargs)

  A Role is used to configure which actions are permitted to users. Therefor each role will have an internal list of modul actions. A user will be allowed to call all actions assigned to the role he is equiped with.

  `admin`

    Flag to set the role as administrational role which means that the user will gain the assigned permissions irrespective from checking the ownership

  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

class `ringo.model.user.` `Profile`(**kwargs)
  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

### News

class `ringo.model.news.` `News`(**kwargs)
  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

### Appointment

class `ringo.model.appointment.` `Appointment`(**kwargs)
  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

### File

class `ringo.model.file.` `File`(**kwargs)
  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

### Log

class `ringo.model.log.` `Log`(**kwargs)
  `author`

    Textual representation of the user. This will even stay if the origin creator (user) is deleted.

  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

### Tag

class `ringo.model.tag.` `Tag`(**kwargs)

  Tags (keywords) can be used to mark items.

  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

### Todo

class `ringo.model.todo.` `Todo`(**kwargs)
  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

### Comment

class `ringo.model.comment.` `Comment`(**kwargs)
  `__init__`(**kwargs)

    A simple constructor that allows initialization from kwargs.

    Sets attributes on the constructed instance using the names and values in `kwargs`.

    Only keys that are present as attributes of the instance’s class are allowed. These could be, for example, any mapped columns or relationships.

### Statemachine

class `ringo.model.statemachine.` `Statemachine`(item, item_state_attr, init_state=None, request=None)

  A state machine, is a mathematical model of computation used to design sequential logic circuits for items of a module. It is conceived as an abstract machine that can be in one of a finite number of states. The machine is in only one state at a time; the state it is in at any given time is called the current state. It can change from one state to another when initiated by a triggering event or condition; this is called a transition.

  `__init__`(item, item_state_attr, init_state=None, request=None)

    Initialise the statemachine for the given item.

    Item: | Attach the state machine to this `BaseItem`
    Item_state_attr:
    | name of the attribute which store the value of

    the current state of the statemachine in the given item. :init_state: Initialize the statemachine with an alternative state. (Not the value coming from item_state_attr) :request: Current request.

  `setup`()

    Need to be implemented in the inherited class.

    Example:

        s1 = State(self, 1, "On")
        s2 = State(self, 2, "Off")

        s1.add_transition(s2, "Turn on", handler, condition)
        s2.add_transition(s1, "Turn off", handler, condition)
        return s1

  `get_states`(ignore_checks=False)

    Returns a list of all states in the statemachine

    Ignore_checks: | Do not check if a transition is avaible. Return

    all states. :returns: List of `State` objects.

  `set_state`(state)

    Will set the current state of the state machine

    State: | Id of the `State` or the `State` object to

    be set as current state :returns: None

  `get_state`()

    Returns the current state of the Statemachine

    Returns: | Current `State`

class `ringo.model.statemachine.` `State`(statemachine, id, label, description=None, disabled_actions={})

  A single state in a statemachine.

  `__init__`(statemachine, id, label, description=None, disabled_actions={})

    Initialise the State

    Statemachine: | Statemachine
    Id: | Id of the state
    Label: | Label of the Statemachine (short description)
    Description: | Long description of the state.
    Disabled_actions:
    | Dictionary with a list of actions which are

    disabled for a role. {‘rolename’: [‘read’, ‘update’]}

  `add_transition`(to_state, label=None, handler=None, condition=None)

    Will add a transtion to the given state

    To_state: | End state of the transition
    Label: | Label of the transition. Is usually a verb.
    Handler: | `TransitionHandler` which will be called if the state has been changed
    Condition: | `TransitionCondition` which must be true to make the transition available
    Returns: | None

  `get_disabled_actions`(role)

    Returns a list of disabled actions of the state for the given role

    Returns: | List of disabled actions

  `get_transitions`(ignore_checks=False)

    Returns the available transitions to other states.

    Ignore_checks: | Do not check if a transition is avaible. Return

    all available transitions. :returns: List of `Transition` objects.

class `ringo.model.statemachine.` `Transition`(start_state, end_state, label=None, handler=None, condition=None)

  A transitions is used to switch from one state into another. The two states are called start state and end state where the end state is the state of the state machine after the transtions has been done.

  Every transtion can have a handler and a condition. The handler can be used to add some logic which should be trigger after the transition has been finished. The handler is a simple callable which is called with the item of the state machine.

  The condition is also a callable and can be used to restrict the availability to whatever want. The function is called with the item of the state machine and returns true or false. If the condition returns true then a transition is available.

  `__init__`(start_state, end_state, label=None, handler=None, condition=None)

    Creates a transition between to states.

    Start_state: | Start `State` of the transition
    End_state: | End of the transition
    Handler: | `TransitionHandler` which will be called if the state has been changed
    Condition: | `TransitionCondition` which must be true to make the transition available

  `get_start`()

    Returns the start state of the transition

    Returns: | Start `State`

  `get_end`()

    Returns the end state of the transition

    Returns: | End `State`

  `get_label`()

    Returns the label of the transtion. If no label was set return the two lables of the start and end state separated with a “->”.

    Returns: | Label of the `State`

  `exchange`()

    Do the transition! Exchanges the start state to the end state.

    Returns: | End `State` of the transtion.

  `is_available`()

    Check is the transition is available for the item in the statemachine. The function will call the condition function with the item of the statemachine. It returns true if the state is available (check succeeds) and returns False if the conditions for a state change are not met.

class `ringo.model.statemachine.` `TransitionHandler`

  Handler callable which will be called if the transition between to `State` objects has been finished.

class `ringo.model.statemachine.` `TransitionCondition`

  Condition callable which must be true to make the `Transition` between two `State` objects applicable.

## Lib

### Security

`ringo.lib.security.` `has_permission`(permission, context, request)

  Wrapper for pyramid’s buitin has_permission function. This wrapper sets dynamically the __acl__ attribute of the given context and then . check if the user has the given permission in the current context using pyramid’s has_permission function.

  Context can be: * Instance of BaseItem * Subclass of BaseItem * Ressource, built from a RessourceFactory

  If context is an instance or subclass of BaseItem the wrapper will dynamically set the __acl__ attribute. This attribute is used by the pyramid’s has_permission function the check the permission. If the context is a resource the function does nothing as the resource already has the __acl__ attribute set.

  If the user has the permission the it returns True, else False (Actually it returns a boolean like object, see pyramids has_permission doc for more details.)

  Permission: | String. Name of the permission. E.g list, create, read
  Context: | Either Resource, Instance of BaseItem or Subclass of BaseItem
  Request: | current request
  Returns: | True or False (Boolean like object)

`ringo.lib.security.` `get_permissions`(modul, item=None)

  Will return a list permissions attached to the modul and optionally to particular item of the modul. The returned list is suitable for using it as ACL in pyramid’s authorization system. The function will at least return class based permissions. If a item is provided then additional item level permissions are returned.

  The function will iterate over all available actions of the given modul and tries to adds a permission entry to the for every role which has granted access to the action.

  For every role it will check the following things:

  1. If the role is marked as “administrational” role, then add the permission for role and action.
  2. Elif action is either “list” or “create” (permissons on class level) then add the permission for the role and action.
  3. Elif an item is provided add item level permissions for the role _and_ only the owner or users which are member of the items group.

  Model: | The modul for which the permissions are returned
  Item: | Optional: Item of the model for which the permissons as returned
  Returns: | List of permissions

`ringo.lib.security.` `get_principals`(userid, request)

  Returns a list of pricipals for the user with userid for the given request.

  Principals are basically strings naming the groups or roles the user have. Example: role:admin or group:users are typical principals.

  Userid: | id of the user
  Request: | current request
  Returns: | list with pricipals

`ringo.lib.security.` `has_role`(user, role)

  Return True if the user has the given role. Else False” :user: User instance :returns: True or False

`ringo.lib.security.` `get_roles`(user)

  Returns a list of roles the user has. The list contains Role object and are collected by loading roles directly attached to the user plus roles attached to the groups the user is member of

  User: | User instance
  Returns: | List of Role instances

`ringo.lib.security.` `has_group`(user, group)

  Return True if the user is in the the given group. Else False” :user: User instance :returns: True or False

### Navigation

- index
- modules |
- previous |
- Ringo 0.15.1 documentation »