graphit package¶

Subpackages¶

graphit.graph module¶

file: graph.py

Graph base class implementing a graph based data storage with support for dictionary like storage of data in graph nodes and edges, rich graph comparison, query and traversal method and a Object Relations Mapper.

TODO: Would it be possible and useful to create support for config files: to configure a Graph and function arguments?
TODO: Dynamic class creation kills performance. Turning off run_node_new: or run_edge_new when creation new nodes and edges results in a enormous performance boost. Can we make the latter faster?

class graphit.graph.GraphBase(edges=None, directed=False, nodes=None, data=None, root=None, orm=None, storagedriver=<function init_dictstorage_driver>, **kwargs)¶

Bases: object

Graph base class

Graph root By default a graph is an undirected and non-rooted network of nodes. Many graph methods however require the definition of a root relative to which a calculation will be performed.

The graph class defines a root attribute for this purpose that is undefined by default. It will be set automatically in the following cases:

Node traversal: the first node selected (getnodes method) will be assigned root and traversal to child nodes will be done relative to the root. If multiple nodes are selected using getnodes, the root node is ambiguous and will be set to the node with the lowest nid.

add_edge(nd1, nd2, directed=None, node_from_edge=False, unicode_convert=True, run_edge_new=False, **kwargs)¶

Add edge between two nodes to the graph

An edge is defined as a connection between two node ID’s. Additional keyword arguments (kwargs) to the method are stored as edge metadata by the edge storage class.

Edges are always directional in the way they are stored. An undirectional edge is thus represented by a pair of two edges pointing in opposite directions. Directionality is defined globally by the graph ‘directed’ attribute and can be overridden locally by the method ‘directed’ attribute. If undirected the two edges of the undirected pair need to share the same metadata attributes. This enabled by using JSON style ‘$ref’ pointers that has one of the edges point to the data of the other. The pointer is transparently used by the edge storage class to get, set and delete attributes.

After de new edge is created the edge class ‘new’ method is called once to allow any custom edge initiation to be performed. This feature can be customized by overloading the ‘new’ method in the NodeEdgeToolsBaseClass abstract base class. Calling the ‘new’ method can be disabled using the run_node_new flag.

Parameters

nd1 – first node in edge node pair. Source node in directed graph.
nd2 – second node in edge node pair. Target node in directed graph.
directed (:py:bool) – override the graph definition for directed for the added edge.
node_from_edge (:py:bool) – make node for edge node id’s not in graph
unicode_convert (:py:bool) – convert string types to unicode
run_edge_new (:py:bool) – run the custom initiation method (new method) of the new edge once.
kwargs – any additional keyword arguments to be added as edge metadata.

Returns

edge ID

Return type

:py:tuple

add_edges(edges, node_from_edge=False, unicode_convert=True, run_edge_new=False, **kwargs)¶

Add multiple edges to the graph.

This is the iterable version of the add_edge methods allowing multiple edge additions from any iterable. If the iterable yields a tuple with a dictionary as third argument the key/value pairs of that dictionary will be added as attributes to the new edge along with any keyword arguments passed to the method.

The latter functionality can be used to add the edges of one graph to those of another by using graph.edges.items() as argument to add_edges.

Parameters

edges (Iterable of hashable objects) – Objects to be added as edges to the graph
node_from_edge (:py:bool) – make node for edge node id’s not in graph
unicode_convert (:py:bool) – convert string types to unicode
run_edge_new (:py:bool) – run the custom initiation method (new method) of the new edges once.

Returns

list of edge ids for the objects added in the same order as th input iterable.

Return type

:py:list

add_node(node=None, unicode_convert=True, run_node_new=False, **kwargs)¶

Add a node to the graph

All nodes are stored using a dictionary like data structure that can be represented like:

{nid: {‘_id’: auto_nid, attribute_key: attribute_value, ….}}

‘nid’ is the primary node identifier which is either an auto-incremented unique integer value if Graph.data.auto_nid equals True or a custom value when False.

If Graph.data.auto_nid equals True, the node parameter is stored as part of the node attributes (value in the above dict example) using the Graph.data.key_tag as key unless overloaded by any additional keyword arguments provided to the method. Using the key_tag and value_tag is a convenient way of storing node data that should be accessible using the same key. The key_tag and value_tag are used as default in the various dictionary style set and get methods of the graph, node and edge classes.

When Graph.data.auto_nid equals False, the node parameter becomes the primary node identifier that can be any hashable object except None.

