graphable 0.2.0__py3-none-any.whl

graphable/graph.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+from collections import deque
+from graphlib import CycleError, TopologicalSorter
+from logging import getLogger
+from typing import Any, Callable
+
+from .graphable import Graphable
+
+logger = getLogger(__name__)
+
+
+class GraphCycleError(Exception):
+    """
+    Exception raised when a cycle is detected in the graph.
+    """
+
+    def __init__(self, message: str, cycle: list[Any] | None = None):
+        super().__init__(message)
+        self.cycle = cycle
+
+
+class GraphConsistencyError(Exception):
+    """
+    Exception raised when the bi-directional relationships in the graph are inconsistent.
+    """
+
+    pass
+
+
+def graph[T: Graphable[Any, Any]](contains: list[T]) -> Graph[T]:
+    """
+    Constructs a Graph containing the given nodes and all their connected dependencies/dependents.
+    It traverses the graph both up (dependencies) and down (dependents) from the initial nodes.
+
+    Args:
+        contains (list[T]): A list of initial nodes to start the graph construction from.
+
+    Returns:
+        Graph[T]: A Graph object containing all reachable nodes.
+    """
+    logger.debug(f"Building graph from {len(contains)} initial nodes.")
+
+    def go_down(node: T, nodes: set[T]) -> None:
+        """
+        Recursively traverse down the graph to find all dependent nodes.
+
+        Args:
+            node (T): The current node to traverse from.
+            nodes (set[T]): The set of nodes found so far.
+        """
+        for down_node in node.dependents:
+            if down_node in nodes:
+                continue
+
+            nodes.add(down_node)
+            go_down(down_node, nodes)
+
+    def go_up(node: T, nodes: set[T]) -> None:
+        """
+        Recursively traverse up the graph to find all dependency nodes.
+
+        Args:
+            node (T): The current node to traverse from.
+            nodes (set[T]): The set of nodes found so far.
+        """
+        for up_node in node.depends_on:
+            if up_node in nodes:
+                continue
+
+            nodes.add(up_node)
+            go_up(up_node, nodes)
+
+    nodes: set[T] = set(contains)
+    for node in contains:
+        go_up(node, nodes)
+        go_down(node, nodes)
+
+    logger.info(f"Graph built with {len(nodes)} total nodes.")
+    return Graph(nodes)
+
+
+class Graph[T: Graphable[Any, Any]]:
+    """
+    Represents a graph of Graphable nodes.
+    """
+
+    def __init__(self, initial: set[T] | None = None):
+        """
+        Initialize a Graph.
+
+        Args:
+            initial (set[T] | None): An optional set of initial nodes.
+
+        Raises:
+            GraphCycleError: If the initial set of nodes contains a cycle.
+        """
+        self._nodes: set[T] = initial if initial else set[T]()
+        self._topological_order: list[T] | None = None
+
+        if self._nodes:
+            self.check_consistency()
+            self.check_cycles()
+
+    def _find_path(self, start: T, target: T) -> list[T] | None:
+        """
+        Find a path from start to target using BFS.
+
+        Args:
+            start (T): The starting node.
+            target (T): The target node.
+
+        Returns:
+            list[T] | None: The shortest path as a list of nodes, or None if no path exists.
+        """
+        # BFS find shortest path
+        queue: deque[tuple[T, list[T]]] = deque()
+        for neighbor in start.dependents:
+            queue.append((neighbor, [start, neighbor]))
+
+        # We don't mark 'start' as visited in the set immediately if we want to find a cycle
+        # that returns to 'start'. However, if start == target, the above loop already handles it.
+        # Actually, the most robust way is to mark everything we pop as visited.
+        visited: set[T] = set()
+        while queue:
+            current, path = queue.popleft()
+            if current == target:
+                return path
+
+            if current in visited:
+                continue
+
+            visited.add(current)
+            for neighbor in current.dependents:
+                if neighbor not in visited:
+                    queue.append((neighbor, path + [neighbor]))
+
+        return None
+
+    def check_cycles(self) -> None:
+        """
+        Check for cycles in the graph.
+
+        Raises:
+            GraphCycleError: If a cycle is detected.
+        """
+        try:
+            sorter = TopologicalSorter({node: node.depends_on for node in self._nodes})
+            sorter.prepare()
+        except CycleError as e:
+            # graphlib.CycleError args: (message, cycle_tuple)
+            cycle = list(e.args[1]) if len(e.args) > 1 else None
+            raise GraphCycleError(f"Cycle detected in graph: {e}", cycle=cycle) from e
+
+    def check_consistency(self) -> None:
+        """
+        Check for consistency between depends_on and dependents for all nodes in the graph.
+
+        Raises:
+            GraphConsistencyError: If an inconsistency is detected.
+        """
+        for node in self._nodes:
+            self._check_node_consistency(node)
+
+    def _check_node_consistency(self, node: T) -> None:
+        """
+        Check for consistency between depends_on and dependents for a single node.
+
+        Args:
+            node (T): The node to check.
+
+        Raises:
+            GraphConsistencyError: If an inconsistency is detected.
+        """
+        # Check dependencies: if node depends on X, X must have node as dependent
+        for dep in node.depends_on:
+            if node not in dep.dependents:
+                raise GraphConsistencyError(
+                    f"Inconsistency: Node '{node.reference}' depends on '{dep.reference}', "
+                    f"but '{dep.reference}' does not list '{node.reference}' as a dependent."
+                )
+        # Check dependents: if node has dependent Y, Y must depend on node
+        for sub in node.dependents:
+            if node not in sub.depends_on:
+                raise GraphConsistencyError(
+                    f"Inconsistency: Node '{node.reference}' has dependent '{sub.reference}', "
+                    f"but '{sub.reference}' does not depend on '{node.reference}'."
+                )
+
+    def add_edge(self, node: T, dependent: T) -> None:
+        """
+        Add a directed edge from node to dependent.
+        Also adds the nodes to the graph if they are not already present.
+
+        Args:
+            node (T): The source node (dependency).
+            dependent (T): The target node (dependent).
+
+        Raises:
+            GraphCycleError: If adding the edge would create a cycle.
+        """
+        if node == dependent:
+            raise GraphCycleError(
+                f"Self-loop detected: node '{node.reference}' cannot depend on itself.",
+                cycle=[node, node],
+            )
+
+        # Check if adding this edge creates a cycle.
+        # A cycle is created if there is already a path from 'dependent' to 'node'.
+        if path := self._find_path(dependent, node):
+            cycle = path + [dependent]
+            raise GraphCycleError(
+                f"Adding edge '{node.reference}' -> '{dependent.reference}' would create a cycle.",
+                cycle=cycle,
+            )
+
+        self.add_node(node)
+        self.add_node(dependent)
+
+        node._add_dependent(dependent)
+        dependent._add_depends_on(node)
+        logger.debug(f"Added edge: {node.reference} -> {dependent.reference}")
+
+        # Invalidate cache
+        if self._topological_order is not None:
+            self._topological_order = None
+
+    def add_node(self, node: T) -> bool:
+        """
+        Add a node to the graph.
+
+        Args:
+            node (T): The node to add.
+
+        Returns:
+            bool: True if the node was added (was not already present), False otherwise.
+
+        Raises:
+            GraphCycleError: If the node is part of an existing cycle.
+        """
+        if node in self._nodes:
+            return False
+
+        # If the node is already part of a cycle (linked externally), adding it might be invalid
+        # if we want to enforce DAG.
+        if cycle := self._find_path(node, node):
+            raise GraphCycleError(
+                f"Node '{node.reference}' is part of an existing cycle.", cycle=cycle
+            )
+
+        self._check_node_consistency(node)
+        self._nodes.add(node)
+        logger.debug(f"Added node: {node.reference}")
+
+        if self._topological_order is not None:
+            self._topological_order = None
+
+        return True
+
+    @property
+    def sinks(self) -> list[T]:
+        """
+        Get all sink nodes (nodes with no dependents).
+
+        Returns:
+            list[T]: A list of sink nodes.
+        """
+        return [node for node in self._nodes if 0 == len(node.dependents)]
+
+    @property
+    def sources(self) -> list[T]:
+        """
+        Get all source nodes (nodes with no dependencies).
+
+        Returns:
+            list[T]: A list of source nodes.
+        """
+        return [node for node in self._nodes if 0 == len(node.depends_on)]
+
+    def subgraph_filtered(self, fn: Callable[[T], bool]) -> Graph[T]:
+        """
+        Create a new subgraph containing only nodes that satisfy the predicate.
+
+        Args:
+            fn (Callable[[T], bool]): The predicate function.
+
+        Returns:
+            Graph[T]: A new Graph containing the filtered nodes.
+        """
+        logger.debug("Creating filtered subgraph.")
+        return graph([node for node in self._nodes if fn(node)])
+
+    def subgraph_tagged(self, tag: str) -> Graph[T]:
+        """
+        Create a new subgraph containing only nodes with the specified tag.
+
+        Args:
+            tag (str): The tag to filter by.
+
+        Returns:
+            Graph[T]: A new Graph containing the tagged nodes.
+        """
+        logger.debug(f"Creating subgraph for tag: {tag}")
+        return graph([node for node in self._nodes if node.is_tagged(tag)])
+
+    def topological_order(self) -> list[T]:
+        """
+        Get the nodes in topological order.
+
+        Returns:
+            list[T]: A list of nodes sorted topologically.
+        """
+        if self._topological_order is None:
+            logger.debug("Calculating topological order.")
+            sorter = TopologicalSorter({node: node.depends_on for node in self._nodes})
+            self._topological_order = list(sorter.static_order())
+
+        return self._topological_order
+
+    def topological_order_filtered(self, fn: Callable[[T], bool]) -> list[T]:
+        """
+        Get a filtered list of nodes in topological order.
+
+        Args:
+            fn (Callable[[T], bool]): The predicate function.
+
+        Returns:
+            list[T]: Filtered topologically sorted nodes.
+        """
+        return [node for node in self.topological_order() if fn(node)]
+
+    def topological_order_tagged(self, tag: str) -> list[T]:
+        """
+        Get a list of nodes with a specific tag in topological order.
+
+        Args:
+            tag (str): The tag to filter by.
+
+        Returns:
+            list[T]: Tagged topologically sorted nodes.
+        """
+        return [node for node in self.topological_order() if node.is_tagged(tag)]

