API Reference¶

class graphable.graphable.GraphObserver[source]¶

Bases: Protocol

Protocol for objects that need to be notified of node changes.

__init__(*args, **kwargs)¶

class graphable.graphable.Graphable[source]¶

Bases: Generic

A generic class representing a node in a graph that can track dependencies and dependents.

Type Parameters:: T: The type of the reference object this node holds.

__init__(reference)[source]¶

Initialize a Graphable node.

Parameters:: reference (T) – The underlying object this node represents.

property duration: float¶: Get the duration of this node.

property status: str¶: Get the status of this node.

add_dependencies(dependencies, check_cycles=False, **attributes)[source]¶

Add multiple dependencies to this node.

Parameters:

dependencies (set[Self]) – A set of Graphable nodes to add as dependencies.
check_cycles (bool) – If True, check if adding these dependencies would create a cycle.
**attributes (Any) – Edge attributes to apply to all added dependencies.

Return type:

None

add_dependency(dependency, check_cycles=False, **attributes)[source]¶

Add a single dependency to this node.

Parameters:

dependency (Self) – The Graphable node to add as a dependency.
check_cycles (bool) – If True, check if adding this dependency would create a cycle.
**attributes (Any) – Edge attributes (e.g., weight, label).

Raises:

GraphCycleError – If check_cycles is True and a cycle would be created.

Return type:

None

add_dependent(dependent, check_cycles=False, **attributes)[source]¶

Add a single dependent to this node.

Parameters:

dependent (Self) – The Graphable node to add as a dependent.
check_cycles (bool) – If True, check if adding this dependent would create a cycle.
**attributes (Any) – Edge attributes (e.g., weight, label).

Raises:

GraphCycleError – If check_cycles is True and a cycle would be created.

Return type:

None

add_dependents(dependents, check_cycles=False, **attributes)[source]¶

Add multiple dependents to this node.

Parameters:

dependents (set[Self]) – A set of Graphable nodes to add as dependents.
check_cycles (bool) – If True, check if adding these dependents would create a cycle.
**attributes (Any) – Edge attributes to apply to all added dependents.

Return type:

None

add_tag(tag)[source]¶

Add a tag to this node.

Parameters:: tag (str) – The tag to add.
Return type:: None

property dependents: set[Self]¶

Get the set of nodes that depend on this node.

Returns:: A copy of the dependents set.
Return type:: set[Self]

property depends_on: set[Self]¶

Get the set of nodes that this node depends on.

Returns:: A copy of the dependencies set.
Return type:: set[Self]

is_tagged(tag)[source]¶

Check if the node has a specific tag.

Parameters:: tag (str) – The tag to check.
Returns:: True if the tag exists, False otherwise.
Return type:: bool

edge_attributes(other)[source]¶

Get the attributes of the edge between this node and another. Checks both outgoing (dependents) and incoming (depends_on) edges.

Parameters:: other (Self) – The other node.
Returns:: The edge attributes.
Return type:: dict[str, Any]
Raises:: KeyError – If no edge exists between the nodes.

set_edge_attribute(other, key, value)[source]¶

Set an attribute on the edge between this node and another.

Parameters:

other (Self) – The other node.
key (str) – The attribute key.
value (Any) – The attribute value.

Return type:

None

find_path(target)[source]¶

Find a path from this node to the target node using BFS.

Parameters:: target (Self) – The target node to find a path to.
Returns:: The shortest path as a list of nodes, or None if no path exists.
Return type:: list[Self] | None

provides_to(dependent, check_cycles=False)[source]¶

Alias for add_dependent: indicates this node provides something to another.

Parameters:

dependent (Self) – The Graphable node that receives the provision.
check_cycles (bool) – If True, check if adding this dependent would create a cycle.

Return type:

None

property reference: T¶

Get the underlying reference object.

Returns:: The reference object.
Return type:: T

requires(dependency, check_cycles=False)[source]¶

Alias for add_dependency: indicates this node requires another node.

Parameters:

dependency (Self) – The Graphable node that is required.
check_cycles (bool) – If True, check if adding this dependency would create a cycle.

Return type:

None

property tags: set[str]¶

Get the set of tags for this node.

Returns:: A copy of the tags set.
Return type:: set[str]

remove_tag(tag)[source]¶

Remove a tag from this node.

Parameters:: tag (str) – The tag to remove.
Return type:: None

class graphable.graph.Graph[source]¶

Bases: Generic

Represents a graph of Graphable nodes.

__init__(initial=None, discover=False)[source]¶

Initialize a Graph.

Parameters:

initial (set[T] | list[T] | None) – An optional set of initial nodes.
discover (bool) – If True, automatically expand the graph to include all reachable ancestors and descendants of the initial nodes.

Raises:

GraphCycleError – If the initial set of nodes contains a cycle.

clone(include_edges=False)[source]¶

Create a copy of this graph.

Parameters:: include_edges (bool) – If True, the new graph will have the same edges as this one. If False, the new graph will contain copies of all nodes but with no edges between them.
Returns:: A new Graph instance.
Return type:: Graph[T]

neighbors(node, direction=Direction.DOWN)[source]¶

Iterate over neighbors within this graph.

Parameters:

node (T) – The source node.
direction (Direction) – Direction.DOWN for dependents, Direction.UP for dependencies.

Yields:

tuple[T, dict[str, Any]] – A (neighbor_node, edge_attributes) tuple.

Return type:

Iterator[tuple[T, dict[str, Any]]]

internal_dependents(node)[source]¶

Alias for neighbors(node, Direction.DOWN).

Return type:: Iterator[tuple[T, dict[str, Any]]]
Parameters:: node (T)

internal_depends_on(node)[source]¶

Alias for neighbors(node, Direction.UP).

Return type:: Iterator[tuple[T, dict[str, Any]]]
Parameters:: node (T)

discover()[source]¶

Traverse the entire connectivity of the current nodes and add any reachable ancestors or descendants that are not yet members.

Return type:: None

is_equal_to(other)[source]¶

Check if this graph is equal to another graph. Equality is defined as having the same checksum (structural and metadata-wise).

Parameters:: other (object) – The other object to compare with.
Returns:: True if equal, False otherwise.
Return type:: bool

checksum()[source]¶

Calculate a deterministic BLAKE2b checksum of the graph. The checksum accounts for all member nodes (references, tags, duration, status) and edges (including attributes) between them. External nodes are excluded.

Returns:: The hexadecimal digest of the graph.
Return type:: str

validate_checksum(expected)[source]¶

Validate the graph against an expected checksum.

Parameters:: expected (str) – The expected BLAKE2b hexadecimal digest.
Returns:: True if the checksums match, False otherwise.
Return type:: bool

write_checksum(path)[source]¶

Write the graph’s current checksum to a file.

Parameters:: path (Path | str) – Path to the output checksum file.
Return type:: None

static read_checksum(path)[source]¶

Read a checksum from a file.

Parameters:: path (Path | str) – Path to the checksum file.
Returns:: The checksum string.
Return type:: str

classmethod read(path, **kwargs)[source]¶

Read a graph from a file, automatically detecting the format.

Return type:

Graph[Any]

Parameters:

path (Path | str)
kwargs (Any)

write(path, transitive_reduction=False, embed_checksum=False, engine=None, **kwargs)[source]¶

Write the graph to a file, automatically detecting the format.

Parameters:

path (Path | str) – Path to the output file.
transitive_reduction (bool) – If True, perform transitive reduction before writing.
embed_checksum (bool) – If True, embed a BLAKE2b checksum in the output.
engine (Engine | str | None) – The rendering engine to use for images (.svg, .png). If None, it will be auto-detected.
**kwargs (Any) – Additional arguments passed to the specific exporter.

Return type:

None

parallelized_topological_order()[source]¶

Get the nodes in topological order, grouped into sets that can be processed in parallel. Only nodes that are members of this graph are included.

Returns:: A list of sets of member nodes that have no unmet dependencies.
Return type:: list[set[T]]

subgraph_between(source, target)[source]¶

Create a new graph containing all nodes and edges on all paths between source and target.

Parameters:

source (T) – The starting node.
target (T) – The ending node.

Returns:

A new Graph instance.

Return type:

Graph[T]

diff_graph(other)[source]¶

Create a visualization-friendly diff graph. - Nodes in both: grey/default - Added nodes: green - Removed nodes: red - Modified nodes/edges: yellow/orange

Returns:: A merged graph with diff metadata.
Return type:: Graph[T]
Parameters:: other (Graph[T])

transitive_closure()[source]¶

Compute the transitive closure of this graph. An edge (u, v) exists in the transitive closure if there is a path from u to v.

Returns:: A new Graph instance representing the transitive closure.
Return type:: Graph[T]

suggest_cycle_breaks()[source]¶

Identify a minimal set of edges to remove to make the graph a Directed Acyclic Graph (DAG). Uses a greedy heuristic.

Returns:: A list of (source, target) tuples representing suggested edges to remove.
Return type:: list[tuple[T, T]]

parallelized_topological_order_filtered(fn)[source]¶

Get a filtered list of nodes in parallelized topological order.

Parameters:: fn (Callable[[T], bool]) – The predicate function.
Returns:: Filtered sets of nodes for parallel processing.
Return type:: list[set[T]]

parallelized_topological_order_tagged(tag)[source]¶

Get a list of nodes with a specific tag in parallelized topological order.

Parameters:: tag (str) – The tag to filter by.
Returns:: Tagged sets of nodes for parallel processing.
Return type:: list[set[T]]

check_cycles()[source]¶

Check for cycles in the graph.

Raises:: GraphCycleError – If a cycle is detected.
Return type:: None

check_consistency()[source]¶

Check for consistency between depends_on and dependents for all nodes in the graph.

Raises:: GraphConsistencyError – If an inconsistency is detected.
Return type:: None

add_edge(node, dependent, **attributes)[source]¶

Add a directed edge from node to dependent. Also adds the nodes to the graph if they are not already present.

Parameters:

node (T) – The source node (dependency).
dependent (T) – The target node (dependent).
**attributes (Any) – Edge attributes (e.g., weight, label).

Raises:

GraphCycleError – If adding the edge would create a cycle.

Return type:

None

add_node(node)[source]¶

Add a node to the graph.

Parameters:: node (T) – The node to add.
Returns:: True if the node was added (was not already present), False otherwise.
Return type:: bool
Raises:: GraphCycleError – If the node is part of an existing cycle.

remove_edge(node, dependent)[source]¶

