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: Raises: ConstraintViolation – Raised if you are trying to create a duplicate edge between head and tail.
Returns: Added edge.
Return type:
-
add_vertex
(label=None, **kwargs)¶ Create a new vertex, add it to the graph, and return the newly created vertex.
Parameters: - label (
str
orNone
) – 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: - label (
-
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.
- label (
-
append_edge
(edge)¶ Append the edge to the graph.
Note
The edge that you are appending to the graph should have
ident
set toNone
, so that theIGraph
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:
-
append_vertex
(vertex)¶ Append the vertex to the graph.
Note
The vertex that you are appending to the graph should have
ident
set toNone
, so that theIGraph
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:
-
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
orIEdge
.
-
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
- 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
-
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: Returns: IEdge
that matched the filter criteria.Return type:
-
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
ortail
is atuple
, thenget_or_create_vertex()
will always be called to create the vertex.Parameters: Returns: Added edge.
Return type:
-
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
orNone
) – Vertex label. - kwargs (
str
, value.) – Property key and values to set on the new created vertex.
Returns: Added vertex.
Return type: - label (
-
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 labelstr
, keystr
-
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
orNone
- kwargs (
str
and value.) – Property key and value.
Returns: IVertex
that matched the filter criteria.Return type: - label – Vertice label. If
-
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
- 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
-
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
andIEdge
.
-
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 thebind_to_graph()
when they are bound to the a graph. If usingIEntity
andIEntitySet
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
()¶ Return the entity as a dictionary representation.
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.
- vertex (
-
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.
- vertex (
-
as_dict
()¶ Return the entity as a dictionary representation.
Returns: The entity as a dictionary representation. Return type: dict
-
get_both_edges
(label=None, **kwargs)¶ Return both
in
andout
edges to the vertex.Parameters: - label (
str
) – Edge label. IfNone
, all edges will be returned. - kwargs (key
str
and value.) – Edge property key and value pairs.
Returns: New
IEntitySet
with filtered entities.Return type: - label (
-
get_both_vertices
(label=None, **kwargs)¶ Return the
in
andout
vertices adjacent to the vertex according to the edges.Parameters: - label (
str
) – Vertices label. IfNone
, all edges will be returned. - kwargs (key
str
and value.) – Vertices property key and value pair.
Returns: New
IEntitySet
with filtered entities.Return type: - label (
-
get_in_edges
(label=None, **kwargs)¶ Return all the
in
edges to the vertex.Parameters: - label (
str
) – Edge label. IfNone
, all edges will be returned. - kwargs (key
str
and value.) – Edges property key and value pairs.
Returns: New
IEntitySet
with filtered entities.Return type: - label (
-
get_in_vertices
(label=None, **kwargs)¶ Return the
in
vertices adjacent to the vertex according to the edge.Parameters: - label (
str
) – Vertices label. IfNone
, all edges will be returned. - kwargs (key
str
and value.) – Vertices property key and value pairs.
Returns: New
IEntitySet
with filtered entities.Return type: - label (
-
get_out_edges
(label=None, **kwargs)¶ Return all the
out
edges to the vertex.Parameters: - label (
str
) – Edge label. IfNone
, all edges will be returned. - kwargs (key
str
and value.) – Edge property key and value pairs.
Returns: New
IEntitySet
with filtered entities.Return type: - label (
-
get_out_vertices
(label=None, **kwargs)¶ Return the
out
vertices adjacent to the vertex according to the edge.Parameters: - label (
str
) – Vertices label. IfNone
, all edges will be returned. - kwargs (key
str
and value.) – Vertices property key and value pairs.
Returns: New
IEntitySet
with filtered entities.Return type: - label (
-
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
()¶ Return the entity as a dictionary representation.
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.
-
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 existingIEntity
-
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. IfNone
, all entities are returned. - kwargs (key=value) – Property key and value.
Returns: All the items in the container.
Return type: list
containingIEntity
- label (
-
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()
oradd_edge()
methods) followed by one of these suffixes, to control how the given value is matched against theIEntity
‘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. IfNone
, all entities are returned. - kwargs (key=value) – Property key and value.
Returns: New
IEntitySet
with the entities that matched the filter criteria.Return type:
-
get
(ident)¶ Return the
IEntity
that has the identification number supplied by parameter identParameters: 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 indentReturn 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
ofstr
,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
containingIEntity
-