graphable/graphable.py

@@ -0,0 +1,125 @@
+from logging import getLogger
+from typing import cast
+
+logger = getLogger(__name__)
+
+
+class Graphable[T, S: Graphable[T, S]]:
+    """
+    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.
+        S: The type of the Graphable subclass (recursive bound).
+    """
+
+    def __init__(self, reference: T):
+        """
+        Initialize a Graphable node.
+
+        Args:
+            reference (T): The underlying object this node represents.
+        """
+        self._dependents: set[S] = set()
+        self._depends_on: set[S] = set()
+        self._reference: T = reference
+        self._tags: set[str] = set()
+        logger.debug(f"Created Graphable node for reference: {reference}")
+
+    def _add_dependent(self, dependent: S) -> None:
+        """
+        Internal method to add a dependent node (incoming edge in dependency graph).
+
+        Args:
+            dependent (S): The node that depends on this node.
+        """
+        if dependent not in self._dependents:
+            self._dependents.add(dependent)
+            logger.debug(
+                f"Node '{self.reference}': added dependent '{cast(Graphable, dependent).reference}'"
+            )
+
+    def _add_depends_on(self, depends_on: S) -> None:
+        """
+        Internal method to add a dependency (outgoing edge in dependency graph).
+
+        Args:
+            depends_on (S): The node that this node depends on.
+        """
+        if depends_on not in self._depends_on:
+            self._depends_on.add(depends_on)
+            logger.debug(
+                f"Node '{self.reference}': added dependency '{cast(Graphable, depends_on).reference}'"
+            )
+
+    def add_tag(self, tag: str) -> None:
+        """
+        Add a tag to this node.
+
+        Args:
+            tag (str): The tag to add.
+        """
+        self._tags.add(tag)
+        logger.debug(f"Added tag '{tag}' to {self.reference}")
+
+    @property
+    def dependents(self) -> set[S]:
+        """
+        Get the set of nodes that depend on this node.
+
+        Returns:
+            set[S]: A copy of the dependents set.
+        """
+        return set(self._dependents)
+
+    @property
+    def depends_on(self) -> set[S]:
+        """
+        Get the set of nodes that this node depends on.
+
+        Returns:
+            set[S]: A copy of the dependencies set.
+        """
+        return set(self._depends_on)
+
+    def is_tagged(self, tag: str) -> bool:
+        """
+        Check if the node has a specific tag.
+
+        Args:
+            tag (str): The tag to check.
+
+        Returns:
+            bool: True if the tag exists, False otherwise.
+        """
+        return tag in self._tags
+
+    @property
+    def reference(self) -> T:
+        """
+        Get the underlying reference object.
+
+        Returns:
+            T: The reference object.
+        """
+        return self._reference
+
+    @property
+    def tags(self) -> set[str]:
+        """
+        Get the set of tags for this node.
+
+        Returns:
+            set[str]: A copy of the tags set.
+        """
+        return set(self._tags)
+
+    def remove_tag(self, tag: str) -> None:
+        """
+        Remove a tag from this node.
+
+        Args:
+            tag (str): The tag to remove.
+        """
+        self._tags.discard(tag)
+        logger.debug(f"Removed tag '{tag}' from {self.reference}")

