Metadata-Version: 2.5
Name: mermaiden
Version: 3.1.0
Summary: Typed deterministic Mermaid source generation for Python.
Project-URL: Repository, https://github.com/szpak-dev/mermaiden
Project-URL: Issues, https://github.com/szpak-dev/mermaiden/issues
Author: 9orky
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.12
Requires-Dist: wireup>=2.12.0
Provides-Extra: dev
Requires-Dist: build>=1.3; extra == 'dev'
Requires-Dist: import-linter>=2.11; extra == 'dev'
Requires-Dist: jsonschema>=4.25; extra == 'dev'
Requires-Dist: packaging>=25; extra == 'dev'
Requires-Dist: pyright>=1.1.403; extra == 'dev'
Requires-Dist: pytest>=9; extra == 'dev'
Requires-Dist: pyyaml>=6; extra == 'dev'
Requires-Dist: ruff>=0.14; extra == 'dev'
Requires-Dist: twine>=7; extra == 'dev'
Description-Content-Type: text/markdown

# mermaiden

`mermaiden` generates deterministic Mermaid source from typed Python diagram models. It supports the Mermaid syntax families registered by the package and validates each diagram before rendering its text.

The package produces Mermaid text only. Render it with Mermaid in a browser, Markdown viewer, or your own CLI workflow.

## Installation

Python 3.12 or later is required.

```sh
pip install mermaiden
```

## Quick start

```python
from mermaiden.application import Application

application = Application.create()
diagrams = application.available_diagrams()
print(diagrams)
```

`Application.available_diagrams()` returns the supported diagram catalog. `Application.diagram_info(diagram_id)` returns the typed diagram API for an individual syntax. CLI workflows are available through `python -m mermaiden.cli`.

## Application API

`Application` is the boundary for API and persistence adapters. Create a diagram by Mermaid syntax id, apply a named domain command, and persist the JSON-safe snapshot returned by the application.

```python
from mermaiden.application import Application, DiagramCommand

application = Application.create()
diagram = application.create_diagram("sequenceDiagram")
application.apply(diagram, DiagramCommand("add_participant", {"id": "api", "label": "API"}))

payload = application.snapshot(diagram).to_dict()
restored = application.restore(payload)
source = application.render(restored)
```

Snapshots have a versioned envelope and may be stored as JSON. `Application.restore()` validates restored state before returning it. Command argument values use the diagram operation names; JSON string values are accepted for enum arguments.

The caller can discover the REST contract without maintaining a manifest. `diagram_description()` returns JSON Schema for the diagram's elements, relations, annotations, and commands. `command_payload()` returns the generated Pydantic request model for one command.

```python
description = application.diagram_description("sequenceDiagram")
payload_type = application.command_payload("sequenceDiagram", "add_participant")
payload = payload_type.model_validate({"id": "api", "kind": "control"})
```

## Development

The repository uses a single host-mode CI target:

```sh
make ci
```

It installs the development dependencies, runs linting, type checks, tests, compatibility validation, Mermaid CLI rendering, and wheel validation. To open the locally generated diagram preview, run:

```sh
make diagrams-test
```

## Release

Releases are versioned by annotated `vX.Y.Z` tags. After `make ci` passes, create and push the tag, then publish the GitHub release:

```sh
git tag -a v2.0.0 -m "v2.0.0"
git push origin v2.0.0
gh release create v2.0.0 --verify-tag --generate-notes --title v2.0.0
```