Note

With auto_nid disabled the method checks if there is a node with nid in the graph already. If found, a warning is logged and the attributes of the existing node are updated.

The node attribute dictionary contains at least the ‘_id’ attribute representing the unique auto-incremented integer node identifier and any additional keyword argument provided to the method (kwargs)

After de new node is created the node class ‘new’ method is called once to allow any custom node initiation to be performed. This feature can be customized by overloading the ‘new’ method in the NodeEdgeToolsBaseClass abstract base class. Calling the ‘new’ method can be disabled using the run_node_new flag.

Parameters

node (any hashable object) – object representing the node
unicode_convert (:py:bool) – convert string types to unicode
run_node_new (:py:bool) – run the custom initiation method (new method) of the new node once.
kwargs – any additional keyword arguments to be added as node attributes.

Returns

node ID (nid)

Return type

int

add_nodes(nodes, unicode_convert=True, run_node_new=False, **kwargs)¶

Add multiple nodes to the graph.

This is the iterable version of the add_node methods allowing multiple node additions from any iterable. If the iterable yields a tuple with a dictionary as seconds argument the key/value pairs of that dictionary will be added as attributes to the new node along with any keyword arguments passed to the method.

The latter functionality can be used to add the nodes of one graph to those of another by using graph.nodes.items() as argument to add_nodes.

Parameters

nodes (Iterable of hashable objects) – Objects to be added as nodes to the graph
unicode_convert (:py:bool) – convert string types to unicode
run_node_new (:py:bool) – run the custom initiation method (new method) of the new nodes once.

Returns

list of node ids for the objects added in the same order as th input iterable.

Return type

:py:list

adjacency¶

clear()¶

Clear nodes and edges in the graph.

If the Graph instance represents a sub graph, only those nodes and edges will be removed.

copy(deep=True, copy_view=False)¶

Return a (deep) copy of the graph

The copy method offers shallow and deep copy functionality for graphs similar to Pythons building copy and deepcopy functions.

A shallow copy (python copy) will copy the class and its attributes except for the nodes, edges, orm and origin objects that are referenced. As such the copy will not be independent from the source Graph.

Using deep=True, a deep copy (python deepcopy) will be returned that is a new and fully independent copy of the source Graph. A new graph with only those nodes and edges represented by the node and edge ‘views’ will be returned by default. Setting the copy_view attribute to True will copy the full nodes and edges data set of the origin graph together with the views to the new graph.

Parameters

deep (:py:bool) – return a deep copy of the Graph object
copy_view (:py:bool) – make a deep copy of the full nodes and edges dictionary and set any ‘views’. Otherwise, only make a deep copy of the ‘view’ state.

Returns

copy of the graph

Return type

Graph object

data¶

directed¶

edge_tools¶

edges¶

empty()¶

Report if the graph is empty (no nodes)

Return type: :py:bool

get(nid, key=None, default=None, defaultattr=None)¶

Return (sub)graph values.

This is a placeholder method that can be overloaded by custom classes to return a value for (sub)graphs containing more than one edge or node in contrast to the single node or edge graph classes for which the get method returns attribute values. The get method has the latter functionality by default and will return single node or edge attributes based on nid.

Parameters

nid (mixed) – node or edge identifier to return data for. If not defined attempt to resolve using nid property.
key (mixed) – node or edge value attribute name. If not defined then attempt to use class wide key_tag attribute.
defaultattr (mixed) – node or edge value attribute to use as source of default data when key attribute is not present.
default (mixed) – value to return when all fails

getedges(edges, orm_cls=None, add_edge_tools=True)¶

Get an edge as graph object

Returns a new Graph with a ‘view’ on the selected nodes and the edges connecting them. If nodes equals None or empty list, the returned Graph object will have no nodes and is basically ‘empty’.

Getedges calls the Graph Object Relation Mapper (GraphORM) class to customize the returned (sub) Graph class. Next to the custom classes registered with the ORM mapper, the getedges method allows for further customization of the returned Graph object through the orm_cls attribute. In addition, for sub graphs containing single edges, the EdgeTools class is added.

The addition of the EdgeTools class changes the behaviour of the Graph class to a state where it provides direct access to edge attributes for that particular edge. This may be undesirable in cases where one wants to iterate over graphs even if they contain only one edge. The add_edge_tools attribute prevents addition of EdgeTools for these cases.

Parameters