graphable/views/graphviz.py

@@ -0,0 +1,148 @@
+from dataclasses import dataclass
+from logging import getLogger
+from pathlib import Path
+from shutil import which
+from subprocess import PIPE, CalledProcessError, run
+from typing import Callable
+
+from ..graph import Graph
+from ..graphable import Graphable
+
+logger = getLogger(__name__)
+
+
+@dataclass
+class GraphvizStylingConfig:
+    """
+    Configuration for customizing Graphviz DOT generation.
+
+    Attributes:
+        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: Callable[[Graphable], str] = lambda n: str(n.reference)
+    node_label_fnc: Callable[[Graphable], str] = lambda n: str(n.reference)
+    node_attr_fnc: Callable[[Graphable], dict[str, str]] | None = None
+    edge_attr_fnc: Callable[[Graphable, Graphable], 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
+
+
+def _check_dot_on_path() -> None:
+    """Check if 'dot' executable is available in the system path."""
+    if which("dot") is None:
+        logger.error("dot not found on PATH.")
+        raise FileNotFoundError("dot (Graphviz) is required but not available on $PATH")
+
+
+def _format_attrs(attrs: dict[str, str] | None) -> str:
+    """Format a dictionary of attributes into a DOT attribute string."""
+    if not attrs:
+        return ""
+    parts = [f'{k}="{v}"' for k, v in attrs.items()]
+    return f" [{', '.join(parts)}]"
+
+
+def create_topology_graphviz_dot(
+    graph: Graph, config: GraphvizStylingConfig | None = None
+) -> str:
+    """
+    Generate Graphviz DOT definition from a Graph.
+
+    Args:
+        graph (Graph): The graph to convert.
+        config (GraphvizStylingConfig | None): Styling configuration.
+
+    Returns:
+        str: The Graphviz DOT definition string.
+    """
+    config = config or GraphvizStylingConfig()
+    dot: list[str] = ["digraph G {"]
+
+    # Global attributes
+    if config.graph_attr:
+        for k, v in config.graph_attr.items():
+            dot.append(f'    {k}="{v}";')
+
+    if config.node_attr_default:
+        dot.append(f"    node{_format_attrs(config.node_attr_default)};")
+
+    if config.edge_attr_default:
+        dot.append(f"    edge{_format_attrs(config.edge_attr_default)};")
+
+    # Nodes and Edges
+    for node in graph.topological_order():
+        node_ref = config.node_ref_fnc(node)
+        node_attrs = {"label": config.node_label_fnc(node)}
+        if config.node_attr_fnc:
+            node_attrs.update(config.node_attr_fnc(node))
+
+        dot.append(f'    "{node_ref}"{_format_attrs(node_attrs)};')
+
+        for dependent in node.dependents:
+            dep_ref = config.node_ref_fnc(dependent)
+            edge_attrs = {}
+            if config.edge_attr_fnc:
+                edge_attrs.update(config.edge_attr_fnc(node, dependent))
+
+            dot.append(f'    "{node_ref}" -> "{dep_ref}"{_format_attrs(edge_attrs)};')
+
+    dot.append("}")
+    return "\n".join(dot)
+
+
+def export_topology_graphviz_dot(
+    graph: Graph, output: Path, config: GraphvizStylingConfig | None = None
+) -> None:
+    """
+    Export the graph to a Graphviz .dot file.
+
+    Args:
+        graph (Graph): The graph to export.
+        output (Path): The output file path.
+        config (GraphvizStylingConfig | None): Styling configuration.
+    """
+    logger.info(f"Exporting graphviz dot to: {output}")
+    with open(output, "w+") as f:
+        f.write(create_topology_graphviz_dot(graph, config))
+
+
+def export_topology_graphviz_svg(
+    graph: Graph, output: Path, config: GraphvizStylingConfig | None = None
+) -> None:
+    """
+    Export the graph to an SVG file using the 'dot' command.
+
+    Args:
+        graph (Graph): The graph to export.
+        output (Path): The output file path.
+        config (GraphvizStylingConfig | None): Styling configuration.
+    """
+    logger.info(f"Exporting graphviz svg to: {output}")
+    _check_dot_on_path()
+
+    dot_content: str = create_topology_graphviz_dot(graph, config)
+
+    try:
+        run(
+            ["dot", "-Tsvg", "-o", str(output)],
+            input=dot_content,
+            check=True,
+            stderr=PIPE,
+            stdout=PIPE,
+            text=True,
+        )
+        logger.info(f"Successfully exported SVG to {output}")
+    except CalledProcessError as e:
+        logger.error(f"Error executing dot: {e.stderr}")
+        raise
+    except Exception as e:
+        logger.error(f"Failed to export SVG to {output}: {e}")
+        raise

graphable/views/mermaid.py

@@ -0,0 +1,241 @@
+from atexit import register as on_script_exit
+from dataclasses import dataclass
+from functools import cache
+from logging import getLogger
+from pathlib import Path
+from shutil import which
+from string import Template
+from subprocess import PIPE, CalledProcessError, run
+from tempfile import NamedTemporaryFile
+from typing import Callable
+
+from ..graph import Graph
+from ..graphable import Graphable
+
+logger = getLogger(__name__)
+
+_MERMAID_CONFIG_JSON: str = '{ "htmlLabels": false }'
+_MMDC_SCRIPT_TEMPLATE: Template = Template("""
+#!/bin/env bash
+/bin/env mmdc -c $mermaid_config -i $source -o $output -p $puppeteer_config
+""")
+_PUPPETEER_CONFIG_JSON: str = '{ "args": [ "--no-sandbox" ] }'
+
+
+@dataclass
+class MermaidStylingConfig:
+    """
+    Configuration for customizing Mermaid diagram generation.
+
+    Attributes:
+        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: Callable[[Graphable], str] = lambda n: n.reference
+    node_text_fnc: Callable[[Graphable], str] = lambda n: n.reference
+    node_style_fnc: Callable[[Graphable], str] | None = None
+    node_style_default: str | None = None
+    link_text_fnc: Callable[[Graphable, Graphable], str] = lambda n, sn: "-->"
+    link_style_fnc: Callable[[Graphable, Graphable], str] | None = None
+    link_style_default: str | None = None
+
+
+def _check_mmdc_on_path() -> None:
+    """Check if 'mmdc' executable is available in the system path."""
+    if which("mmdc") is None:
+        logger.error("mmdc not found on PATH.")
+        raise FileNotFoundError("mmdc is required but not available on $PATH")
+
+
+def _cleanup_on_exit(path: Path) -> None:
+    """
+    Remove a temporary file if it still exists at script exit.
+
+    Args:
+        path (Path): The path to the file to remove.
+    """
+    if path.exists():
+        logger.debug(f"Cleaning up temporary file: {path}")
+        path.unlink()
+
+
+def _create_mmdc_script(mmdc_script_content: str) -> Path:
+    """Create a temporary shell script for executing mmdc."""
+    with NamedTemporaryFile(delete=False, mode="w+", suffix=".sh") as f:
+        f.write(mmdc_script_content)
+        mmdc_script: Path = Path(f.name)
+    logger.debug(f"Created temporary mmdc script: {mmdc_script}")
+    return mmdc_script
+
+
+def create_mmdc_script_content(source: Path, output: Path) -> str:
+    """
+    Generate the bash script content to run mmdc.
+
+    Args:
+        source (Path): Path to the source mermaid file.
+        output (Path): Path to the output file.
+
+    Returns:
+        str: The script content.
+    """
+    mmdc_script_content: str = _MMDC_SCRIPT_TEMPLATE.substitute(
+        mermaid_config=_write_mermaid_config(),
+        output=output,
+        puppeteer_config=_write_puppeteer_config(),
+        source=source,
+    )
+
+    return mmdc_script_content
+
+
+def create_topology_mermaid_mmd(
+    graph: Graph, config: MermaidStylingConfig | None = None
+) -> str:
+    """
+    Generate Mermaid flowchart definition from a Graph.
+
+    Args:
+        graph (Graph): The graph to convert.
+        config (MermaidStylingConfig | None): Styling configuration.
+
+    Returns:
+        str: The mermaid graph definition string.
+    """
+    config = config or MermaidStylingConfig()
+
+    def link_style(node: Graphable, subnode: Graphable) -> str | None:
+        if config.link_style_fnc:
+            return config.link_style_fnc(node, subnode)
+        return None
+
+    def node_style(node: Graphable) -> str | None:
+        if config.node_style_fnc and (style := config.node_style_fnc(node)):
+            return style
+        return config.node_style_default
+
+    link_num: int = 0
+    mermaid: list[str] = ["flowchart TD"]
+    for node in graph.topological_order():
+        if subnodes := node.dependents:
+            for subnode in subnodes:
+                mermaid.append(
+                    f"{config.node_text_fnc(node)} {config.link_text_fnc(node, subnode)} {config.node_text_fnc(subnode)}"
+                )
+                if style := link_style(node, subnode):
+                    mermaid.append(f"linkStyle {link_num} {style}")
+                link_num += 1
+        else:
+            mermaid.append(f"{config.node_text_fnc(node)}")
+
+        if style := node_style(node):
+            mermaid.append(f"style {config.node_ref_fnc(node)} {style}")
+
+    if config.link_style_default:
+        mermaid.append(f"linkStyle default {config.link_style_default}")
+
+    return "\n".join(mermaid)
+
+
+def _execute_build_script(build_script: Path) -> bool:
+    """
+    Execute the build script.
+
+    Args:
+        build_script (Path): Path to the script.
+
+    Returns:
+        bool: True if execution succeeded, False otherwise.
+    """
+    try:
+        run(
+            ["/bin/env", "bash", build_script],
+            check=True,
+            stderr=PIPE,
+            stdout=PIPE,
+            text=True,
+        )
+        return True
+    except CalledProcessError as e:
+        logger.error(f"Error executing {build_script}: {e.stderr}")
+    except FileNotFoundError:
+        logger.error("Could not execute script: file not found.")
+    return False
+
+
+def export_topology_mermaid_mmd(
+    graph: Graph, output: Path, config: MermaidStylingConfig | None = None
+) -> None:
+    """
+    Export the graph to a Mermaid .mmd file.
+
+    Args:
+        graph (Graph): The graph to export.
+        output (Path): The output file path.
+        config (MermaidStylingConfig | None): Styling configuration.
+    """
+    logger.info(f"Exporting mermaid mmd to: {output}")
+    with open(output, "w+") as f:
+        f.write(create_topology_mermaid_mmd(graph, config))
+
+
+def export_topology_mermaid_svg(
+    graph: Graph, output: Path, config: MermaidStylingConfig | None = None
+) -> None:
+    """
+    Export the graph to an SVG file using mmdc.
+
+    Args:
+        graph (Graph): The graph to export.
+        output (Path): The output file path.
+        config (MermaidStylingConfig | None): Styling configuration.
+    """
+    logger.info(f"Exporting mermaid svg to: {output}")
+    _check_mmdc_on_path()
+
+    mermaid: str = create_topology_mermaid_mmd(graph, config)
+
+    with NamedTemporaryFile(delete=False, mode="w+", suffix=".mmd") as f:
+        f.write(mermaid)
+        source: Path = Path(f.name)
+
+    logger.debug(f"Created temporary mermaid source file: {source}")
+
+    build_script: Path = _create_mmdc_script(
+        create_mmdc_script_content(source=source, output=output)
+    )
+
+    if _execute_build_script(build_script):
+        build_script.unlink()
+        source.unlink()
+        logger.info(f"Successfully exported SVG to {output}")
+    else:
+        logger.error(f"Failed to export SVG to {output}")
+
+
+@cache
+def _write_mermaid_config() -> Path:
+    """Write temporary mermaid config file."""
+    with NamedTemporaryFile(delete=False, mode="w+", suffix=".json") as f:
+        f.write(_MERMAID_CONFIG_JSON)
+
+        path: Path = Path(f.name)
+        on_script_exit(lambda: _cleanup_on_exit(path))
+        return path
+
+
+@cache
+def _write_puppeteer_config() -> Path:
+    """Write temporary puppeteer config file."""
+    with NamedTemporaryFile(delete=False, mode="w+", suffix=".json") as f:
+        f.write(_PUPPETEER_CONFIG_JSON)
+
+        path: Path = Path(f.name)
+        on_script_exit(lambda: _cleanup_on_exit(path))
+        return path

