Interfaces

Graph

class ruruki.interfaces.IGraph

Interface for a property graph database.

add_edge(head, label, tail, **kwargs)

Add an directed edge to the graph.

Note

If you wish to add in a undirected edge, you should add a directed edge in each direction.

Parameters:
  • head (IVertex) – Head vertex.
  • label (str) – Edge label.
  • tail (IVertex) – Tail vertex.
  • kwargs (str, value.) – Property key and values to set on the new created edge.
Raises:

ConstraintViolation – Raised if you are trying to create a duplicate edge between head and tail.

Returns:

Added edge.

Return type:

IEdge

add_vertex(label=None, **kwargs)

Create a new vertex, add it to the graph, and return the newly created vertex.

Parameters:
  • label (str or None) – Vertex label.
  • kwargs (str, value.) – Property key and values to set on the new created vertex.
Raises:

ConstraintViolation – Raised if you are adding a new vertex that violates a constraint.

Returns:

Added vertex.

Return type:

IVertex

add_vertex_constraint(label, key)

Add a constraint to ensure uniqueness for a particular label and property key.

Parameters:
  • label (str) – Vertex label which the constraint is meant for.
  • key (str) – Vertex property key used to ensure uniqueness.
append_edge(edge)

Append the edge to the graph.

Note

The edge that you are appending to the graph should have ident set to None, so that the IGraph can manage what the identity number should be.

Parameters:

edge (IEdge) – Edge that should be appended to the graph.

Raises:
  • ConstraintViolation – Raised if you are trying to create a duplicate edge between head and tail.
  • EntityIDError – If the edge already has a identity number set.
  • DatabaseError – If the edge already is already bound to anther IGraph.
Returns:

The edge after it has been appended to the graph.

Return type:

IEdge

append_vertex(vertex)

Append the vertex to the graph.

Note

The vertex that you are appending to the graph should have ident set to None, so that the IGraph can manage what the identity number should be.

Parameters:

vertex (IVertex) – Vertex that should be appended to the graph.

Raises:
  • ConstraintViolation – Raised if you are appending a new vertex that violates a constraint.
  • EntityIDError – If the vertex already has a identity number set.
  • DatabaseError – If the vertex already is already bound to anther IGraph.
Returns:

The vertex after it has been appended to the graph.

Return type:

IVertex

bind_to_graph(entity)

Bind an entity to the graph and generate and set a unique id on the entity.

Parameters:entity (IEntity) – Entity that you are binding to the graph.
Raises:UnknownEntityError – Is raised if the entity is not a instance if a IVertex or IEdge.
close()

Close the instance.

dump(file_handler)

Export the database to a file handler.

Parameters:
  • file_handler – A writable file-like object; a description of this graph will be written to this file encoded as JSON data that can be read back later with load().
  • file_handlerfile
get_edge(id_num)

Return the edge referenced by the provided object identifier.

Parameters:id_num (int) – Edge identity number.
Returns:Added edge.
Return type:IEdge
get_edges(head=None, label=None, tail=None, **kwargs)

Return an iterable of all the edges in the graph that have a particular key/value property.

Note

See IEntitySet.filter() for filtering options.

Parameters:
  • head (IVertex) – Head vertex of the edge. If None then heads will be ignored.
  • label (str or None) – Edge label. If None then all edges will be checked for key and value.
  • tail (IVertex) – Tail vertex of the edge. If None then tails will be ignored.
  • kwargs (str and value.) – Property key and value.
Returns:

IEdge that matched the filter criteria.

Return type:

IEntitySet

get_or_create_edge(head, label, tail, **kwargs)

Get or create a unique directed edge.

Note

If you wish to add in a unique undirected edge, you should add a directed edge in each direction.

If head or tail is a tuple, then get_or_create_vertex() will always be called to create the vertex.

Parameters:
  • head (IVertex or tuple of label str and properties dict) – Head vertex.
  • label (str) – Edge label.
  • tail (IVertex or tuple of label str and properties dict) – Tail vertex.
  • kwargs (str, value.) – Property key and values to set on the new created edge.
Returns:

Added edge.