edges (iterable of length 2 containing integers) – edge id
orm_cls (:py:list) – custom classes to construct new edge oriented Graph class from.
add_edge_tools (:py:bool) – add edge tools to Graph instance if one edge

getnodes(nodes, orm_cls=None, add_node_tools=True)¶

Get one or multiple nodes as new sub graph instance

Returns a new Graph with a ‘view’ on the selected nodes and the edges connecting them. If nodes equals None or empty list, the returned Graph object will have no nodes and is basically ‘empty’.

Getnodes calls the Graph Object Relation Mapper (GraphORM) class to customize the returned (sub) Graph class. Next to the custom classes registered with the ORM mapper, the getnodes method allows for further customization of the returned Graph object through the orm_cls attribute. In addition, for sub graphs containing single nodes, the NodeTools class is added.

The addition of the NodeTools class changes the behaviour of the Graph class to a state where it provides direct access to node attributes for that particular node. This may be undesirable in cases where one wants to iterate over graphs even if they contain only one node. The add_node_tools attribute prevents addition of NodeTools for these cases.

Parameters

nodes – single node ID or an iterable of multiple node ID’s
orm_cls (:py:list) – custom classes to construct new node oriented Graph class from.
add_node_tools (:py:bool) – add node tools to Graph instance if single node

Returns

Graph instance reflecting the node selection

Return type

:graphit:Graph

Raises

GraphitException, node check fails

insert(node, between)¶

Insert a new node in between two other

Parameters

node – node to add
between – nodes to add new node in between

items(keystring=None, valuestring=None, **kwargs)¶

Python dict-like function to return node items in the (sub)graph.

Keystring defines the value lookup key in the node data dict. This defaults to the graph key_tag. Valuestring defines the value lookup key in the node data dict.

Parameters

keystring (:py:str) – Data key to use for dictionary keys.
valuestring (:py:str) – Data key to use for dictionary values.

Returns

List of keys, value pairs

Return type

:py:list

iteredges(orm_cls=None, reverse=False, sort_key=<class 'str'>)¶

Graph edge iterator

Returns a new graph view object for the given edge and it’s nodes.

Parameters

orm_cls (list) – custom classes to construct new Graph class from for every edge that is returned
reverse (:py:bool) – switch between ascending and descending sort order of the returned edges
sort_key – function for sorting edge IDs. Equivalent to the ‘key’ argument to Pythons ‘sorted’ build in function.

Returns

single edge Graph object

Return type

:graphit:Graph

iternodes(orm_cls=None, reverse=False, sort_key=<class 'str'>)¶

Graph node iterator

Returns a new graph view object for the given node and it’s edges. The dynamically created object contains additional node tools. Nodes are returned in node ID sorted order.

Parameters

orm_cls (list) – custom classes to construct new Graph class from for every node that is returned
reverse (:py:bool) – switch between ascending and descending sort order of the returned nodes
sort_key – function for sorting node IDs. Equivalent to the ‘key’ argument to Pythons ‘sorted’ build in function.

Returns

single node Graph object

Return type

:graphit:Graph

keys(keystring=None, **kwargs)¶

Python dict-like function to return node keys in the (sub)graph.

Keystring defines the value lookup key in the node data dict. This defaults to the graph key_tag.

Parameters: keystring (:py:str) – Data key to use for dictionary keys.
Returns: List of keys
Return type: :py:list

masked¶

node_tools¶

nodes¶

origin¶

orm¶

query_edges(query=None, orm_cls=None, add_edge_tools=True, **kwargs)¶

Select edges based on edge data query

The query is executed by the query method of the respective edge storage driver class. That query method accepts a query function often as lambda function allowing for rich query functionality. The query_edges method accepts three different input arguments that are passed to the query method with some conversion if needed:

1 A dictionary where the key, value pairs are converted to a
lambda function evaluation ‘key == value’ against the edge attributes.

2 Additional keyword arguments used in the same way as in 1. 3 A custom (lambda) function passed to as is.

Matching edges are passed on to the getedges method and returned.

Parameters

query (:py:func) – query function as input to storage driver query method
orm_cls (:py:list) – custom classes added to new Graph class.
add_edge_tools (:py:bool) – add edge tools to Graph instance if single edge
kwargs – if query is None, build lambda function from keyword arguments

Returns

edges subgraph

Return type

:graphit:Graph

query_nodes(query=None, orm_cls=None, add_node_tools=True, **kwargs)¶