Remove a directed edge from node to dependent.

Parameters:

node (T) – The source node.
dependent (T) – The target node.

Return type:

None

remove_node(node)[source]¶

Remove a node and all its connected edges from the graph.

Parameters:: node (T) – The node to remove.
Return type:: None

ancestors(node)[source]¶

Get an iterator for all nodes that the given node depends on, recursively.

Parameters:: node (T) – The starting node.
Yields:: T – The next ancestor node.
Return type:: Iterator[T]

descendants(node)[source]¶

Get an iterator for all nodes that depend on the given node, recursively.

Parameters:: node (T) – The starting node.
Yields:: T – The next descendant node.
Return type:: Iterator[T]

bfs(start_node, direction=Direction.DOWN, limit_to_graph=True)[source]¶

Perform a breadth-first search (BFS) starting from the given node.

Parameters:

start_node (T) – The node to start from.
direction (Direction) – Direction.UP for dependencies, Direction.DOWN for dependents.
limit_to_graph (bool) – If True, only return nodes that are members of this graph.

Yields:

T – Each reached node in breadth-first order.

Return type:

Iterator[T]

dfs(start_node, direction=Direction.DOWN, limit_to_graph=True)[source]¶

Perform a depth-first search (DFS) starting from the given node.

Parameters:

start_node (T) – The node to start from.
direction (Direction) – Direction.UP for dependencies, Direction.DOWN for dependents.
limit_to_graph (bool) – If True, only return nodes that are members of this graph.

Yields:

T – Each reached node in depth-first order.

Return type:

Iterator[T]

property sinks: list[T]¶

Get all sink nodes (nodes with no dependents).

Returns:: A list of sink nodes.
Return type:: list[T]

property sources: list[T]¶

Get all source nodes (nodes with no dependencies).

Returns:: A list of source nodes.
Return type:: list[T]

static parse(parser_fnc, source, **kwargs)[source]¶

Parse a graph from a source using a parser function.

Parameters:

parser_fnc (Callable[..., Graph[Any]]) – The parser function to use (e.g., load_graph_json).
source (str | Path) – The source to parse (string or path).
**kwargs (Any) – Additional arguments passed to the parser function.

Returns:

A new Graph instance.

Return type:

Graph

classmethod from_csv(source, **kwargs)[source]¶

Create a Graph from a CSV edge list.

Return type:

Graph[Any]

Parameters:

source (str | Path)
kwargs (Any)

classmethod from_graphml(source, **kwargs)[source]¶

Create a Graph from a GraphML file or string.

Return type:

Graph[Any]

Parameters:

source (str | Path)
kwargs (Any)

classmethod from_json(source, **kwargs)[source]¶

Create a Graph from a JSON file or string.

Return type:

Graph[Any]

Parameters:

source (str | Path)
kwargs (Any)

classmethod from_toml(source, **kwargs)[source]¶

Create a Graph from a TOML file or string.

Return type:

Graph[Any]

Parameters:

source (str | Path)
kwargs (Any)

classmethod from_yaml(source, **kwargs)[source]¶

Create a Graph from a YAML file or string.

Return type:

Graph[Any]

Parameters:

source (str | Path)
kwargs (Any)

subgraph_filtered(fn)[source]¶

Create a new subgraph containing only nodes that satisfy the predicate.

Parameters:: fn (Callable[[T], bool]) – The predicate function.
Returns:: A new Graph containing the filtered nodes.
Return type:: Graph[T]

subgraph_tagged(tag)[source]¶

Create a new subgraph containing only nodes with the specified tag.

Parameters:: tag (str) – The tag to filter by.
Returns:: A new Graph containing the tagged nodes.
Return type:: Graph[T]

upstream_of(node)[source]¶

Create a new graph containing the given node and all its ancestors.

Parameters:: node (T) – The node to start from.
Returns:: A new Graph instance.
Return type:: Graph[T]

downstream_of(node)[source]¶

Create a new graph containing the given node and all its descendants.

Parameters:: node (T) – The node to start from.
Returns:: A new Graph instance.
Return type:: Graph[T]

cpm_analysis()[source]¶

Perform Critical Path Method (CPM) analysis on the graph. Assumes all nodes have a ‘duration’ attribute.

Returns:

A dictionary mapping each node to its CPM values:

’ES’: Earliest Start
’EF’: Earliest Finish
’LS’: Latest Start
’LF’: Latest Finish
’slack’: Total Slack (LF - EF)

Return type:

dict[T, dict[str, float]]

critical_path()[source]¶

Identify the nodes on the critical path (slack == 0).

Returns:: A list of nodes on the critical path, in topological order.
Return type:: list[T]

longest_path()[source]¶

Find the longest path in the graph based on node durations. In a DAG, this is equivalent to the critical path chain.

Returns:: The nodes forming the longest path.
Return type:: list[T]

all_paths(source, target)[source]¶

Find all possible paths between two nodes.

Parameters:

source (T) – Starting node.
target (T) – Ending node.

Returns:

A list of all paths, where each path is a list of nodes.

Return type:

list[list[T]]

diff(other)[source]¶

Compare this graph with another graph.

Returns:

A dictionary containing differences:

