API Reference

This document is for developers of OSP-core, it contains the API functions

Cuds class

class osp.core.cuds.Cuds(attributes: Dict[osp.core.ontology.attribute.OntologyAttribute, Any], oclass: osp.core.ontology.entity.OntologyEntity, session: osp.core.session.session.Session = None, uid: uuid.UUID = None)[source]

Bases: object

A Common Universal Data Structure

The cuds object has attributes and is connected to other cuds objects via relationships.

add(*args, rel: osp.core.ontology.relationship.OntologyRelationship = None) → Union[osp.core.cuds.Cuds, List[osp.core.cuds.Cuds]][source]

Adds (a) cuds(s) to their respective relationship. Before adding, check for invalid keys to avoid inconsistencies later.

Parameters:
  • args (Cuds) – object(s) to add
  • rel (OntologyRelationship) – class of the relationship between the objects
Returns:

The added object(s)

Return type:

Union[Cuds, List[Cuds]]

Raises:

ValueError – adding an element already there

get(*uids, rel: osp.core.ontology.relationship.OntologyRelationship = <OntologyRelationship CUBA.ACTIVE_RELATIONSHIP>, oclass: osp.core.ontology.oclass.OntologyClass = None, return_rel: bool = False) → Union[osp.core.cuds.Cuds, List[osp.core.cuds.Cuds]][source]

Returns the contained elements of a certain type, uid or relationship. Expected calls are get(), get(*uids), get(rel), get(oclass), get(*uids, rel), get(rel, oclass). If uids are specified, the position of each element in the result is determined by to the position of the corresponding uid in the given list of uids. In this case, the result can contain None values if a given uid is not a child of this cuds_object. If no uids are specified, the resulting elements are ordered randomly.

Parameters:
  • uids – UIDs of the elements
  • rel (OntologyRelationship) – Only return cuds_object which are connected by subclass of given relationship.
  • oclass (OntologyClass) – Type (Ontology class) of the subelements
  • return_rel (bool) – Whether to return the connecting relationship, defaults to False
Returns:

the queried objects, or None, if not found

Return type:

Union[Cuds, List[Cuds]]

get_attributes()[source]

Get the attributes as a dictionary

get_triples()[source]

Get the triples of the cuds object.

iri

Get the IRI of the CUDS object

is_a(oclass)[source]

Check if self is an instance of the given oclass.

Parameters:oclass (OntologyClass) – Check if self is an instance of this oclass.
Returns:Whether self is an instance of the given oclass.
Return type:bool
iter(*uids, rel: osp.core.ontology.relationship.OntologyRelationship = <OntologyRelationship CUBA.ACTIVE_RELATIONSHIP>, oclass: osp.core.ontology.oclass.OntologyClass = None, return_rel: bool = False) → Iterator[osp.core.cuds.Cuds][source]

Iterates over the contained elements of a certain type, uid or relationship. Expected calls are iter(), iter(*uids), iter(rel), iter(oclass), iter(*uids, rel), iter(rel, oclass). If uids are specified, the each element will be yielded in the order given by list of uids. In this case, elements can be None values if a given uid is not a child of this cuds_object. If no uids are specified, the resulting elements are ordered randomly.

Parameters:
  • uids (UUID) – UIDs of the elements.
  • rel (OntologyRelationship) – class of the relationship.
  • oclass (OntologyClass) – Type of the subelements.
  • return_rel (bool) – Whether to return the connecting relationship, defaults to False
Returns:

Iterator over of queried objects, or None, if not found.

Return type:

Iterator[Cuds]

oclass

The type of the cuds object

remove(*args, rel: osp.core.ontology.relationship.OntologyRelationship = <OntologyRelationship CUBA.ACTIVE_RELATIONSHIP>, oclass: osp.core.ontology.oclass.OntologyClass = None)[source]

Removes elements from the Cuds. Expected calls are remove(), remove(*uids/Cuds), remove(rel), remove(oclass), remove(*uids/Cuds, rel), remove(rel, oclass)

Parameters:
  • args (Union[Cuds, UUID]) – UIDs of the elements or the elements themselves
  • rel (OntologyRelationship) – Only remove cuds_object which are connected by subclass of given relationship
  • oclass (OntologyClass) – Type (Ontology Class) of the subelements
session

The session of the cuds object

uid

The uid of the cuds object

update(*args) → List[osp.core.cuds.Cuds][source]

Updates the object with the other versions.

Parameters:args (Cuds) – updated cuds objects
Returns:The updated cuds_object.
Return type:Union[Cuds, List[Cuds]]

Registry class

class osp.core.session.registry.Registry[source]