Select nodes based on node data query

The query is executed by the query method of the respective node storage driver class. That query method accepts a query function often as lambda function allowing for rich query functionality. The query_nodes method accepts three different input arguments that are passed to the query method with some conversion if needed:

1 A dictionary where the key, value pairs are converted to a
lambda function evaluation ‘key == value’ against the node attributes.

2 Additional keyword arguments used in the same way as in 1. 3 A custom (lambda) function passed to as is.

Matching nodes are passed on to the getnodes method and returned.

Parameters

query (:py:func) – query function as input to storage driver query method
orm_cls (:py:list) – custom classes added to new Graph class.
add_node_tools (:py:bool) – add node tools to Graph instance if single node
kwargs – if query is None, build lambda function from keyword arguments

Returns

nodes subgraph

Return type

:graphit:Graph

remove_edge(nd1, nd2, directed=None)¶

Removing an edge from the graph

Checks if the graph contains the edge, then removes it. If the graph is undirectional, try to remove both edges of the undirectional pair. Force directed removal of the edge using the ‘directed’ argument. Useful in mixed (un)-directional graphs.

If the graph is a (sub)graph representing a view on the origin graph, the edge is removed from the view and not from the origin.

Parameters

nd1 – first node in edge node pair. Source node in directed graph.
nd2 – second node in edge node pair. Target node in directed graph.
directed (:py:bool) – force directed removal of the edge

remove_edges(edges, directed=None)¶

Remove multiple edges from the graph.

This is the iterable version of the remove_edge methods allowing mutliple edge removal from any iterable.

Parameters

