termaid 0.1.1__py3-none-any.whl

termaid/__init__.py

@@ -0,0 +1,178 @@
+"""termaid - Render Mermaid diagram syntax as beautiful Unicode art in the terminal."""
+from __future__ import annotations
+
+import re
+
+from .graph.model import Graph
+from .parser.flowchart import parse_flowchart
+from .parser.statediagram import parse_state_diagram
+
+
+__version__ = "0.1.0"
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n.*?\n---\s*\n", re.DOTALL)
+
+
+def _strip_frontmatter(text: str) -> str:
+    """Strip YAML frontmatter (---...---) from the beginning of mermaid source."""
+    return _FRONTMATTER_RE.sub("", text)
+
+
+def parse(source: str) -> Graph:
+    """Parse mermaid syntax and return a Graph model.
+
+    Auto-detects diagram type (flowchart or state diagram).
+
+    Args:
+        source: Mermaid diagram source text
+
+    Returns:
+        Parsed Graph model
+    """
+    text = _strip_frontmatter(source.strip())
+    if text.startswith("stateDiagram"):
+        return parse_state_diagram(text)
+    return parse_flowchart(text)
+
+
+def render(
+    source: str,
+    *,
+    use_ascii: bool = False,
+    padding_x: int = 4,
+    padding_y: int = 2,
+    rounded_edges: bool = True,
+) -> str:
+    """Render mermaid syntax as Unicode (or ASCII) art.
+
+    Args:
+        source: Mermaid diagram source text
+        use_ascii: Use ASCII characters instead of Unicode box-drawing
+        padding_x: Horizontal padding inside node boxes
+        padding_y: Vertical padding inside node boxes
+
+    Returns:
+        Rendered diagram as a string
+
+    Example:
+        >>> from termaid import render
+        >>> print(render("graph LR\\n  A --> B --> C"))
+    """
+    try:
+        text = _strip_frontmatter(source.strip())
+        if text.startswith("sequenceDiagram"):
+            from .parser.sequence import parse_sequence_diagram
+            from .renderer.sequence import render_sequence
+            diagram = parse_sequence_diagram(text)
+            return render_sequence(diagram, use_ascii=use_ascii).to_string()
+
+        if text.startswith("classDiagram"):
+            from .parser.classdiagram import parse_class_diagram
+            from .renderer.classdiagram import render_class_diagram
+            diagram = parse_class_diagram(text)
+            return render_class_diagram(diagram, use_ascii=use_ascii).to_string()
+
+        if text.startswith("erDiagram"):
+            from .parser.erdiagram import parse_er_diagram
+            from .renderer.erdiagram import render_er_diagram
+            diagram = parse_er_diagram(text)
+            return render_er_diagram(diagram, use_ascii=use_ascii).to_string()
+
+        if text.startswith("block"):
+            from .parser.blockdiagram import parse_block_diagram
+            from .renderer.blockdiagram import render_block_diagram
+            diagram = parse_block_diagram(text)
+            return render_block_diagram(diagram, use_ascii=use_ascii).to_string()
+
+        if text.startswith("gitGraph") or (text.startswith("%%{init") and "gitGraph" in text):
+            from .parser.gitgraph import parse_git_graph
+            from .renderer.gitgraph import render_git_graph
+            diagram = parse_git_graph(text)
+            return render_git_graph(diagram, use_ascii=use_ascii).to_string()
+
+        graph = parse(text)
+        from .output.text import render_text
+        return render_text(graph, use_ascii=use_ascii, padding_x=padding_x, padding_y=padding_y, rounded_edges=rounded_edges)
+    except Exception as exc:
+        return f"[termaid] Failed to render diagram: {exc}"
+
+
+def render_rich(
+    source: str,
+    *,
+    use_ascii: bool = False,
+    padding_x: int = 4,
+    padding_y: int = 2,
+    rounded_edges: bool = True,
+    theme: str = "default",
+):
+    """Render mermaid syntax as a Rich Text object with colors.
+
+    Requires: pip install termaid[rich]
+
+    Args:
+        source: Mermaid diagram source text
+        use_ascii: Use ASCII characters instead of Unicode
+        padding_x: Horizontal padding inside node boxes
+        padding_y: Vertical padding inside node boxes
+        theme: Color theme name (default, terra, neon, mono, amber, phosphor)
+
+    Returns:
+        rich.text.Text object
+    """
+    try:
+        text = _strip_frontmatter(source.strip())
+        if text.startswith("sequenceDiagram"):
+            from .parser.sequence import parse_sequence_diagram
+            from .renderer.sequence import render_sequence
+            from .output.rich import render_sequence_rich
+            diagram = parse_sequence_diagram(text)
+            canvas = render_sequence(diagram, use_ascii=use_ascii)
+            return render_sequence_rich(canvas, theme=theme)
+
+        if text.startswith("classDiagram"):
+            from .parser.classdiagram import parse_class_diagram
+            from .renderer.classdiagram import render_class_diagram
+            from .output.rich import render_sequence_rich
+            diagram = parse_class_diagram(text)
+            canvas = render_class_diagram(diagram, use_ascii=use_ascii)
+            return render_sequence_rich(canvas, theme=theme)
+
+        if text.startswith("erDiagram"):
+            from .parser.erdiagram import parse_er_diagram
+            from .renderer.erdiagram import render_er_diagram
+            from .output.rich import render_sequence_rich
+            diagram = parse_er_diagram(text)
+            canvas = render_er_diagram(diagram, use_ascii=use_ascii)
+            return render_sequence_rich(canvas, theme=theme)
+
+        if text.startswith("block"):
+            from .parser.blockdiagram import parse_block_diagram
+            from .renderer.blockdiagram import render_block_diagram
+            from .output.rich import render_sequence_rich
+            diagram = parse_block_diagram(text)
+            canvas = render_block_diagram(diagram, use_ascii=use_ascii)
+            return render_sequence_rich(canvas, theme=theme)
+
+        if text.startswith("gitGraph") or (text.startswith("%%{init") and "gitGraph" in text):
+            from .parser.gitgraph import parse_git_graph
+            from .renderer.gitgraph import render_git_graph
+            from .output.rich import render_sequence_rich
+            diagram = parse_git_graph(text)
+            canvas = render_git_graph(diagram, use_ascii=use_ascii)
+            return render_sequence_rich(canvas, theme=theme)
+
+        graph = parse(text)
+        from .output.rich import render_rich as _render_rich
+        return _render_rich(graph, use_ascii=use_ascii, padding_x=padding_x, padding_y=padding_y, rounded_edges=rounded_edges, theme=theme)
+    except Exception as exc:
+        from rich.text import Text
+        return Text(f"[termaid] Failed to render diagram: {exc}")
+
+
+# Lazy import for MermaidWidget
+def __getattr__(name: str):
+    if name == "MermaidWidget":
+        from .output.widget import _get_widget_class
+        return _get_widget_class()
+    raise AttributeError(f"module 'termaid' has no attribute {name!r}")