Bases: dict

filter(criterion)[source]

Filter the registry. Return a dictionary that is a subset of the registry. It contains only cuds objects that satisfy the given criterion.

Parameters:criterion (Callable[Cuds, bool]) – A function that decides whether a cuds object should be returned. If the function returns True on a cuds object it means the cuds object satisfies the criterion.
Returns:A dict contains the cuds objects satisfying the criterion.
Return type:Dict[UUID, Cuds]
filter_by_attribute(attribute, value)[source]

Filter by attribute and valie

Parameters:
  • attribute (str) – The attribute to look for
  • value (Any) – The corresponding value to look for
Returns:

A subset of the registry, containing cuds objects with given attribute and value.

Return type:

Dict[UUID, Cuds]

filter_by_oclass(oclass)[source]

Filter the registry by ontolgy class.

Parameters:oclass (OntologyClass) – The oclass used for filtering.
Returns:A subset of the registry, containing cuds objects with given ontology class.
Return type:Dict[UUID, Cuds]
filter_by_relationships(relationship, consider_subrelationships=False)[source]

Filter the registry by relationships: Return cuds objects containing the given relationship.

Parameters:
  • relationship (Type[Relationship]) – The relationship to filter by.
  • consider_subrelationships (bool, optional) – Whether to return cuds objects containing subrelationships of the given relationship, defaults to False
Returns:

A subset of the registry, containing cuds objects with given relationship.

Return type:

Dict[UUID, Cuds]

get(uid)[source]

Returns the object corresponding to a given uuid.

Parameters:uid (UUID) – uuid of the desired object
Returns:Cuds object with the uid
Raises:ValueError – unsupported key provided (not a UUID object)
get_subtree(root, rel=None, skip=None)[source]

Get all the elements in the subtree which is rooted in the cuds_object element with the given uid. Only consider the given relationship.

Parameters:
  • root (Union[UUID, Cuds]) – The root of the subtree.
  • rel (Relationship, optional) – The relationship to consider defaults to None
  • skip (Set[Cuds], optional) – The elements to skip, defaults to None
Returns:

The set of elements in the subtree rooted in the given uid.

Return type:

Set[Cuds]

prune(*roots, rel=None)[source]

Remove all elements in the registry that are reachable from the given roots by considering relationship rel.

Parameters:
  • roots – Remove all elements not reachable from these root elements.
  • rel (Relationship) – Only consider this relationship.
Returns:

The set of removed elements.

Return type:

List[Cuds]

put(cuds_object)[source]

Adds an object to the registry.

Parameters:cuds_object (Cuds) – The cuds_object to put in the registry
Raises:ValueError – unsupported object provided (not a Cuds object)
reset()[source]

Delete the contents of the registry

Session classes

class osp.core.session.session.Session[source]

Bases: abc.ABC

Abstract Base Class for all Sessions. Defines the common standard API and sets the registry.

prune(rel=None)[source]

Remove all elements not reachable from the sessions root. Only consider given relationship and its subclasses.

Parameters:rel (Relationship) – Only consider this relationship to calculate reachability.
class osp.core.session.core_session.CoreSession[source]

Bases: osp.core.session.session.Session

Core default session for all objects.

get_triples()[source]

Get the triples in the core session

class osp.core.session.wrapper_session.WrapperSession(engine)[source]

Bases: osp.core.session.session.Session

Common class for all wrapper sessions. Sets the engine and creates the sets with the changed elements

expire(*cuds_or_uids)[source]

Let cuds_objects expire. Expired objects will be reloaded lazily when attributed or relationships are accessed.

Parameters:cuds_or_uids (Union[Cuds, UUID]) – The cuds_object or uids to expire
Returns:The set of uids that became expired
Return type:Set[UUID]
expire_all()[source]

Let all cuds_objects of the session expire. Expired objects will be reloaded lazily when attributed or relationships are accessed.

Returns:The set of uids that became expired
Return type:Set[UUID]
get_triples()[source]

Get the triples in the core session

log_buffer_status(context)[source]

TODO

refresh(*cuds_or_uids)[source]

Refresh cuds_objects. Load possibly data of cuds_object from the backend.

Parameters:*cuds_or_uids

The cuds_object or uids to refresh

class osp.core.session.sim_wrapper_session.SimWrapperSession(engine, **kwargs)[source]

Bases: osp.core.session.wrapper_session.WrapperSession

class osp.core.session.db.db_wrapper_session.DbWrapperSession(engine)[source]

Bases: osp.core.session.wrapper_session.WrapperSession

Abstract class for a DB Wrapper Session

close()[source]

Close the connection to the database