edges (Iterable of edges defined as tuples of two node ID's) – Iterable of edges to remove
directed (:py:bool) – force directed removal of the edge

remove_node(node)¶

Removing a node from the graph

Checks if the graph contains the node and if the node is connected with edges. Removes the node and associated edges.

If the graph is a (sub)graph representing a view on the origin graph, the node is removed from the view and not from the origin.

Parameters: node (mixed) – Node to remove

remove_nodes(nodes)¶

Remove multiple nodes from the graph.

This is the iterable version of the remove_node methods allowing multiple nodes to be removed from any iterable.

Parameters: nodes (mixed) – Nodes to remove

root¶

storagedriver¶

values(valuestring=None, **kwargs)¶

Python dict-like function to return node values in the (sub)graph.

Valuestring defines the value lookup key in the node data dict.

Parameters: valuestring (:py:str) – Data key to use for dictionary values.
Returns: List of values
Return type: :py:list

graphit.graph_exceptions module¶

file: graph_exceptions.py

Graphit specific exceptions

exception graphit.graph_exceptions.GraphitException¶

Bases: Exception

Base class for Graphit specific exceptions

Logs the exception as critical before raising.

exception graphit.graph_exceptions.GraphitAlgorithmError¶

Bases: graphit.graph_exceptions.GraphitException

Exception for unexpected termination of algorithms.

exception graphit.graph_exceptions.GraphitEdgeNotFound¶

Bases: graphit.graph_exceptions.GraphitException

Exception raised if edge is not present in the graph

exception graphit.graph_exceptions.GraphitNodeNotFound¶

Bases: graphit.graph_exceptions.GraphitException

Exception raised if node is not present in the graph

exception graphit.graph_exceptions.GraphitValidationError(message, graph)¶

Bases: graphit.graph_exceptions.GraphitException

Exception raised if validation on a (sub)graph failed

graphit.graph_helpers module¶

graphit.graph_helpers.adjacency_to_edges(nodes, adjacency, node_source)¶

Construct edges for nodes based on adjacency.

Edges are created for every node in nodes based on the neighbors of the node in adjacency if the neighbor node is also in node_source. The source of adjacency information would normally be self.graph and self.nodes for node_source. However, node_source may also equal nodes to return edges for the isolated graph.

Parameters

nodes (list) – nodes to return edges for
adjacency (dict) – node adjacency (self.graph)
node_source (list) – other nodes to consider when creating edges

graphit.graph_helpers.check_nodes_in_graph(graph, nodes)¶

Validate if nodes are in graph

Parameters

graph (:graphit:GraphBase) – graph that should contain nodes
nodes (:py:list) – nodes to check

Returns

True if validation successful

Return type

:py:bool

:raises GraphitNodeNotFound

graphit.graph_helpers.edge_list_to_adjacency(edges)¶

Create adjacency dictionary based on a list of edges

Parameters: edges (:py:list) – edges to create adjacency for
Return type: :py:dict

graphit.graph_helpers.edge_list_to_nodes(edges)¶

Create a list of nodes from a list of edges

Parameters: edges (list) – edges to create nodes for

graphit.graph_helpers.edges_between_nodes(graph, nodes)¶

Return all edges in graph that connect the nodes

Parameters

graph –
nodes –

Returns

graphit.graph_helpers.graph_directionality(graph)¶

Return a graph overall directionality as ‘directional’, ‘undirectional’ or ‘mixed’

Parameters: graph – Graph to asses directionality of
Returns: ‘directional’, ‘undirectional’ or ‘mixed’
Return type: :py:str

graphit.graph_helpers.make_edges(nodes, directed=True)¶

Create an edge tuple from two nodes either directed (first to second) or undirected (two edges, both ways).

Parameters

nodes (:py:list, py:tuple) – nodes to create edges for
directed (bool) – create directed edge or not

graphit.graph_helpers.make_undirected_edges(edges)¶

Complete a list of (directed) edges with their undirected equivalent

Parameters: edges –
Returns

graphit.graph_helpers.renumber_id(graph, start)¶

Renumber all node ID’s in the graph from a new start ID and adjust edges accordingly. Useful when duplicating a graph substructure. If the graph uses auto_nid, the node nid is also changed.

#TODO: this one failes if run on a subgraph. Probably need to make changes #to nids in place instead of registering new storage

Parameters

graph (Graph object) – Graph object to renumber
start (:py:int) – New start number to renumber from

Returns

Renumber graph and mapping of old to new ID

Return type

Graph object, :py:dict

graphit.graph_helpers.share_common_origin(*args)¶

Check if (sub)graphs share the same origin graph based on object id.

Parameters: args – list of graphs
Return type: :py:bool

graphit.graph_mixin module¶

file: graph_mixin.py

Defines an abstract base class for node and edge tool classes that are used for dynamic (ORM based) Graph class creation. Node and Edge tools are used (sub)graphs containing a single node or single edge respectively.

class graphit.graph_mixin.NodeTools¶

Bases: graphit.graph_mixin.NodeEdgeToolsBaseClass

Node specific tools

connected_edges()¶

Return the connected edges to a node

Returns: connected edges
Return type: list

get(key=None, default=None, defaultattr=None)¶

Return node value

Get direct access to relevant node attributes. If key is not defined the method returns the value of the default value_tag which is equivalent to returning the value for a dictionary key where the key is either the nid or the key_tag attribute.

Parameters

key (mixed) – node value attribute name. If not defined then attempt to use class wide value_tag attribute.
defaultattr (mixed) – node or edge value attribute to use as source of default data when key attribute is not present.
default (mixed) – value to return when all fails

property isleaf¶

Check if the current selected node is a leaf node.

Return type: bool

property nid¶

Return the nid of the current selected node.

Returns: node nid

set(key, value=None)¶

Set node attribute values.

Parameters

key – node attribute key
value – node attribute value

class graphit.graph_mixin.EdgeTools¶

Bases: graphit.graph_mixin.NodeEdgeToolsBaseClass

Edge specific tools

get(key=None, default=None, defaultattr=None)¶

Return edge value

Used by the value method to get direct access to relevant node or edge attributes. The value method itself is a placeholder method that can be overloaded by custom classes to post process the data before returning it.

Parameters

key (mixed) – node or edge value attribute name. If not defined then attempt to use class wide key_tag attribute.
defaultattr (mixed) – node or edge value attribute to use as source of default data when key attribute is not present.
default (mixed) – value to return when all fails

property is_directed¶

Determine if edge is directed based

An edge is undirected if both edges of a pair pointing in opposite directions are present.

Return type: :py:bool

property nid¶

Return the eid of the current selected edge.

Returns: edge eid

set(key, value, **kwargs)¶

Set edge attribute values. The method may be overloaded in custom classes to pre-process data before setting.

Parameters

key – edge attribute key
value – edge attribute value

graphit.graph_networkx module¶

file: graph_networkx.py

Provides a NetworkX compliant Graph class.

class graphit.graph_networkx.NetworkXGraph(*args, **kwargs)¶

Bases: graphit.graph.GraphBase

add_edges_from(edges, **kwargs)¶

add_nodes_from(nodes, **kwargs)¶

add_weighted_edges_from(edges, weight='weight', **kwargs)¶

Add edges with a numeric weight factor

Parameters

edges – edges as iterable of tuples with length 3 containing (node1, node2, weight value)
weight (:py:str) – edge weight attribute name
kwargs – additional keyword arguments passed to add_edge

Returns

list of edge ids for the objects added in the same order as th input iterable.

Return type

:py:list

property adj¶

adjacency¶

data¶

property degree¶

directed¶

edge_subgraph(edges)¶

edge_tools¶

edges¶

get_edge_data(n1, n2, default=None)¶

has_edge(n1, n2)¶

has_node(node)¶

is_directed()¶

Return graph directionality

A graph with mixed edges (partly directed, partly undirected) is considered a directed graph.

Returns: directed or undirected graph
Return type: :py:bool

masked¶

nbunch_iter(nodes=None)¶

neighbors(node)¶

node_tools¶

nodes¶

number_of_edges(first=None, second=None)¶

number_of_nodes()¶

Return the number of nodes in the graph similar to __len__

Returns: Number of nodes
Return type: :py:int

order()¶

Return the number of nodes in the graph similar to __len__

Returns: Number of nodes
Return type: :py:int

origin¶

orm¶

remove_edges_from(*args, **kwargs)¶

remove_nodes_from(*args, **kwargs)¶

root¶

size(weight=None)¶

storagedriver¶

subgraph(nodes)¶

to_directed()¶

to_undirected()¶

update(edges=None, nodes=None)¶

graphit.graph_orm module¶

file: graph_orm.py

Defines the Graph Object Relation Mapper (ORM)

class graphit.graph_orm.GraphORM(node_mapping=None, edge_mapping=None, inherit=True)¶

Bases: object

Graph Object Relation Mapper (ORM) class

An Object Relation Mapper encapsulates data in an object based on a series of rules. It is an often used concept in database bindings in particular for dynamically typed languages such as Python.

graphit uses an ORM to return customized versions of the Graph/GraphAxis classes at runtime based on rules matched against node or edge attributes. It is a powerful method to extend the Graph base class with new methods or override existing ones.

How it works ORM mapping is performed by registering custom classes for nodes or edges together with a matching function using the add method on the node_mapping and edge_mapping methods respectively. For each call to the get_nodes or get_edges methods of the ORM, all registered matching functions will be evaluated and the classes for positive matches will be included in the newly generated Graph/GraphAxis class together with other classes defined by the orm_cls argument of the getnodes or getedges methods.

Matching functions Matching is based on a match function (match_func argument) that requires the node or edge attribute dictionary as input and needs to return a boolean for the matching result.

An example of a matching function where x is the node or edge dictionary:

lambda x: x.get(‘arg’) == 1 and ‘conf’ in x

A lambda function is convenient but any function accepting a dictionary and returning a boolean will do. The benefit of using functions is the freedom in defining the matching criteria.

Class inheritance Class inheritance is respected by the ORM and can be controlled. By default, the base class used in a mapping is the one from which the call to the getnodes or getedges methods was made. This includes the Graph base class and any custom methods added to it by the user or previous calls to the ORM. Inheritance can be disabled by setting the inherit variable on the ORM class to False.

The Method Resolution Order (mro) A new class is dynamically build by the class factory of the ORM from a list of classes that include required graph base classes and custom classes. The ORM ensures that the right Python method resolution order is defined. When multiple classes in the mro have similarly named methods the order affects the final class behaviour through method override.

The mro can be controlled using the mro_pos argument that can be defined as part of a registered custom node or edge (add method). This argument influence the sort order of resolved classes in the MRO following the rule: smaller indices are resolved first. The mro_pos index may be both a negative to large positive number to force first or last resolution respectively. This is also important when using Pythons build-in ‘super’ function to call similar named method up the MRO stack.

Current scope of the ORM The ORM is used in the getnodes and getedges methods of the Graph class but only when a single node or edge is requested as it is currently designed to only match against the attributes of a single node or edge. This is primarily done to guard performance by limiting the amount of ORM matching evaluations performed. In addition the number of edges that need evaluation for a single node and vice versa depends on graph directionality and masking which may cause ambiguous behaviour for now.

However, both getnodes and getedges will accept custom classes that will be included in the newly generated Graph class regardless of the ORM results (orm_cls argument). This allows to partly bypass current limitations of the ORM by writing custom evaluation code.

edge_mapping¶

get_edges(graph, edges, classes=None)¶

Resolve mapped edges

Edge mapping and construction of custom classes is only performed when a single edge is provided. For multiple edges or when the query yields no result, the same class is returned base on the Graph instance making the call to the get method including any custom classes defined.

Parameters

graph (:graphit:graph:Graph) – a graph to match against
edges (:py:list) – one or more edges
classes (:py:list or :py:tuple) – additional classes to include in the base class when building the custom Graph class

Returns

new Graph class instance

get_nodes(graph, nodes, classes=None)¶

Resolve mapped nodes

Node mapping and construction of custom classes is only performed when a single node is provided. For multiple nodes or when the query yields no result, the same class is returned base on the Graph instance making the call to the get method including any custom classes defined.

Parameters

graph (:graphit:graph:Graph) – a graph to match against
nodes (:py:list) – one or more nodes
classes (:py:list or :py:tuple) – additional classes to include in the base class when building the custom Graph class

Returns

new Graph class instance

inherit¶

node_mapping¶

orm_class_factory(base_cls, classes, exclude_node_edge=False)¶

Factory for custom Graph classes

Build custom Graph class by adding classes to base_cls. The factory resolves the right method resolution order (mro).

Use the exclude_node_edge argument to prevent inheritance of classes that operate on single node or edge graphs such as the NodeTools class. This is important in for instance a query returning multiple nodes called from a single node object. Classes are identified by having the __isnetbc__ class variable part of the NodeEdgeToolsBaseClass abstract base class that custom node or edge classes should inherit from.

Parameters

base_cls (:py:class) – graph base class. Needs to be based on Graph
classes (:py:list) – additional classes to include in base class when building custom Graph class sorted according to the desired method resolution order
exclude_node_edge (:py:bool) – prevent including specific single node or edge classes (such as NodeTools) when returning an interface to multiple nodes or edges.

Returns

custom Graph class

Return type

:py:class

Module contents¶

#Graph module

###Basic graph structure A graph represented by a Graph class is an object that stores nodes, edges and adjacency information in seperate DictStorage classes. A DictStorage class is a subclass of the standard Python dictionary and collections MutableMappings Abstract Base Class (ABC).

The nodes and edges DictStorage objects store node and edge attributes respectivly based on the node ID (nid). The graph DictStorage object stores node adjacency and is the primary store for the graph topology.

###Node ID The node ID or nid for short is the unique identifier of a node and derived edges in the graph. The nid itself can be any hasable object except None. Set auto_nid to True in the graph to ensure all added nodes are automatically assigned a unique auto incremented integer ID.

###Graph directionality A graph is undirected by default storing an two edges for every connected node, one in each direction. Change the graph directed attribute to True will ensure that every every newly added edge is directed. Directed and undirected edges can be mixed in the same graph.

###Graph query and iteration The graph module has a rich palet of functions to query and analyze graphs. For performance reasons, most of these will return node or edge IDs. New Graph object representing a node and/or edge selection can returned using one of the following Graph methods:

getnodes: return subgraph based on one or more nodes
getedges: return subgraph based on one or more edges
iternodes: iterate over nodes in the graph. Uses getnodes
iteredges: iterate over edges in the graph. Uses getedges
query_nodes: return subgraph based on a query over node attributes
query_edges: return subgraph based on a query over edge attributes

The subgraphs returned by these methods are implemented as a dictionary view over the keys in the nodes and edges DictStorage objects. By default this means that the subgraphs are fully isolated from the parent graph. Returning a single node using getnodes will have no neighbors. This may not be desirable in circumstances where you want a view over nodes but retain connectivity with nodes outside of the view. This behaviour is enabled by switching the Graph masked to False.

graphit.check_graphaxis_instance(*args)¶

Validate if all objects in args are instances of the GraphAxis class

Parameters: args – Arguments to check
Returns: True if validation successful
Return type: :py:bool
Raises: AttributeError if validation fails

graphit.check_graphbase_instance(*args)¶

Validate if all objects in args are instances of the GraphBase class

Parameters: args – Arguments to check
Returns: True if validation successful
Return type: :py:bool
Raises: AttributeError if validation fails

graphit.version(digits=3)¶

Return a string representation of the graphit __version__

Graphit version follows the semantic versioning guidelines formatted as

The full version string is returned by default but number of significant version digits can be set using the digits argument.

Parameters: digits (:py:int) – number of digits to format version string
Return type: :py:str