Return type:

IEdge

get_or_create_vertex(label=None, **kwargs)

Get or create a unique vertex.

Note

Constraints will always be applied first when searching for vertices.

Parameters:
  • label (str or None) – Vertex label.
  • kwargs (str, value.) – Property key and values to set on the new created vertex.
Returns:

Added vertex.

Return type:

IVertex

get_vertex(id_num)

Return the vertex referenced by the provided object identifier.

Parameters:id_num (int) – Vertex identity number.
Returns:Vertex that has the identity number.
Return type:IVertex
get_vertex_constraints()

Return all the known vertex constraints.

Returns:Distinct label and key pairs to add_vertex_constraint().
Return type:Iterable of tuple of label str, key str
get_vertices(label=None, **kwargs)

Return all the vertices in the graph that have a particular key/value property.

Note

See IEntitySet.filter() for filtering options.

Parameters:
  • label – Vertice label. If None then all vertices will be checked for key and value.
  • labelstr or None
  • kwargs (str and value.) – Property key and value.
Returns:

IVertex that matched the filter criteria.

Return type:

IEntitySet

load(file_handler)

Load and import data into the database. Data should be in a JSON format.

Note

Id’s are not retained and are regenerated. This allows you to load multiple dumps into the same graph.

Parameters:
  • file_handler – A file-like object that, when read, produces JSON data describing a graph. The JSON data should be compatible with that produced by dump().
  • file_handlerfile
remove_edge(edge)

Remove the provided edge from the graph.

Note

Removing a edge does not remove the head or tail vertices, but only the edge between them.

Parameters:edge (IEdge) – Remove a edge/relationship.
remove_vertex(vertex)

Remove the provided vertex from the graph.

Parameters:vertex (IVertex) – Remove a vertex/node.
Raises:VertexBoundByEdges – Raised if you are trying to remove a vertex that is still bound or attached to another vertex via edge.
set_property(entity, **kwargs)

Set or update the entities property key and values.

Parameters:

kwargs (str, value.) – Property key and values to set on the new created vertex.

Raises:
  • ConstraintViolation – A constraint violation is raised when you are updating the properties of a entity and you already have a entity with the constrained property value.
  • UnknownEntityError – If you are trying to update a property on a IEntity that is not known in the database.
  • TypeError – If the entity that you are trying to update is not supported by the database. Property updates only support Ivertex and IEdge.

Base Entity

class ruruki.interfaces.IEntity

Base interface for a vertex/node and edge/relationship.

Note

Identity numbers are None by default. They are set by the bind_to_graph() when they are bound to the a graph. If using IEntity and IEntitySet without a bound graph, you will need to manually set the ident yourself.

IDGenerator can help you with assigning id’s to vertices and edges.

as_dict(include_privates=False)

Return the entity as a dictionary representation.

>>> from pprint import pprint
>>> from ruruki.entities import Entity
>>> e = Entity("Person")
>>> e.set_property(name="Bob")
>>> e.set_property(_private_name="Sasquatch")
>>> pprint(e.as_dict()["properties"])
{'name': 'Bob'}

>>> pprint(e.as_dict(include_privates=True)["properties"])
{'_private_name': 'Sasquatch', 'name': 'Bob'}
Parameters:include_privates (bool) – True to include private property keys in the dump. Private property keys are those that begin with “_”.
Returns:The entity as a dictionary representation.
Return type:dict
is_bound()

Return True if the entity is bound to a graph.

Returns:True is the entity is bound to a IGraph
Return type:bool
remove_property(key)

Un-assigns a property key with its value.

Parameters:key (str) – Key that you are removing.
set_property(**kwargs)

Assign or update a property.

Parameters:kwargs (key str and value.) – Key and value pairs.

Vertex

class ruruki.interfaces.IVertex

Interface for a vertex/node.

add_in_edge(vertex, label=None, **kwargs)

Add and create an incoming edge between the two vertices.

Parameters:
  • vertex (IVertex) – Edge the vertex is attached to.
  • label (str) – Label for the edge being created.
  • kwargs (str and value) – Key and values for the edges properties.