class osp.core.session.db.sql_wrapper_session.SqlWrapperSession(engine)[source]

Bases: osp.core.session.db.db_wrapper_session.DbWrapperSession

Abstract class for an SQL DB Wrapper Session

static handle_vector_item(column, value, datatypes, temp_vec, old_vector_datatype)[source]

Check if a column corresponds to a vector. If it does, add it to the temp_vec list. Used during contract_vector_values

Parameters:
  • column (str) – The currect column to consider in the contraction
  • value (Any) – The value of the column
  • datatypes (List) – Maps a datatype to each column
  • temp_vec (List[float]) – The elements of the current vector.
  • old_vector_datatype (str) – The vector datatype of the old iteration.
Returns:

The new vector datatype and whether the current column corresponds to a vector

Return type:

Tuple[str, bool]

utils

class osp.core.utils.cuds2dot.Cuds2dot(root)[source]

Utility for creating a dot and png representation of the objects related to a given Cuds instance

render()[source]

Create the graph and save it to a dot and png file.

static shorten_uid(uid)[source]

Shortens the string of a given uid

Parameters:uid (UUID) – uuid to shorten
Returns:8 first and 3 last characters separated by ‘…’
Return type:str
osp.core.utils.general.branch(cuds_object, *args, rel=None)[source]

Like Cuds.add(), but returns the element you add to. This makes it easier to create large CUDS structures.

Parameters:
  • cuds_object (Cuds) – the object to add to
  • args (Cuds) – object(s) to add
  • rel (OntologyRelationship) – class of the relationship between the objects
Returns:

The first argument

Return type:

Cuds

Raises:

ValueError – adding an element already there

osp.core.utils.general.deserialize(json_doc, session=None)[source]

Deserialize the given json objects (to CUDS). Will add the CUDS objects to the buffers.

Parameters:
  • json_doc (Union[str, dict]) – the json document to load. Either string or already loaded json object.
  • session (Session, optional) – The session to add the CUDS objects to. Defaults to the CoreSession.
Returns:

The deserialized data. Can be CUDS.

Return type:

Any

osp.core.utils.general.get_rdf_graph(session=None)[source]

EXPERIMENTAL Get the RDF Graph from a session. If no session is, the core session will be used.

Parameters:session (Session, optional) – The session to compute the RDF Graph of. Defaults to None.
Returns:The resulting rdf Graph
Return type:rdflib.Graph
osp.core.utils.general.get_relationships_between(subj, obj)[source]

Get the set of relationships between two cuds objects.

Parameters:
  • subj (Cuds) – The subject
  • obj (Cuds) – The object
Returns:

The set of relationships between subject and object.

Return type:

Set[Type[Relationship]]

osp.core.utils.general.post(url, cuds_object, max_depth=inf)[source]

Will send the given CUDS object to the given URL. Will also send the CUDS object in the container recursively.

Parameters:
  • url (string) – The URL to send the CUDS object to
  • cuds_object (Cuds) – The CUDS to send
  • max_depth (int, optional) – The maximum depth to send CUDS objects recursively. Defaults to float(“inf”).
Returns:

[description]

Return type:

[type]

osp.core.utils.general.remove_cuds_object(cuds_object)[source]

Remove a cuds_object from the datastructure. Removes the relationships to all neighbours. To delete it from the registry you must call the sessions prune method afterwards.

Parameters:cuds_object – The cuds_object to remove.
osp.core.utils.pretty_print.pretty_print(cuds_object, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)[source]

Prints the given cuds_object with the uuid, the type, the ancestors and the description in a human readable way.

Parameters:cuds_object (Cuds) – container to be printed
osp.core.utils.simple_search.find_cuds_object(criterion, root, rel, find_all, max_depth=inf, current_depth=0, visited=None)[source]

Recursively finds an element inside a container by considering the given relationship.

Parameters:
  • criterion (Callable) – function that returns True on the Cuds object that is searched.
  • root (Cuds) – Starting point of search
  • rel (Type[Relationship]) – The relationship (incl. subrelationships) to consider
  • find_all (bool) – Whether to find all cuds_objects with satisfying the criterion.
  • max_depth (Union(float, int)) – The maximum depth for the search.
Returns:

the element if found

Return type:

Union[Cuds, List[Cuds]]

osp.core.utils.simple_search.find_cuds_object_by_uid(uid, root, rel)[source]

Recursively finds an element with given uid inside a cuds object by considering the given relationship.

Parameters:
  • uid (UUID) – The uid of the cuds_object that is searched.
  • root (Cuds) – Starting point of search
  • rel (Type[Relationship]) – The relationship (incl. subrelationships) to consider