termaid/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running termaid as a module: python -m termaid"""
+from .cli import main
+
+main()

termaid/cli.py

@@ -0,0 +1,129 @@
+"""CLI entry point for termaid."""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="termaid",
+        description="Render Mermaid diagrams as Unicode art in the terminal",
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        help="Mermaid diagram file (.mmd). Reads from stdin if not provided.",
+    )
+    parser.add_argument(
+        "--ascii",
+        action="store_true",
+        help="Use ASCII characters instead of Unicode box-drawing",
+    )
+    parser.add_argument(
+        "--padding-x",
+        type=int,
+        default=4,
+        help="Horizontal padding inside node boxes (default: 4)",
+    )
+    parser.add_argument(
+        "--padding-y",
+        type=int,
+        default=2,
+        help="Vertical padding inside node boxes (default: 2)",
+    )
+    parser.add_argument(
+        "--sharp-edges",
+        action="store_true",
+        help="Use sharp corners on edge turns (┌┐└┘) instead of rounded (╭╮╰╯)",
+    )
+    parser.add_argument(
+        "--theme",
+        default=None,
+        choices=["default", "terra", "neon", "mono", "amber", "phosphor"],
+        help="Color theme. Requires 'rich' package (pip install termaid[rich]).",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s 0.1.0",
+    )
+
+    args = parser.parse_args(argv)
+
+    use_color = args.theme is not None
+    theme = args.theme or "default"
+
+    # Read input
+    if args.file:
+        try:
+            with open(args.file) as f:
+                source = f.read()
+        except FileNotFoundError:
+            print(f"Error: File not found: {args.file}", file=sys.stderr)
+            return 1
+        except OSError as e:
+            print(f"Error reading file: {e}", file=sys.stderr)
+            return 1
+    elif not sys.stdin.isatty():
+        source = sys.stdin.read()
+    else:
+        print("Error: No input provided. Pass a file or pipe input.", file=sys.stderr)
+        print("Usage: termaid diagram.mmd", file=sys.stderr)
+        print("       echo 'graph LR; A-->B' | termaid", file=sys.stderr)
+        return 1
+
+    source = source.strip()
+    if not source:
+        print("Error: Empty input.", file=sys.stderr)
+        return 1
+
+    try:
+        from termaid import render, render_rich
+    except ImportError:
+        # Support running directly: python3 src/termaid/cli.py
+        # __file__ is src/termaid/cli.py → go up to src/
+        _src_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        sys.path.insert(0, _src_dir)
+        try:
+            from termaid import render, render_rich
+        except ImportError:
+            print("Error: termaid package not found. Install with: pip install -e .", file=sys.stderr)
+            return 1
+
+    try:
+        if use_color:
+            result = render_rich(
+                source,
+                use_ascii=args.ascii,
+                padding_x=args.padding_x,
+                padding_y=args.padding_y,
+                rounded_edges=not args.sharp_edges,
+                theme=theme,
+            )
+            try:
+                from rich import print as rprint
+                rprint(result)
+            except ImportError:
+                print("Error: 'rich' package required for --theme. Install with: pip install termaid[rich]", file=sys.stderr)
+                return 1
+        else:
+            result = render(
+                source,
+                use_ascii=args.ascii,
+                padding_x=args.padding_x,
+                padding_y=args.padding_y,
+                rounded_edges=not args.sharp_edges,
+            )
+            print(result)
+    except Exception as e:
+        print(f"Error rendering diagram: {e}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

termaid/graph/__init__.py

@@ -0,0 +1,4 @@
+from .model import Graph, Node, Edge, Subgraph
+from .shapes import NodeShape
+
+__all__ = ["Graph", "Node", "Edge", "Subgraph", "NodeShape"]

termaid/graph/model.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+
+from .shapes import NodeShape
+
+
+@dataclass
+class GraphNote:
+    """A note attached to a node in the graph."""
+    text: str
+    position: str  # "rightof" or "leftof"
+    target: str    # node id
+
+
+@dataclass
+class LabelSegment:
+    """A segment of a node label with optional bold/italic styling."""
+    text: str
+    bold: bool = False
+    italic: bool = False
+
+
+class ArrowType(Enum):
+    ARROW = auto()    # --> (filled triangle ►▼◄▲)
+    CIRCLE = auto()   # --o (○)
+    CROSS = auto()    # --x (×)
+
+
+class EdgeStyle(Enum):
+    SOLID = auto()       # -->
+    DOTTED = auto()      # -.->
+    THICK = auto()       # ==>
+    INVISIBLE = auto()   # ~~~
+
+
+class Direction(Enum):
+    TB = "TB"
+    TD = "TD"
+    LR = "LR"
+    BT = "BT"
+    RL = "RL"
+
+    @property
+    def is_vertical(self) -> bool:
+        return self in (Direction.TB, Direction.TD, Direction.BT)
+
+    @property
+    def is_horizontal(self) -> bool:
+        return self in (Direction.LR, Direction.RL)
+
+    @property
+    def is_reversed(self) -> bool:
+        return self in (Direction.BT, Direction.RL)
+
+    def normalized(self) -> Direction:
+        """Return the non-reversed equivalent (BT->TB, RL->LR)."""
+        if self == Direction.BT:
+            return Direction.TB
+        if self == Direction.RL:
+            return Direction.LR
+        if self == Direction.TD:
+            return Direction.TB
+        return self
+
+
+@dataclass
+class Node:
+    id: str
+    label: str
+    shape: NodeShape = NodeShape.RECTANGLE
+    style_class: str | None = None
+    label_segments: list[LabelSegment] | None = None
+
+    def __hash__(self) -> int:
+        return hash(self.id)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Node):
+            return self.id == other.id
+        return NotImplemented
+
+
+@dataclass
+class Edge:
+    source: str
+    target: str
+    label: str = ""
+    style: EdgeStyle = EdgeStyle.SOLID
+    has_arrow_start: bool = False
+    has_arrow_end: bool = True
+    arrow_type_start: ArrowType = ArrowType.ARROW
+    arrow_type_end: ArrowType = ArrowType.ARROW
+    min_length: int = 1
+    source_is_subgraph: bool = False
+    target_is_subgraph: bool = False
+
+    @property
+    def is_bidirectional(self) -> bool:
+        return self.has_arrow_start and self.has_arrow_end
+
+    @property
+    def is_self_reference(self) -> bool:
+        return self.source == self.target
+
+
+@dataclass
+class Subgraph:
+    id: str
+    label: str
+    node_ids: list[str] = field(default_factory=list)
+    children: list[Subgraph] = field(default_factory=list)
+    direction: Direction | None = None
+    parent: Subgraph | None = field(default=None, repr=False)
+
+
+@dataclass
+class Graph:
+    direction: Direction = Direction.TB
+    nodes: dict[str, Node] = field(default_factory=dict)
+    edges: list[Edge] = field(default_factory=list)
+    subgraphs: list[Subgraph] = field(default_factory=list)
+    node_order: list[str] = field(default_factory=list)
+    class_defs: dict[str, dict[str, str]] = field(default_factory=dict)
+    node_styles: dict[str, dict[str, str]] = field(default_factory=dict)
+    link_styles: dict[int, dict[str, str]] = field(default_factory=dict)
+    warnings: list[str] = field(default_factory=list)
+    notes: list[GraphNote] = field(default_factory=list)
+
+    def add_node(self, node: Node) -> None:
+        if node.id not in self.nodes:
+            self.nodes[node.id] = node
+            self.node_order.append(node.id)
+        else:
+            existing = self.nodes[node.id]
+            if node.label != node.id and existing.label == existing.id:
+                existing.label = node.label
+            if node.shape != NodeShape.RECTANGLE:
+                existing.shape = node.shape
+            if node.style_class:
+                existing.style_class = node.style_class
+
+    def add_edge(self, edge: Edge) -> None:
+        self.edges.append(edge)
+
+    def get_roots(self) -> list[str]:
+        """Nodes with no incoming edges, in definition order."""
+        targets = {e.target for e in self.edges}
+        roots = [nid for nid in self.node_order if nid not in targets]
+        return roots if roots else [self.node_order[0]] if self.node_order else []
+
+    def get_children(self, node_id: str) -> list[str]:
+        """Get target nodes of outgoing edges from node_id, in order."""
+        seen: set[str] = set()
+        children: list[str] = []
+        for e in self.edges:
+            if e.source == node_id and e.target != node_id and e.target not in seen:
+                seen.add(e.target)
+                children.append(e.target)
+        return children
+
+    def find_subgraph_by_id(self, sg_id: str) -> Subgraph | None:
+        """Find a subgraph by its ID (recursive search)."""
+        def _search(subs: list[Subgraph]) -> Subgraph | None:
+            for sg in subs:
+                if sg.id == sg_id:
+                    return sg
+                result = _search(sg.children)
+                if result:
+                    return result
+            return None
+        return _search(self.subgraphs)
+
+    def find_subgraph_for_node(self, node_id: str) -> Subgraph | None:
+        """Find the innermost subgraph containing a node."""
+        def _search(subs: list[Subgraph]) -> Subgraph | None:
+            for sg in subs:
+                result = _search(sg.children)
+                if result:
+                    return result
+                if node_id in sg.node_ids:
+                    return sg
+            return None
+        return _search(self.subgraphs)

termaid/graph/shapes.py

@@ -0,0 +1,22 @@
+from enum import Enum, auto
+
+
+class NodeShape(Enum):
+    """Supported node shapes in Mermaid flowcharts."""
+    RECTANGLE = auto()      # A[text] or plain A
+    ROUNDED = auto()        # A(text)
+    STADIUM = auto()        # A([text])
+    SUBROUTINE = auto()     # A[[text]]
+    DIAMOND = auto()        # A{text}
+    HEXAGON = auto()        # A{{text}}
+    CIRCLE = auto()         # A((text))
+    DOUBLE_CIRCLE = auto()  # A(((text)))
+    ASYMMETRIC = auto()     # A>text]
+    CYLINDER = auto()       # A[(text)]
+    PARALLELOGRAM = auto()  # A[/text/]
+    PARALLELOGRAM_ALT = auto()  # A[\text\]
+    TRAPEZOID = auto()      # A[/text\]
+    TRAPEZOID_ALT = auto()  # A[\text/]
+    START_STATE = auto()    # [*] start (filled circle ●)
+    END_STATE = auto()      # [*] end (bullseye ◉)
+    FORK_JOIN = auto()      # <<fork>>/<<join>> (thick bar ━━━)

termaid/layout/__init__.py

@@ -0,0 +1,3 @@
+from .grid import GridLayout
+
+__all__ = ["GridLayout"]