’added_nodes’: references of nodes in other but not in self.
’removed_nodes’: references of nodes in self but not in other.
’modified_nodes’: references of nodes in both but with different properties.
’added_edges’: (u, v) tuples of edges in other but not in self.
’removed_edges’: (u, v) tuples of edges in self but not in other.
’modified_edges’: (u, v) tuples of edges in both but with different attributes.

Return type:

dict[str, Any]

Parameters:

other (Graph[T])

topological_order()[source]¶

Get the nodes in topological order. Only nodes that are members of this graph are included.

Returns:: A list of member nodes sorted topologically.
Return type:: list[T]

topological_order_filtered(fn)[source]¶

Get a filtered list of nodes in topological order.

Parameters:: fn (Callable[[T], bool]) – The predicate function.
Returns:: Filtered topologically sorted nodes.
Return type:: list[T]

topological_order_tagged(tag)[source]¶

Get a list of nodes with a specific tag in topological order.

Parameters:: tag (str) – The tag to filter by.
Returns:: Tagged topologically sorted nodes.
Return type:: list[T]

to_networkx()[source]¶

Convert this graph to a networkx.DiGraph. Requires ‘networkx’ to be installed.

Returns:: The converted directed graph.
Return type:: networkx.DiGraph

transitive_reduction()[source]¶

Compute the transitive reduction of this DAG. A transitive reduction of a directed acyclic graph G is a graph G’ with the same nodes and the same reachability as G, but with as few edges as possible.

Returns:: A new Graph instance containing the same nodes (cloned) but with redundant edges removed.
Return type:: Graph[T]

render(view_fnc, transitive_reduction=False, **kwargs)[source]¶

Render the graph using a view function.

Parameters:

view_fnc (Callable[..., str]) – The view function to use (e.g., create_topology_mermaid_mmd).
transitive_reduction (bool) – If True, render the transitive reduction of the graph.
**kwargs (Any) – Additional arguments passed to the view function.

Returns:

The rendered representation.

Return type:

str

export(export_fnc, output, transitive_reduction=False, embed_checksum=False, **kwargs)[source]¶

Export the graph using an export function.

Parameters:

export_fnc (Callable[..., None]) – The export function to use (e.g., export_topology_graphviz_svg).
output (Path | str) – The output file path.
transitive_reduction (bool) – If True, export the transitive reduction of the graph.
embed_checksum (bool) – If True, embed the graph’s checksum as a comment at the top.
**kwargs (Any) – Additional arguments passed to the export function.

Return type:

None

Views¶

class graphable.views.graphviz.GraphvizStylingConfig[source]¶

Bases: object

Configuration for customizing Graphviz DOT generation.

Variables:

node_ref_fnc – Function to generate the node identifier (reference).
node_label_fnc – Function to generate the node label.
node_attr_fnc – Function to generate a dictionary of attributes for a node.
edge_attr_fnc – Function to generate a dictionary of attributes for an edge.
graph_attr – Dictionary of global graph attributes.
node_attr_default – Dictionary of default node attributes.
edge_attr_default – Dictionary of default edge attributes.

node_ref_fnc()¶

node_label_fnc()¶

node_attr_fnc: Callable[[Graphable[Any]], dict[str, str]] | None = None¶

edge_attr_fnc: Callable[[Graphable[Any], Graphable[Any]], dict[str, str]] | None = None¶

graph_attr: dict[str, str] | None = None¶

node_attr_default: dict[str, str] | None = None¶

edge_attr_default: dict[str, str] | None = None¶

cluster_by_tag: bool = False¶

tag_sort_fnc()¶

__init__(node_ref_fnc=<function GraphvizStylingConfig.<lambda>>, node_label_fnc=<function GraphvizStylingConfig.<lambda>>, node_attr_fnc=None, edge_attr_fnc=None, graph_attr=None, node_attr_default=None, edge_attr_default=None, cluster_by_tag=False, tag_sort_fnc=<function GraphvizStylingConfig.<lambda>>)¶

Parameters:

node_ref_fnc (Callable[[Graphable[Any]], str])
node_label_fnc (Callable[[Graphable[Any]], str])
node_attr_fnc (Callable[[Graphable[Any]], dict[str, str]] | None)
edge_attr_fnc (Callable[[Graphable[Any], Graphable[Any]], dict[str, str]] | None)
graph_attr (dict[str, str] | None)
node_attr_default (dict[str, str] | None)
edge_attr_default (dict[str, str] | None)
cluster_by_tag (bool)
tag_sort_fnc (Callable[[set[str]], list[str]])

Return type:

None

graphable.views.graphviz.create_topology_graphviz_dot(graph, config=None)[source]¶

Generate Graphviz DOT definition from a Graph.

Parameters:

graph (Graph) – The graph to convert.
config (GraphvizStylingConfig | None) – Styling configuration.

Returns:

The Graphviz DOT definition string.

Return type:

str

graphable.views.graphviz.export_topology_graphviz_dot(graph, output, config=None)[source]¶

Export the graph to a Graphviz .dot file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (GraphvizStylingConfig | None) – Styling configuration.

Return type:

None

graphable.views.graphviz.export_topology_graphviz_image(graph, output, config=None)[source]¶

Export the graph to an image file (SVG or PNG) using the ‘dot’ command.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (GraphvizStylingConfig | None) – Styling configuration.

Return type:

None

class graphable.views.d2.D2StylingConfig[source]¶

Bases: object

