objectgraph - Reference documentation

A basic graph library

This package provides a class ObjectGraph that represents a basic graph where nodes are arbitrary objects with a string-values attribute named “identifier”.

Edges between nodes have arbrary (hashable) attributes, where edges with the same source, destination and attributes are collapsed into one edge.

Graph

class objectgraph.ObjectGraph

A basic graph datastructure where the nodes can be arbitrary objects with an attribute named “identifier”. Edges between nodes can have associated data.

There can be multiple edges between nodes, but all edges with the same attributes are collapsed into one edge.

For Mypy users this is a generic class with two type parameters:

  • The node type

    An arbitrary that that has an string-valued attribute named “identifier”

  • The edge type

    An arbirary type that is hashable.

Creating and updating a graph

ObjectGraph.__init__() → None

Create a new empty graph

ObjectGraph.add_node(node: NODE_TYPE) → None

Add a root to the graph

Parameters:

node – A node

ObjectGraph.add_root(node: str | NODE_TYPE) → None

Add a root to the graph

Parameters:

node – A node or name of a node.

Raises:

KeyError – if the node is not part of the graph

ObjectGraph.add_edge(source: str | NODE_TYPE, destination: str | NODE_TYPE, edge_attributes: EDGE_TYPE) → None

Add a directed edge between source and destination with edge attributes. Edges between the source and destination with the same edge attributes are merged into a single edge.

Parameters:

  • source – A node or node identifier

  • destination – A node or node identifier

  • edge_attributes – Attributes for the edge, must be hashable

Raises:

KeyError – If the source or destination are not nodes in the graph

ObjectGraph.remove_edge(source: str | NODE_TYPE, destination: str | NODE_TYPE, edge_attributes: EDGE_TYPE) → None

Remove an edge from the graph

Parameters:

  • source – a node or node identifier

  • destination – a node or node identifier

  • edge_attributes – attributes of the edge that should be removed

Raises:

  • KeyError – If the source of destination are not found

  • KeyError – If there is no edge between source and destination with the specified attributes

ObjectGraph.remove_all_edges(source: str | NODE_TYPE, destination: str | NODE_TYPE)

Remove all edges between source and destination.

Parameters:

  • source – a node or node identifier

  • destination – a node or node identifier

Raises:

KeyError – If the source of destination are not found

ObjectGraph.remove_root(node: str | NODE_TYPE) → None

Removes one of the graph roots, without removing the node from the graph.

Parameters:

node – A node or node identifier

Raises:

KeyError – if the node is not a root of the graph

ObjectGraph.remove_node(node: str | NODE_TYPE) → None

Removes a node and related information from the graph.

Parameters:

node – The node or node identifier to remove

Raises:

KeyError – If the node is not part of the graph

Reporting on a graph

ObjectGraph.find_node(node: str | NODE_TYPE) → NODE_TYPE | None

Find a node in the graph. If the argument is a node object this looks for a graph member with the same identifier.

Parameters:

node – A node or node identifier

Returns:

The node found, or None when the node is not present

ObjectGraph.__contains__(node: str | NODE_TYPE)

Check if a node is a member of the graph

Parameters:

node – The node or node identifier to look for

Returns:

True if the node is part of the graph, False otherwise

ObjectGraph.edge_data(source: str | NODE_TYPE, destination: str | NODE_TYPE) → set[EDGE_TYPE]

Return the all edge attributes for edges between source and destination.

Parameters:

  • source – A node or node identifier

  • destination – A node or node identifier

Returns:

A set of edge attributes for all edges between source and destination

Raises:

  • KeyError – If source or destination aren’t member of the graph

  • KeyError – If there is no edge between source and destination

ObjectGraph.roots() → Iterator[NODE_TYPE]

Yield the roots of the graph in an arbirary order.

ObjectGraph.nodes() → Iterator[NODE_TYPE]

Yield all nodes in the graph in an arbirary order.

ObjectGraph.iter_graph(*, node: str | NODE_TYPE | None = None, _visited: set | None = None) → Iterator[NODE_TYPE]

Yield all nodes in the graph reachable from node or any of the graph roots.

Parameters:

node – The node or node identifier used to start iterating. Defaults to using the graph roots.

ObjectGraph.edges() → Iterator[tuple[NODE_TYPE, NODE_TYPE, set[EDGE_TYPE]]]

Yield the source and destination of all edges in the graph with a set of all unique edge attributes for edges between the two nodes.

ObjectGraph.incoming(destination: str | NODE_TYPE) → Iterator[tuple[set[EDGE_TYPE], NODE_TYPE]]

Yield (edge, node) for all incoming edges

Parameters:

destination – A node or node identifier

ObjectGraph.outgoing(source: str | NODE_TYPE) → Iterator[tuple[set[EDGE_TYPE], NODE_TYPE]]

Yield (edge, node) for all outgoing edges

Parameters:

source – A node or node identifier

Mypy support

objectgraph.NODE_TYPE

This a type variable representing the interface for nodes: Nodes should have an string-valued attribute named “identifier”.

objectgraph.EDGE_TYPE

This type is a type variable representing the interface for edges: Edges should be hashable.