add_out_edge(vertex, label=None, **kwargs)

Add and create an outgoing edge between the two vertices.

Parameters:
  • vertex (IVertex) – Edge the vertex is attached to.
  • label (str) – Label for the edge being created.
  • kwargs (key str and value.) – Edges property key and value pairs.
as_dict(include_privates=False)

Return the entity as a dictionary representation.

>>> from pprint import pprint
>>> from ruruki.entities import Entity
>>> e = Entity("Person")
>>> e.set_property(name="Bob")
>>> e.set_property(_private_name="Sasquatch")
>>> pprint(e.as_dict()["properties"])
{'name': 'Bob'}

>>> pprint(e.as_dict(include_privates=True)["properties"])
{'_private_name': 'Sasquatch', 'name': 'Bob'}
Parameters:include_privates (bool) – True to include private property keys in the dump. Private property keys are those that begin with “_”.
Returns:The entity as a dictionary representation.
Return type:dict
get_both_edges(label=None, **kwargs)

Return both in and out edges to the vertex.

Parameters:
  • label (str) – Edge label. If None, all edges will be returned.
  • kwargs (key str and value.) – Edge property key and value pairs.
Returns:

New IEntitySet with filtered entities.

Return type:

IEntitySet

get_both_vertices(label=None, **kwargs)

Return the in and out vertices adjacent to the vertex according to the edges.

Parameters:
  • label (str) – Vertices label. If None, all edges will be returned.
  • kwargs (key str and value.) – Vertices property key and value pair.
Returns:

New IEntitySet with filtered entities.

Return type:

IEntitySet

get_in_edges(label=None, **kwargs)

Return all the in edges to the vertex.

Parameters:
  • label (str) – Edge label. If None, all edges will be returned.
  • kwargs (key str and value.) – Edges property key and value pairs.
Returns:

New IEntitySet with filtered entities.

Return type:

IEntitySet

get_in_vertices(label=None, **kwargs)

Return the in vertices adjacent to the vertex according to the edge.

Parameters:
  • label (str) – Vertices label. If None, all edges will be returned.
  • kwargs (key str and value.) – Vertices property key and value pairs.
Returns:

New IEntitySet with filtered entities.

Return type:

IEntitySet

get_out_edges(label=None, **kwargs)

Return all the out edges to the vertex.

Parameters:
  • label (str) – Edge label. If None, all edges will be returned.
  • kwargs (key str and value.) – Edge property key and value pairs.
Returns:

New IEntitySet with filtered entities.

Return type:

IEntitySet

get_out_vertices(label=None, **kwargs)

Return the out vertices adjacent to the vertex according to the edge.

Parameters:
  • label (str) – Vertices label. If None, all edges will be returned.
  • kwargs (key str and value.) – Vertices property key and value pairs.
Returns:

New IEntitySet with filtered entities.

Return type:

IEntitySet

in_edge_count()

Return the total number of in edges.

Returns:Total number of in edges.
Return type:int
is_bound()

Return True if the entity is bound to a graph.

Returns:True is the entity is bound to a IGraph
Return type:bool
out_edge_count()

Return the total number of out edges.

Returns:Total number of out edges.
Return type:int
remove_edge(edge)

Remove a IEdge from the vertex if it exists.

Parameters:edge (IEdge) – Edge that you are removing from the vertex.
Raises:KeyError – KeyError is raised if you are trying to remove an edge that is not found or does not exist.
remove_property(key)

Un-assigns a property key with its value.

Parameters:key (str) – Key that you are removing.
set_property(**kwargs)

Assign or update a property.

Parameters:kwargs (key str and value.) – Key and value pairs.

Edge

class ruruki.interfaces.IEdge

Interface for a edge/relationship.

as_dict(include_privates=False)

Return the entity as a dictionary representation.

>>> from pprint import pprint
>>> from ruruki.entities import Entity
>>> e = Entity("Person")
>>> e.set_property(name="Bob")
>>> e.set_property(_private_name="Sasquatch")
>>> pprint(e.as_dict()["properties"])
{'name': 'Bob'}