Configuration for customizing D2 diagram generation.

Variables:

node_ref_fnc – Function to generate the node identifier (reference).
node_label_fnc – Function to generate the node label.
node_style_fnc – Function to generate a dictionary of style attributes for a node.
edge_style_fnc – Function to generate a dictionary of style attributes for an edge.
global_style – Dictionary of global styling attributes.
layout – D2 layout engine to use (e.g., ‘dagre’, ‘elk’).
theme – D2 theme ID to use.

node_ref_fnc()¶

node_label_fnc()¶

node_style_fnc: Callable[[Graphable[Any]], dict[str, str]] | None = None¶

edge_style_fnc: Callable[[Graphable[Any], Graphable[Any]], dict[str, str]] | None = None¶

global_style: dict[str, str] | None = None¶

layout: str | None = None¶

theme: str | None = None¶

cluster_by_tag: bool = False¶

tag_sort_fnc()¶

__init__(node_ref_fnc=<function D2StylingConfig.<lambda>>, node_label_fnc=<function D2StylingConfig.<lambda>>, node_style_fnc=None, edge_style_fnc=None, global_style=None, layout=None, theme=None, cluster_by_tag=False, tag_sort_fnc=<function D2StylingConfig.<lambda>>)¶

Parameters:

node_ref_fnc (Callable[[Graphable[Any]], str])
node_label_fnc (Callable[[Graphable[Any]], str])
node_style_fnc (Callable[[Graphable[Any]], dict[str, str]] | None)
edge_style_fnc (Callable[[Graphable[Any], Graphable[Any]], dict[str, str]] | None)
global_style (dict[str, str] | None)
layout (str | None)
theme (str | None)
cluster_by_tag (bool)
tag_sort_fnc (Callable[[set[str]], list[str]])

Return type:

None

graphable.views.d2.create_topology_d2(graph, config=None)[source]¶

Generate D2 definition from a Graph.

Parameters:

graph (Graph) – The graph to convert.
config (D2StylingConfig | None) – Styling configuration.

Returns:

The D2 definition string.

Return type:

str

graphable.views.d2.export_topology_d2(graph, output, config=None)[source]¶

Export the graph to a D2 file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (D2StylingConfig | None) – Styling configuration.

Return type:

None

graphable.views.d2.export_topology_d2_image(graph, output, config=None)[source]¶

Export the graph to an image file (SVG or PNG) using the ‘d2’ command.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (D2StylingConfig | None) – Styling configuration.

Return type:

None

class graphable.views.plantuml.PlantUmlStylingConfig[source]¶

Bases: object

Configuration for customizing PlantUML diagram generation.

Variables:

node_ref_fnc – Function to generate the node identifier (alias).
node_label_fnc – Function to generate the node label.
node_type – PlantUML node type (e.g., ‘node’, ‘component’, ‘artifact’).
direction – Diagram direction (e.g., ‘top to bottom direction’, ‘left to right direction’).

node_ref_fnc()¶

node_label_fnc()¶

node_type: str = 'node'¶

direction: str = 'top to bottom direction'¶

cluster_by_tag: bool = False¶

tag_sort_fnc()¶

__init__(node_ref_fnc=<function PlantUmlStylingConfig.<lambda>>, node_label_fnc=<function PlantUmlStylingConfig.<lambda>>, node_type='node', direction='top to bottom direction', cluster_by_tag=False, tag_sort_fnc=<function PlantUmlStylingConfig.<lambda>>)¶

Parameters:

node_ref_fnc (Callable[[Graphable[Any]], str])
node_label_fnc (Callable[[Graphable[Any]], str])
node_type (str)
direction (str)
cluster_by_tag (bool)
tag_sort_fnc (Callable[[set[str]], list[str]])

Return type:

None

graphable.views.plantuml.create_topology_plantuml(graph, config=None)[source]¶

Generate PlantUML definition from a Graph.

Parameters:

graph (Graph) – The graph to convert.
config (PlantUmlStylingConfig | None) – Styling configuration.

Returns:

The PlantUML definition string.

Return type:

str

graphable.views.plantuml.export_topology_plantuml(graph, output, config=None)[source]¶

Export the graph to a PlantUML (.puml) file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (PlantUMLStylingConfig | None) – Styling configuration.

Return type:

None

graphable.views.plantuml.export_topology_plantuml_image(graph, output, config=None)[source]¶

Export the graph to an image file (SVG or PNG) using the ‘plantuml’ command.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (PlantUmlStylingConfig | None) – Styling configuration.

Return type:

None

class graphable.views.tikz.TikzStylingConfig[source]¶

Bases: object

Configuration for customizing TikZ diagram generation.

Variables:

node_ref_fnc – Function to generate the node identifier.
node_label_fnc – Function to generate the node label.
node_options – Global TikZ options for nodes.
edge_options – Global TikZ options for edges.
use_graphs_lib – Whether to use the TikZ ‘graphs’ library syntax.

node_ref_fnc()¶

node_label_fnc()¶

node_options: str = 'draw, circle'¶

edge_options: str = '->'¶

use_graphs_lib: bool = True¶

__init__(node_ref_fnc=<function TikzStylingConfig.<lambda>>, node_label_fnc=<function TikzStylingConfig.<lambda>>, node_options='draw, circle', edge_options='->', use_graphs_lib=True)¶

