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_handler – `file`

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. label – `str` 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_handler – `file`

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.