>>> pprint(e.as_dict(include_privates=True)["properties"])
{'_private_name': 'Sasquatch', 'name': 'Bob'}
Parameters:include_privates (bool) – True to include private property keys in the dump. Private property keys are those that begin with “_”.
Returns:The entity as a dictionary representation.
Return type:dict
get_in_vertex()

Return the in/head vertex.

Returns:In vertex.
Return type:IVertex
get_out_vertex()

Return the out/tail vertex.

Returns:Out vertex.
Return type:IVertex
is_bound()

Return True if the entity is bound to a graph.

Returns:True is the entity is bound to a IGraph
Return type:bool
remove_property(key)

Un-assigns a property key with its value.

Parameters:key (str) – Key that you are removing.
set_property(**kwargs)

Assign or update a property.

Parameters:kwargs (key str and value.) – Key and value pairs.

Entity Set

class ruruki.interfaces.IEntitySet

Interface for a entity containers.

add(entity)

Add a unique entity to the set.

Parameters:entity (IEntity) – Unique entity being added to the set.
Raises:KeyError – KeyError is raised if the entity being added to the set has a ident conflict with an existing IEntity
all(label=None, **kwargs)

Return all the items in the container as a list.

Parameters:
  • label (str) – Filter for entities that have a particular label. If None, all entities are returned.
  • kwargs (key=value) – Property key and value.
Returns:

All the items in the container.

Return type:

list containing IEntity

clear()

This is slow (creates N new iterators!) but effective.

discard(entity)

Remove a entity from the current set.

Parameters:entity (IEntity) – Entity to be removed from the set.
Raises:KeyError – KeyError is raised if the entity being discared does not exists in the set.
filter(label=None, **kwargs)

Filter for all entities that match the given label and properties returning a new IEntitySet

Note

Keywords should be made of a property name (as passed to the add_vertex() or add_edge() methods) followed by one of these suffixes, to control how the given value is matched against the IEntity‘s values for that property.

  • __contains
  • __icontains
  • __startswith
  • __istartswith
  • __endswith
  • __iendswith
  • __le
  • __lt
  • __ge
  • __gt
  • __eq
  • __ieq
  • __ne
  • __ine
Parameters:
  • label (str) – Filter for entities that have a particular label. If None, all entities are returned.
  • kwargs (key=value) – Property key and value.
Returns:

New IEntitySet with the entities that matched the filter criteria.

Return type:

IEntitySet

get(ident)

Return the IEntity that has the identification number supplied by parameter ident

Parameters:ident (int) – Identification number.
Raises:KeyError – Raised if there are no IEntity that has the given identification number supplied by parameter ident.
Returns:The IEntity that has the identification number supplied by parameter indent
Return type:Iterable of str
get_indexes()

Return all the index labels and properties.

Returns:All the index label and property keys.
Return type:Iterable of tuple of str, str
get_labels()

Return labels known to the entity set.

Returns:All the the labels known to the entity set.
Return type:Iterable of str
isdisjoint(other)

Return True if two sets have a null intersection.

pop()

Return the popped value. Raise KeyError if empty.

remove(entity)

Like discard(), remove a entity from the current set.

Parameters:entity (IEntity) – Entity to be removed from the set.
Raises:KeyError – KeyError is raised if the entity being removed does not exists in the set.
sorted(key=None, reverse=False)

Sort and return all items in the container.

Parameters:
  • key (callable) – Key specifies a function of one argument that is used to extract a comparison key from each list element. The default is to compare the elements directly.
  • reverse (bool) – If set to True, then the list elements are sorted as if each comparison were reverted.
Returns:

All the items in the container.

Return type:

list containing IEntity

update_index(entity, **kwargs)

Update the index with the new property keys.

Parameters:
  • entity (IEntity) – Entity with a set of properties that need to be indexed.
  • kwargs (str, value.) – Property key and values to set on the new created vertex.

Locks

class ruruki.interfaces.ILock

Interface for locking.

acquire()

Acquire a lock.

Raises:AcquireError – If a lock failed to be acquired.
release()

Release the lock.

Raises:ReleaseError – If the lock was unable to be released.