Parameters:

node_ref_fnc (Callable[[Graphable[Any]], str])
node_label_fnc (Callable[[Graphable[Any]], str])
node_options (str)
edge_options (str)
use_graphs_lib (bool)

Return type:

None

graphable.views.tikz.create_topology_tikz(graph, config=None)[source]¶

Generate TikZ LaTeX code from a Graph.

Parameters:

graph (Graph) – The graph to convert.
config (TikzStylingConfig | None) – Styling configuration.

Returns:

The TikZ LaTeX code string.

Return type:

str

graphable.views.tikz.export_topology_tikz(graph, output, config=None)[source]¶

Export the graph to a TikZ (.tex) file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (TikZStylingConfig | None) – Styling configuration.

Return type:

None

class graphable.views.mermaid.MermaidStylingConfig[source]¶

Bases: object

Configuration for customizing Mermaid diagram generation.

Variables:

node_ref_fnc – Function to generate the node identifier (reference).
node_text_fnc – Function to generate the node label text.
node_style_fnc – Function to generate specific style for a node (or None).
node_style_default – Default style string for nodes (or None).
link_text_fnc – Function to generate label for links between nodes.
link_style_fnc – Function to generate style for links (or None).
link_style_default – Default style string for links (or None).

node_ref_fnc()¶

node_text_fnc()¶

node_style_fnc()¶

Return type:: str | None
Parameters:: node (Graphable[Any])

node_style_default: str | None = None¶

link_text_fnc(sn)¶

link_style_fnc(subnode)¶

Return type:

str | None

Parameters:

node (Graphable[Any])
subnode (Graphable[Any])

link_style_default: str | None = None¶

cluster_by_tag: bool = False¶

tag_sort_fnc()¶

__init__(node_ref_fnc=<function MermaidStylingConfig.<lambda>>, node_text_fnc=<function MermaidStylingConfig.<lambda>>, node_style_fnc=<function _get_node_style>, node_style_default=None, link_text_fnc=<function MermaidStylingConfig.<lambda>>, link_style_fnc=<function _get_link_style>, link_style_default=None, cluster_by_tag=False, tag_sort_fnc=<function MermaidStylingConfig.<lambda>>)¶

Parameters:

node_ref_fnc (Callable[[Graphable[Any]], str])
node_text_fnc (Callable[[Graphable[Any]], str])
node_style_fnc (Callable[[Graphable[Any]], str | None] | None)
node_style_default (str | None)
link_text_fnc (Callable[[Graphable[Any], Graphable[Any]], str])
link_style_fnc (Callable[[Graphable[Any], Graphable[Any]], str | None] | None)
link_style_default (str | None)
cluster_by_tag (bool)
tag_sort_fnc (Callable[[set[str]], list[str]])

Return type:

None

graphable.views.mermaid.create_mmdc_script_content(source, output)[source]¶

Generate the bash script content to run mmdc.

Parameters:

source (Path) – Path to the source mermaid file.
output (Path) – Path to the output file.

Returns:

The script content.

Return type:

str

graphable.views.mermaid.create_topology_mermaid_mmd(graph, config=None)[source]¶

Generate Mermaid flowchart definition from a Graph.

Parameters:

graph (Graph) – The graph to convert.
config (MermaidStylingConfig | None) – Styling configuration.

Returns:

The mermaid graph definition string.

Return type:

str

graphable.views.mermaid.export_topology_mermaid_mmd(graph, output, config=None)[source]¶

Export the graph to a Mermaid .mmd file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (MermaidStylingConfig | None) – Styling configuration.

Return type:

None

graphable.views.mermaid.export_topology_mermaid_image(graph, output, config=None, embed_checksum=False)[source]¶

Export the graph to an image file (SVG or PNG) using mmdc.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (MermaidStylingConfig | None) – Styling configuration.
embed_checksum (bool) – If True, embed the graph’s checksum as a comment.

Return type:

None

class graphable.views.asciiflow.AsciiflowStylingConfig[source]¶

Bases: object

Configuration for ASCII flowchart representation of the graph.

Variables:

node_text_fnc – Function to generate the text representation of a node.
show_tags – Whether to include tags in the output.

node_text_fnc()¶

show_tags: bool = False¶

__init__(node_text_fnc=<function AsciiflowStylingConfig.<lambda>>, show_tags=False)¶

Parameters:

node_text_fnc (Callable[[Graphable[Any]], str])
show_tags (bool)

Return type:

None

graphable.views.asciiflow.create_topology_ascii_flow(graph, config=None)[source]¶

Create an ASCII-based flowchart representation of the graph. Unlike TextTree, this explicitly shows multiple parents by listing connections.

Parameters:

graph (Graph) – The graph to convert.
config (AsciiflowStylingConfig | None) – Styling configuration.

Returns:

The ASCII flowchart representation.

Return type:

str

graphable.views.asciiflow.export_topology_ascii_flow(graph, output, config=None)[source]¶

Export the graph to an ASCII flowchart file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (AsciiFlowStylingConfig | None) – Styling configuration.

Return type:

None

graphable.views.csv.create_topology_csv(graph, node_text_fnc=<function <lambda>>, include_header=True)[source]¶

Generate a CSV edge list from a Graph.

Parameters:

graph (Graph) – The graph to convert.
node_text_fnc (Callable[[Graphable[Any]], str]) – Function to generate the text for each node.
include_header (bool) – Whether to include a header row (‘source’,’target’).

Returns:

The CSV edge list as a string.

Return type:

str

graphable.views.csv.export_topology_csv(graph, output, node_text_fnc=<function <lambda>>, include_header=True)[source]¶

Export the graph to a CSV file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
node_text_fnc (Callable[[Graphable[Any]], str]) – Function to generate the text for each node.
include_header (bool) – Whether to include a header row.

Return type:

None

class graphable.views.json.JsonStylingConfig[source]¶

Bases: object

Configuration for JSON graph serialization.

Variables:

node_data_fnc – Optional function to add extra data to each node’s JSON object.
reference_fnc – Function to generate the string identifier for each node.
indent – JSON indentation level.

node_data_fnc: Callable[[Graphable[Any]], dict[str, Any]] | None = None¶

reference_fnc()¶

indent: int | str | None = 2¶

__init__(node_data_fnc=None, reference_fnc=<function JsonStylingConfig.<lambda>>, indent=2)¶

Parameters:

node_data_fnc (Callable[[Graphable[Any]], dict[str, Any]] | None)
reference_fnc (Callable[[Graphable[Any]], str])
indent (int | str | None)

Return type:

None

graphable.views.json.create_topology_json(graph, config=None)[source]¶

Generate a JSON representation of the graph.

Parameters:

graph (Graph) – The graph to convert.
config (JsonStylingConfig | None) – Serialization configuration.

Returns:

A JSON string containing ‘nodes’ and ‘edges’.

Return type:

str

graphable.views.json.export_topology_json(graph, output, config=None)[source]¶

Export the graph to a JSON file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (JSONStylingConfig | None) – Serialization configuration.

Return type:

None

class graphable.views.yaml.YamlStylingConfig[source]¶

Bases: object

Configuration for YAML graph serialization.

Variables:

node_data_fnc – Optional function to add extra data to each node’s YAML object.
reference_fnc – Function to generate the string identifier for each node.
indent – YAML indentation level.

node_data_fnc: Callable[[Graphable[Any]], dict[str, Any]] | None = None¶

reference_fnc()¶

indent: int = 2¶

__init__(node_data_fnc=None, reference_fnc=<function YamlStylingConfig.<lambda>>, indent=2)¶

Parameters:

node_data_fnc (Callable[[Graphable[Any]], dict[str, Any]] | None)
reference_fnc (Callable[[Graphable[Any]], str])
indent (int)

Return type:

None

graphable.views.yaml.create_topology_yaml(graph, config=None)[source]¶

Generate a YAML representation of the graph. Requires ‘PyYAML’ to be installed.

Parameters:

graph (Graph) – The graph to convert.
config (YamlStylingConfig | None) – Serialization configuration.

Returns:

A YAML string containing ‘nodes’ and ‘edges’.

Return type:

str

graphable.views.yaml.export_topology_yaml(graph, output, config=None)[source]¶

Export the graph to a YAML file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (YamlStylingConfig | None) – Serialization configuration.

Return type:

None

class graphable.views.toml.TomlStylingConfig[source]¶

Bases: object

Configuration for TOML graph serialization.

Variables:

node_data_fnc – Optional function to add extra data to each node’s TOML object.
reference_fnc – Function to generate the string identifier for each node.

node_data_fnc: Callable[[Graphable[Any]], dict[str, Any]] | None = None¶

reference_fnc()¶

__init__(node_data_fnc=None, reference_fnc=<function TomlStylingConfig.<lambda>>)¶

Parameters:

node_data_fnc (Callable[[Graphable[Any]], dict[str, Any]] | None)
reference_fnc (Callable[[Graphable[Any]], str])

Return type:

None

graphable.views.toml.create_topology_toml(graph, config=None)[source]¶

Generate a TOML representation of the graph. Requires ‘tomli-w’ to be installed.

Parameters:

graph (Graph) – The graph to convert.
config (TomlStylingConfig | None) – Serialization configuration.

Returns:

A TOML string containing ‘nodes’ and ‘edges’.

Return type:

str

graphable.views.toml.export_topology_toml(graph, output, config=None)[source]¶

Export the graph to a TOML file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (TomlStylingConfig | None) – Serialization configuration.

Return type:

None

class graphable.views.cytoscape.CytoscapeStylingConfig[source]¶

Bases: object

Configuration for Cytoscape.js JSON serialization.

Variables:

node_data_fnc – Optional function to add extra data to each node’s ‘data’ object.
edge_data_fnc – Optional function to add extra data to each edge’s ‘data’ object.
reference_fnc – Function to generate the string identifier for each node.
indent – JSON indentation level.

node_data_fnc: Callable[[Graphable[Any]], dict[str, Any]] | None = None¶

edge_data_fnc: Callable[[Graphable[Any], Graphable[Any]], dict[str, Any]] | None = None¶

reference_fnc()¶

indent: int | str | None = 2¶

__init__(node_data_fnc=None, edge_data_fnc=None, reference_fnc=<function CytoscapeStylingConfig.<lambda>>, indent=2)¶

Parameters:

node_data_fnc (Callable[[Graphable[Any]], dict[str, Any]] | None)
edge_data_fnc (Callable[[Graphable[Any], Graphable[Any]], dict[str, Any]] | None)
reference_fnc (Callable[[Graphable[Any]], str])
indent (int | str | None)