Returns:

the element if found

Return type:

Cuds

osp.core.utils.simple_search.find_cuds_objects_by_attribute(attribute, value, root, rel)[source]

Recursively finds a cuds object by attribute and value by only considering the given relationship.

Parameters:
  • attribute (str) – The attribute to look for
  • value (Any) – The corresponding value to filter by
  • root (Cuds) – The root for the search
  • rel (Type[Relationship]) – The relationship (+ subrelationships) to consider.
Returns:

The found cuds objects.

Return type:

List[Cuds]

osp.core.utils.simple_search.find_cuds_objects_by_oclass(oclass, root, rel)[source]

Recursively finds an element with given oclass inside a cuds object by considering the given relationship.

Parameters:
  • oclass – The oclass of the cuds_object that is searched.
  • root (Cuds) – Starting point of search
  • rel (Type[Relationship]) – The relationship (incl. subrelationships) to consider
Returns:

The found suds objects.

Return type:

List[Cuds]

osp.core.utils.simple_search.find_relationships(find_rel, root, consider_rel, find_sub_rels=False)[source]

Find the given relationship in the subtree of the given root.

Parameters:
  • find_rel (Type[Relationship]) – The relationship to find
  • root (Cuds) – Only consider the subgraph rooted in this root.
  • consider_rel (Type[Relationship]) – Only consider these relationships when searching.
Returns:

The cuds objects having the given relationship.

Return type:

List[Cuds]

osp.core.utils.wrapper_development.change_oclass(cuds_object, new_oclass, kwargs)[source]

Change the oclass of a cuds object. Only allowed if cuds object does not have any neighbours.

Parameters:
  • cuds_object (Cuds) – The cuds object to change the oclass of
  • new_oclass (OntologyClass) – The new oclass of the cuds object
  • kwargs (Dict[str, Any]) – The keyword arguments used to instantiate cuds object of the new oclass
Returns:

The cuds object with the changed oclass

Return type:

Cuds

osp.core.utils.wrapper_development.check_arguments(types, *args)[source]

Checks that the arguments provided are of the certain type(s).

Parameters:
  • types (Union[Type, Tuple[Type]]) – tuple with all the allowed types
  • args (Any) – instances to check
Raises:

TypeError – if the arguments are not of the correct type

osp.core.utils.wrapper_development.clone_cuds_object(cuds_object)[source]

Avoid that the session gets copied.

Returns:A copy of self with the same session
Return type:Cuds
osp.core.utils.wrapper_development.create_from_cuds_object(cuds_object, session)[source]

Create a copy of the given cuds_object in a different session. WARNING: Will not recursively copy children.

Parameters:
  • cuds_object (Cuds) – The cuds object to copy
  • kwargs (Dict[str, Any]) – The kwargs of the cuds_object
  • session (Session) – The session of the new Cuds object
Returns:

A copy of self with the given session.

Return type:

Cuds

osp.core.utils.wrapper_development.create_recycle(oclass, kwargs, session, uid, fix_neighbours=True)[source]

Instantiate a cuds_object with a given session. If cuds_object with same uid is already in the session, this object will be reused.

Parameters:
  • oclass (Cuds) – The OntologyClass of cuds_object to instantiate
  • kwargs (Dict[str, Any]) – The kwargs of the cuds_object
  • session (Session) – The session of the new Cuds object
  • uid (UUID) – The uid of the new Cuds object
  • fix_neighbours (bool) – Whether to remove the link from the old neighbours to this cuds object, defaults to True
Result:

The created cuds object

Return type:

Cuds

osp.core.utils.wrapper_development.destroy_cuds_object(cuds_object)[source]

Reset all attributes and relationships. Use this for example if a cuds object has been deleted on the backend.

Parameters:cuds_object (Cuds) – The cuds object to destroy
osp.core.utils.wrapper_development.format_class_name(name)[source]

Formats a string to CapWords.

Parameters:name (str) – string to format
Returns:string with the name in CapWords
Return type:str
osp.core.utils.wrapper_development.get_neighbour_diff(cuds1, cuds2, mode='all')[source]

Get the uids of neighbours of cuds1 which are no neighbours in cuds2. Furthermore get the relationship the neighbours are connected with. Optionally filter the considered relationships.

Parameters:
  • cuds1 (Cuds) – A Cuds object.
  • cuds2 (Cuds) – A Cuds object.
  • mode (str) – one of “all”, “active”, “non-active”, whether to consider only active or non-active relationships.
Returns:

List of Tuples that contain the found uids and relationships.

Return type:

List[Tuple[UUID, Relationship]]