termaid 0.1.1__tar.gz

termaid-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run tests
+        run: uv run pytest tests/ -q

termaid-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

termaid-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+.DS_Store
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+# Scratch diagram files in root
+/*.mmd

termaid-0.1.1/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.1.1 (2026-03-04)
+
+- Rename package from `termmaid` to `termaid`
+
+## 0.1.0 (2026-03-04)
+
+Initial release.
+
+### Features
+
+- **7 diagram types:** flowcharts, sequence, class, ER, state, block, and git graphs
+- **Flowcharts** (`graph`/`flowchart`) with all 5 directions (`LR`, `RL`, `TD`/`TB`, `BT`)
+- **Sequence diagrams** with participants, actors, solid/dashed messages
+- **Class diagrams** with attributes, methods, visibility, and 6 relationship types
+- **ER diagrams** with cardinality, attributes, keys, and relationship labels
+- **State diagrams** (`stateDiagram-v2`) with transitions, composite states, stereotypes
+- **Block diagrams** (`block-beta`) with column layout and spanning
+- **Git graphs** (`gitGraph`) with branches, merges, cherry-picks, tags, and 3 orientations
+- 14 flowchart node shapes: rectangle, rounded, stadium, subroutine, diamond, hexagon, circle, double circle, asymmetric, cylinder, parallelogram, parallelogram alt, trapezoid, trapezoid alt
+- 3 edge styles: solid, dotted, thick
+- Bidirectional edges (`<-->`, `<-.->`, `<==>`)
+- Edge labels (`-->|label|`)
+- Subgraphs with nesting and cross-boundary edges
+- `classDef`, `style`, and `linkStyle` directives
+- `@{shape}` node syntax
+- Link length control (`--->`, `---->`)
+- Markdown labels (`**bold**`, `*italic*`)
+- ASCII mode (`--ascii`) for terminals without Unicode support
+- Colored output via Rich (`--color`) with 6 built-in themes
+- Textual widget for TUI applications
+- CLI tool with stdin/file input
+- Pure Python, zero runtime dependencies

termaid-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to termaid
+
+## Development setup
+
+```bash
+git clone https://github.com/fasouto/termaid.git
+cd termaid
+uv sync --all-extras
+```
+
+## Running tests
+
+```bash
+uv run pytest tests/ -q
+```
+
+To update snapshot tests after changing rendering output:
+
+```bash
+uv run pytest tests/ --update-snapshots
+```
+
+## Project structure
+
+```
+src/termaid/
+  __init__.py          # Public API: render(), render_rich(), parse()
+  cli.py               # CLI entry point (argparse)
+  graph/               # Graph data model (Node, Edge, Subgraph, NodeShape)
+  model/               # Diagram-specific models (sequence, class, ER, block, gitgraph)
+  parser/              # Mermaid syntax parsers (one per diagram type)
+  layout/              # Grid-based layout computation (flowcharts)
+  routing/             # A* edge routing (flowcharts)
+  renderer/            # Canvas rendering, shapes, charsets, themes
+  output/              # Output formats (text, rich, textual widget)
+tests/
+  fixtures/flowcharts/ # .mmd input fixtures + expected .txt outputs
+```
+
+### Architecture
+
+There are two rendering paths:
+
+**Path A — Flowcharts and state diagrams** use the shared `Graph` model with the grid layout engine and A* edge routing (`layout/` + `routing/` + `renderer/draw.py`).
+
+**Path B — All other diagram types** (sequence, class, ER, block, git graph) have their own model (`model/`), parser (`parser/`), and renderer (`renderer/`) that draw directly onto a `Canvas`.
+
+### Diagram dispatch
+
+Both `render()` and `render_rich()` auto-detect the diagram type from the source text prefix (e.g. `sequenceDiagram`, `classDiagram`, `gitGraph`) and dispatch to the appropriate parser + renderer.
+
+## Adding a new diagram type
+
+1. Create the model in `src/termaid/model/yourdiagram.py` (dataclasses)
+2. Create the parser in `src/termaid/parser/yourdiagram.py`
+3. Create the renderer in `src/termaid/renderer/yourdiagram.py` (returns a `Canvas`)
+4. Add dispatch in `src/termaid/__init__.py` (both `render()` and `render_rich()`)
+5. Add tests
+
+## Adding a new node shape
+
+1. Add the shape to `NodeShape` enum in `src/termaid/graph/shapes.py`
+2. Add parser detection in `src/termaid/parser/flowchart.py` (`_parse_node`)
+3. Add renderer in `src/termaid/renderer/shapes/__init__.py`
+4. Register in `SHAPE_RENDERERS` dict
+5. Add tests in `tests/test_shapes.py`
+
+## Adding a test fixture
+
+1. Create `tests/fixtures/flowcharts/my_test.mmd`
+2. Run `uv run pytest tests/test_renderer.py -q` — it auto-generates the expected output
+3. Review the generated `.txt` file in `tests/fixtures/expected/`
+4. Run again to confirm it passes

termaid-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabio Souto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

termaid-0.1.1/PKG-INFO

@@ -0,0 +1,416 @@
+Metadata-Version: 2.4
+Name: termaid
+Version: 0.1.1
+Summary: Render Mermaid diagram syntax as beautiful Unicode art in the terminal
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ascii,diagram,flowchart,mermaid,terminal,unicode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest-snapshot; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == 'rich'
+Provides-Extra: textual
+Requires-Dist: textual>=0.40; extra == 'textual'
+Description-Content-Type: text/markdown
+
+# termaid
+
+Terminal-native Mermaid rendering for Python.
+
+<p align="center">
+  <img src="demo/termaid-demo.gif" alt="termaid demo" width="800">
+</p>
+
+Render [Mermaid](https://mermaid.js.org/) diagrams as Unicode art directly in your terminal. Pure Python, zero dependencies.
+
+## Features
+
+- **7 diagram types:** flowcharts, sequence, class, ER, state, block, and git graphs
+- **Zero dependencies:** pure Python, nothing to install beyond the package itself
+- **Rich and Textual integration:** colored output and TUI widgets with optional extras
+- **6 color themes:** default, terra, neon, mono, amber, phosphor
+- **ASCII fallback:** works on any terminal, even the most basic ones
+- **Pipe-friendly CLI:** `cat diagram.mmd | termaid` just works
+
+## Why?
+
+Mermaid is great for documentation, but rendering it usually means spinning up a browser or calling an external service. termaid lets you render diagrams over SSH, in CI logs, inside TUI apps, or anywhere you have a Python environment. It was built because the existing tools in this space, like [mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) (Go) and [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) (TypeScript), don't offer a native Python library you can import and call directly.
+
+## Install
+
+```bash
+pip install termaid
+```
+
+## Quick start
+
+### CLI
+
+```bash
+termaid diagram.mmd
+echo "graph LR; A-->B-->C" | termaid
+termaid diagram.mmd --theme neon
+termaid diagram.mmd --ascii
+```
+
+### Python
+
+```python
+from termaid import render
+
+print(render("graph LR\n  A --> B --> C"))
+```
+
+```python
+# Colored output (requires: pip install termaid[rich])
+from termaid import render_rich
+from rich import print as rprint
+
+rprint(render_rich("graph LR\n  A --> B", theme="terra"))
+```
+
+```python
+# Textual TUI widget (requires: pip install termaid[textual])
+from termaid import MermaidWidget
+
+widget = MermaidWidget("graph LR\n  A --> B")
+```
+
+## Supported diagram types
+
+### Flowcharts
+
+All directions supported: `LR`, `RL`, `TD`/`TB`, `BT`.
+
+```mermaid
+graph TD
+    A[Start] --> B{Is valid?}
+    B -->|Yes| C(Process)
+    C --> D([Done])
+    B -->|No| E[Error]
+```
+
+```
+┌─────────────┐
+│             │
+│    Start    │
+│             │
+└──────┬──────┘
+       │
+       │
+       ▼
+┌──────◇──────┐
+│             │
+│  Is valid?  │
+│             │
+└──────◇──────┘
+       │
+       │
+       ╰──────────────────╮
+    Yes│                  │No
+       ▼                  ▼
+╭─────────────╮    ┌─────────────┐
+│             │    │             │
+│   Process   │    │    Error    │
+│             │    │             │
+╰──────┬──────╯    └─────────────┘
+       │
+       │
+       ▼
+╭─────────────╮
+(             )
+(    Done     )
+(             )
+╰─────────────╯
+```
+
+**Node shapes:** rectangle `[text]`, rounded `(text)`, diamond `{text}`, stadium `([text])`, subroutine `[[text]]`, circle `((text))`, double circle `(((text)))`, hexagon `{{text}}`, cylinder `[(text)]`, asymmetric `>text]`, parallelogram `[/text/]`, trapezoid `[/text\]`, and `@{shape}` syntax
+
+**Edge styles:** solid `-->`, dotted `-.->`, thick `==>`, bidirectional `<-->`, circle endpoint `--o`, cross endpoint `--x`, labeled `-->|text|`, variable length `--->`, `---->`
+
+**Styling:** `classDef`, `style`, `linkStyle` directives, `:::className` suffix
+
+**Subgraphs:** nesting, cross-boundary edges, per-subgraph `direction` override
+
+**Other:** `%%` comments, `;` line separators, Markdown labels `` "`**bold** *italic*`" ``, `&` operator (`A & B --> C`)
+
+### Sequence diagrams
+
+```mermaid
+sequenceDiagram
+    Alice->>Bob: Hello Bob
+    Bob-->>Alice: Hi Alice
+    Alice->>Bob: How are you?
+    Bob-->>Alice: Great!
+```
+
+```
+ ┌──────────┐      ┌──────────┐
+ │  Alice   │      │   Bob    │
+ └──────────┘      └──────────┘
+       ┆ Hello Bob       ┆
+       ──────────────────►
+       ┆ Hi Alice        ┆
+       ◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+       ┆ How are you?    ┆
+       ──────────────────►
+       ┆ Great!          ┆
+       ◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
+       ┆                 ┆
+```
+
+**Message types:** solid arrow `->>`, dashed arrow `-->>`, solid line `->`, dashed line `-->`
+
+**Participants:** `participant`, `actor`, aliases
+
+### Class diagrams
+
+```mermaid
+classDiagram
+    class Animal {
+        +String name
+        +int age
+        +makeSound()
+    }
+    class Dog {
+        +String breed
+        +fetch()
+    }
+    Animal <|-- Dog
+```
+
+```
+  ┌──────────────┐
+  │    Animal    │
+  ├──────────────┤
+  │ +String name │
+  │ +int age     │
+  ├──────────────┤
+  │ +makeSound() │
+  └──────────────┘
+          △
+          │
+          │
+          │
+  ┌───────────────┐
+  │      Dog      │
+  ├───────────────┤
+  │ +String breed │
+  ├───────────────┤
+  │ +fetch()      │
+  └───────────────┘
+```
+
+**Relationships:** inheritance `<|--`, composition `*--`, aggregation `o--`, association `--`, dependency `..>`, realization `..|>`
+
+**Members:** attributes and methods with visibility (`+` public, `-` private, `#` protected, `~` package)
+
+### ER diagrams
+
+```mermaid
+erDiagram
+    CUSTOMER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+```
+
+```
+  ┌──────────────┐
+  │   CUSTOMER   │
+  └──────────────┘
+          │1
+          │ places
+          │
+          │0..*
+  ┌──────────────┐
+  │    ORDER     │
+  └──────────────┘
+          │1
+          │ contains
+          │
+          │1..*
+  ┌──────────────┐
+  │  LINE-ITEM   │
+  └──────────────┘
+```
+
+**Cardinality:** `||` (exactly one), `o|` (zero or one), `}|` (one or more), `o{` (zero or more)
+
+**Line styles:** solid `--`, dashed `..`
+
+**Attributes:** type, name, keys (`PK`, `FK`, `UK`), comments
+
+### State diagrams
+
+```mermaid
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Processing : start
+    Processing --> Done : complete
+    Done --> [*]
+```
+
+```
+╭───────◯──────╮
+│              │
+│      ●       │
+│              │
+╰───────◯──────╯
+        │
+        │
+        ▼
+╭──────────────╮
+│              │
+│     Idle     │
+│              │
+╰───────┬──────╯
+        │
+   start│
+        ▼
+╭──────────────╮
+│              │
+│  Processing  │
+│              │
+╰───────┬──────╯
+        │
+complete│
+        ▼
+╭──────────────╮
+│              │
+│     Done     │
+│              │
+╰───────┬──────╯
+        │
+        │
+        ▼
+╭───────◯──────╮
+│              │
+│      ◉       │
+│              │
+╰───────◯──────╯
+```
+
+**Features:** `[*]` start/end states, transition labels, `state "name" as alias`, composite states (`state Parent { }`), stereotypes (`<<choice>>`, `<<fork>>`, `<<join>>`)
+
+### Block diagrams
+
+```mermaid
+block-beta
+    columns 3
+    A["Frontend"] B["API"] C["Database"]
+```
+
+```
+  ┌──────────┐    ┌──────────┐    ┌──────────┐
+  │          │    │          │    │          │
+  │ Frontend │    │   API    │    │ Database │
+  │          │    │          │    │          │
+  └──────────┘    └──────────┘    └──────────┘
+```
+
+**Features:** `columns N`, column spanning (`blockname:N`), links between blocks, nested blocks
+
+### Git graphs
+
+```mermaid
+gitGraph
+   commit id: "init"
+   commit id: "feat"
+   branch develop
+   commit id: "dev-1"
+   commit id: "dev-2"
+   checkout main
+   commit id: "fix"
+   merge develop id: "merge"
+```
+
+```
+  main    ───●─────●──────┼──────────────●──────●─
+           init  feat     │             fix   merge
+                          │                     │
+  develop                 ●───────●─────────────┼
+                        dev-1   dev-2
+```
+
+**Directions:** `LR` (default), `TB`, `BT`
+
+**Commands:** `commit` (with `id:`, `type:`, `tag:`), `branch` (with `order:`), `checkout`/`switch`, `merge`, `cherry-pick`
+
+**Commit types:** `NORMAL` (●), `REVERSE` (✖), `HIGHLIGHT` (■)
+
+**Config:** `%%{init: {"gitGraph": {"mainBranchName": "master"}}}%%`
+
+## CLI options
+
+| Flag | Description |
+|------|-------------|
+| `--ascii` | ASCII-only output (no Unicode box-drawing) |
+| `--theme NAME` | Color theme: `default`, `terra`, `neon`, `mono`, `amber`, `phosphor` (requires `pip install termaid[rich]`) |
+| `--padding-x N` | Horizontal padding inside boxes (default: 4) |
+| `--padding-y N` | Vertical padding inside boxes (default: 2) |
+| `--sharp-edges` | Sharp corners on edge turns instead of rounded |
+
+## Python API
+
+### `render(source, ...) -> str`
+
+Render a Mermaid diagram as a plain text string. Auto-detects diagram type.
+
+### `render_rich(source, ..., theme="default") -> rich.text.Text`
+
+Render as a [Rich](https://rich.readthedocs.io/) `Text` object with colors. Requires `pip install termaid[rich]`.
+
+### `MermaidWidget`
+
+A [Textual](https://textual.textualize.io/) widget with a reactive `source` attribute. Requires `pip install termaid[textual]`. Updates live when you change the `source` property.
+
+```python
+from termaid import MermaidWidget
+
+class MyApp(App):
+    def compose(self):
+        yield MermaidWidget("graph LR\n  A --> B")
+```
+
+## Themes
+
+Six built-in themes for `--theme` / `render_rich()`:
+
+| Theme | Colors | Description |
+|-------|--------|-------------|
+| `default` | ![#00FFFF](https://placehold.co/12x12/00FFFF/00FFFF.png) ![#FFFF00](https://placehold.co/12x12/FFFF00/FFFF00.png) ![#FFFFFF](https://placehold.co/12x12/FFFFFF/FFFFFF.png) | Cyan nodes, yellow arrows, white labels |
+| `terra` | ![#D4845A](https://placehold.co/12x12/D4845A/D4845A.png) ![#E8A87C](https://placehold.co/12x12/E8A87C/E8A87C.png) ![#F5E6D3](https://placehold.co/12x12/F5E6D3/F5E6D3.png) | Warm earth tones (browns, oranges) |
+| `neon` | ![#FF00FF](https://placehold.co/12x12/FF00FF/FF00FF.png) ![#00FF00](https://placehold.co/12x12/00FF00/00FF00.png) ![#00FFFF](https://placehold.co/12x12/00FFFF/00FFFF.png) | Magenta nodes, green arrows, cyan edges |
+| `mono` | ![#FFFFFF](https://placehold.co/12x12/FFFFFF/FFFFFF.png) ![#AAAAAA](https://placehold.co/12x12/AAAAAA/AAAAAA.png) ![#666666](https://placehold.co/12x12/666666/666666.png) | White/gray monochrome |
+| `amber` | ![#FFB000](https://placehold.co/12x12/FFB000/FFB000.png) ![#FFD080](https://placehold.co/12x12/FFD080/FFD080.png) ![#FFD580](https://placehold.co/12x12/FFD580/FFD580.png) | Amber/gold CRT-style |
+| `phosphor` | ![#33FF33](https://placehold.co/12x12/33FF33/33FF33.png) ![#66FF66](https://placehold.co/12x12/66FF66/66FF66.png) ![#AAFFAA](https://placehold.co/12x12/AAFFAA/AAFFAA.png) | Green phosphor terminal-style |
+
+## Optional extras
+
+```bash
+pip install termaid[rich]      # Colored terminal output
+pip install termaid[textual]   # Textual TUI widget
+```
+
+## Limitations
+
+- **Layout engine is approximate.** Node positioning uses a grid-based barycenter heuristic. Graphs with many cross-layer edges may still produce crossings.
+- **Manhattan-only edge routing.** Edges use A* pathfinding on a grid. Very dense graphs may have overlapping edges.
+
+## Acknowledgements
+
+Inspired by [mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) by Alexander Grooff and [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) by Lukilabs.
+
+## License
+
+MIT