Return type:

None

graphable.views.cytoscape.create_topology_cytoscape(graph, config=None)[source]¶

Generate a Cytoscape.js compatible JSON representation of the graph.

Parameters:

graph (Graph) – The graph to convert.
config (CytoscapeStylingConfig | None) – Serialization configuration.

Returns:

A JSON string in Cytoscape.js elements format.

Return type:

str

graphable.views.cytoscape.export_topology_cytoscape(graph, output, config=None)[source]¶

Export the graph to a Cytoscape JSON file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (CytoscapeStylingConfig | None) – Serialization configuration.

Return type:

None

graphable.views.markdown.wrap_in_markdown(content, language)[source]¶

Wrap a string in a Markdown code block.

Parameters:

content (str) – The content to wrap.
language (str) – The language identifier for the code block (e.g., ‘mermaid’, ‘d2’).

Returns:

The Markdown-wrapped content.

Return type:

str

graphable.views.markdown.export_markdown_wrapped(content, language, output)[source]¶

Export content wrapped in Markdown to a file.

Parameters:

content (str) – The content to wrap and export.
language (str) – The language identifier.
output (Path) – The output file path.

Return type:

None

class graphable.views.texttree.TextTreeStylingConfig[source]¶

Bases: object

Configuration for text tree representation of the graph.

Variables:

initial_indent – String to use for initial indentation.
node_text_fnc – Function to generate the text representation of a node.

initial_indent: str = ''¶

node_text_fnc()¶

__init__(initial_indent='', node_text_fnc=<function TextTreeStylingConfig.<lambda>>)¶

Parameters:

initial_indent (str)
node_text_fnc (Callable[[Graphable[Any]], str])

Return type:

None

graphable.views.texttree.create_topology_tree_txt(graph, config=None)[source]¶

Create a text-based tree representation of the graph topology.

Parameters:

graph (Graph) – The graph to convert.
config (TextTreeStylingConfig | None) – Styling configuration.

Returns:

The text tree representation.

Return type:

str

graphable.views.texttree.export_topology_tree_txt(graph, output, config=None)[source]¶

Export the graph to a text tree file.

Parameters:

graph (Graph) – The graph to export.
output (Path) – The output file path.
config (TextTreeStylingConfig | None) – Styling configuration.

Return type:

None

Parsers¶

graphable.parsers.json.load_graph_json(source, reference_type=<class 'str'>)[source]¶

Load a graph from a JSON string or file.

Parameters:

source (str | Path) – JSON string or path to a JSON file.
reference_type (type) – The type to cast the node reference to (default: str).

Returns:

A new Graph instance populated from the JSON data.

Return type:

Graph

graphable.parsers.yaml.load_graph_yaml(source, reference_type=<class 'str'>)[source]¶

Load a graph from a YAML string or file. Requires ‘PyYAML’ to be installed.

Parameters:

source (str | Path) – YAML string or path to a YAML file.
reference_type (type) – The type to cast the node reference to (default: str).

Returns:

A new Graph instance populated from the YAML data.

Return type:

Graph

graphable.parsers.toml.load_graph_toml(source, reference_type=<class 'str'>)[source]¶

Load a graph from a TOML string or file. Uses ‘tomllib’ (Python 3.11+) or ‘tomli’.

Parameters:

source (str | Path) – TOML string or path to a TOML file.
reference_type (type) – The type to cast the node reference to (default: str).

Returns:

A new Graph instance populated from the TOML data.

Return type:

Graph

graphable.parsers.csv.load_graph_csv(source, reference_type=<class 'str'>)[source]¶

Load a Graph from a CSV edge list.

Parameters:

source (str | Path) – CSV string or path to a CSV file.
reference_type (type) – The type to cast the reference string to.

Returns:

The loaded Graph instance.

Return type:

Graph

graphable.parsers.graphml.load_graph_graphml(source, reference_type=<class 'str'>)[source]¶

Load a Graph from a GraphML XML source.

Parameters:

source (str | Path) – GraphML XML string or path to a GraphML file.
reference_type (type) – The type to cast the reference string to.

Returns:

The loaded Graph instance.

Return type:

Graph

graphable.parsers.utils.build_graph_from_data(nodes_data, edges_data, reference_type=<class 'str'>)[source]¶

Standardized helper to construct a Graph from raw data.

Parameters:

nodes_data (list[dict[str, Any]]) – List of node dictionaries (id, tags, duration, status).
edges_data (list[dict[str, Any]]) – List of edge dictionaries (source, target, attributes).
reference_type (type) – Type to cast the reference string to.

Returns:

The constructed Graph instance.

Return type:

Graph

graphable.parsers.utils.is_path(source)[source]¶

Check if the given source is likely a path to a file.

Parameters:: source (str | Path) – The source to check (string or Path object).
Returns:: True if it’s a Path object or a string that points to an existing file.
Return type:: bool

graphable.parsers.utils.extract_checksum(source)[source]¶

Extract a blake2b checksum from the first few lines of a source. Looks for the pattern ‘blake2b: <hash>’.

Parameters:: source (str | Path) – The source to check (string or Path object).
Returns:: The hash if found, otherwise None.
Return type:: str | None