graphable/views/texttree.py

@@ -0,0 +1,121 @@
+from dataclasses import dataclass
+from logging import getLogger
+from pathlib import Path
+from typing import Callable
+
+from ..graph import Graph
+from ..graphable import Graphable
+
+logger = getLogger(__name__)
+
+
+@dataclass
+class TextTreeStylingConfig:
+    """
+    Configuration for text tree representation of the graph.
+
+    Attributes:
+        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: Callable[[Graphable], str] = lambda n: n.reference
+
+
+def create_topology_tree_txt(
+    graph: Graph, config: TextTreeStylingConfig | None = None
+) -> str:
+    """
+    Create a text-based tree representation of the graph topology.
+
+    Args:
+        graph (Graph): The graph to convert.
+        config (TextTreeStylingConfig | None): Styling configuration.
+
+    Returns:
+        str: The text tree representation.
+    """
+    if config is None:
+        config = TextTreeStylingConfig()
+
+    logger.debug("Creating topology tree text.")
+
+    def create_topology_subtree_txt(
+        node: Graphable,
+        indent: str = "",
+        is_last: bool = True,
+        is_root: bool = True,
+        visited: set[Graphable] | None = None,
+    ) -> str:
+        """
+        Recursively generate the text representation for a subtree.
+
+        Args:
+            node (Graphable): The current node being processed.
+            indent (str): The current indentation string.
+            is_last (bool): Whether this node is the last sibling.
+            is_root (bool): Whether this is the root of the (sub)tree.
+            visited (set[Graphable] | None): Set of already visited nodes to detect cycles/redundancy.
+
+        Returns:
+            str: The text representation of the subtree.
+        """
+        if visited is None:
+            visited = set[Graphable]()
+        already_seen: bool = node in visited
+
+        subtree: list[str] = []
+        if is_root:
+            subtree.append(f"{indent}{config.node_text_fnc(node)}")
+
+            next_indent: str = indent
+
+        else:
+            marker: str = "└─ " if is_last else "├─ "
+            suffix: str = " (see above)" if already_seen and node.depends_on else ""
+            subtree.append(f"{indent}{marker}{config.node_text_fnc(node)}{suffix}")
+
+            next_indent: str = indent + ("   " if is_last else "│  ")
+
+        if already_seen:
+            return "\n".join(subtree)
+        visited.add(node)
+
+        for i, subnode in enumerate(node.depends_on, start=1):
+            subtree.append(
+                create_topology_subtree_txt(
+                    node=subnode,
+                    indent=next_indent,
+                    is_last=(i == len(node.depends_on)),
+                    is_root=False,
+                    visited=visited,
+                )
+            )
+
+        return "\n".join(subtree)
+
+    tree: list[str] = []
+    for node in graph.sinks:
+        tree.append(
+            create_topology_subtree_txt(
+                node=node, indent=config.initial_indent, is_root=True
+            )
+        )
+    return "\n".join(tree)
+
+
+def export_topology_tree_txt(
+    graph: Graph, output: Path, config: TextTreeStylingConfig | None = None
+) -> None:
+    """
+    Export the graph to a text tree file.
+
+    Args:
+        graph (Graph): The graph to export.
+        output (Path): The output file path.
+        config (TextTreeStylingConfig | None): Styling configuration.
+    """
+    logger.info(f"Exporting topology tree text to: {output}")
+    with open(output, "w+") as f:
+        f.write(create_topology_tree_txt(graph, config))

graphable-0.2.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.3
+Name: graphable
+Version: 0.2.0
+Summary: A lightweight, type-safe library for building, managing, and visualizing dependency graphs.
+Keywords: graph,dependency-graph,topological-sort,mermaid,visualization
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# graphable
+
+[![CI](https://github.com/TheTrueSCU/graphable/actions/workflows/ci.yml/badge.svg)](https://github.com/TheTrueSCU/graphable/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`graphable` is a lightweight, type-safe Python library for building, managing, and visualizing dependency graphs. It provides a simple API for defining nodes and their relationships, performing topological sorts, and exporting graphs to various formats like Mermaid and ASCII text trees.
+
+## Features
+
+- **Type-Safe:** Built with modern Python generics and type hints.
+- **Topological Sorting:** Easily get nodes in dependency order.
+- **Filtering & Tagging:** Create subgraphs based on custom predicates or tags.
+- **Visualizations:**
+    - **Mermaid:** Generate flowchart definitions or export directly to SVG.
+    - **Text Tree:** Generate beautiful ASCII tree representations.
+- **Modern Tooling:** Managed with `uv` and `just`.
+
+## Installation
+
+```bash
+uv add graphable
+# or
+pip install graphable
+```
+
+## Quick Start
+
+```python
+from graphable.graph import Graph
+from graphable.graphable import Graphable
+from graphable.views.texttree import create_topology_tree_txt
+
+# 1. Define your nodes
+a = Graphable("Database")
+b = Graphable("API Service")
+c = Graphable("Web Frontend")
+
+# 2. Build the graph
+g = Graph()
+g.add_edge(a, b)  # API Service depends on Database
+g.add_edge(b, c)  # Web Frontend depends on API Service
+
+# 3. Get topological order
+for node in g.topological_order():
+    print(node.reference)
+# Output: Database, API Service, Web Frontend
+
+# 4. Visualize as a text tree
+print(create_topology_tree_txt(g))
+# Output:
+# Web Frontend
+# └─ API Service
+#    └─ Database
+```
+
+## Visualizing with Mermaid
+
+```python
+from graphable.views.mermaid import create_topology_mermaid_mmd
+
+mmd = create_topology_mermaid_mmd(g)
+print(mmd)
+# Output:
+# flowchart TD
+# Database --> API Service
+# API Service --> Web Frontend
+```
+
+## Documentation
+
+Full documentation is available in the `docs/` directory. You can build it locally:
+
+```bash
+just docs-view
+```
+
+## Development
+
+This project uses `uv` for dependency management and `just` as a command runner.
+
+```bash
+just install    # Install dependencies
+just check      # Run linting, type checking, and tests
+just coverage   # Run tests with coverage report
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

graphable-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+graphable/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+graphable/graph.py,sha256=lTjVep8I6i4szrgyrMMLbsCPD2MhfhJ131woMgZCedo,11080
+graphable/graphable.py,sha256=I4niraMNhaBMRdV-P3HhFukMeohr5Y60--2-5X3XwkI,3416
+graphable/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+graphable/views/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+graphable/views/graphviz.py,sha256=BEpORB-1hY9wsmmiEwN5Yuf-FOXcpj0F4bVkpg0wli8,4906
+graphable/views/mermaid.py,sha256=lxI3ZWjnbQAuCYgEQ75b79Rqc1RMKU5bIVeQf59d6ak,7701
+graphable/views/texttree.py,sha256=ctUF7oG2noeGoED7IP-He0VDCJvbz3j1wNViC2vaJ1s,3651
+graphable-0.2.0.dist-info/WHEEL,sha256=iHtWm8nRfs0VRdCYVXocAWFW8ppjHL-uTJkAdZJKOBM,80
+graphable-0.2.0.dist-info/METADATA,sha256=bHZXsJ-DFigAbUNu0rqFJh4CAkXMe3duHXy5REss0U8,3130
+graphable-0.2.0.dist-info/RECORD,,

graphable-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.30
+Root-Is-Purelib: true
+Tag: py3-none-any