Build Mermaid diagrams from typed, immutable Python objects.
modwire-mermaid validates a diagram's structure and compiles it to deterministic Mermaid text
behind one class-based API. It performs no filesystem, browser, CLI, or image-rendering work.
Compilation is package-native. It does not depend on Node.js or mermaid-py; consumers may pass the
generated source to their preferred Mermaid renderer or validation binary.
Mermaid is a text-based diagramming language. A short definition such as:
flowchart LR
contract[Typed Python contract] --> compiler[modwire-mermaid]
compiler --> source[Mermaid source]
source --> renderer[Mermaid renderer]
can be rendered as a diagram by Mermaid-aware tools. Because the source is plain text, diagrams are easy to review in version control, generate in tests, embed in Markdown, and render independently in a browser or CI pipeline.
This package owns the first two steps: typed Python contracts and Mermaid source generation. Mermaid itself—or a service or application that embeds it—owns visual rendering.
modwire-mermaid requires Python 3.12 or newer.
pip install modwire-mermaidCreate a diagram with one of the feature builders, then compile it with the standard façade:
from modwire_mermaid.composition import ModwireMermaidFactory
from modwire_mermaid.timeline.diagram import ModwireTimelineBuilder
diagram = (
ModwireTimelineBuilder.create("Release history")
.section("2026")
.period("Q1", "Private beta")
.period("Q2", "Public release", "Documentation")
.build()
)
source = ModwireMermaidFactory.standard().compile(diagram)
print(source)The result is plain Mermaid source:
---
config:
timeline:
disableMulticolor: false
---
timeline LR
title Release history
section 2026
Q1 : Private beta
Q2 : Public release : Documentation
Put the result inside a fenced mermaid block in supported Markdown, send it to the
Mermaid Live Editor, or pass it to the renderer used by your application.
Rendering is deliberately outside this package, so server-side code can generate diagrams without
shipping a browser or Node.js runtime.
The supported imports below name each API's defining module; package initializers do not aggregate them.
| Import path | Purpose | Primary API |
|---|---|---|
modwire_mermaid._version.__version__ |
Installed distribution version. | — |
modwire_mermaid.compiler.DiagramCompiler |
Compile one exact diagram type into deterministic Mermaid source. | compile(diagram: 'DiagramT') -> 'str' |
modwire_mermaid.composition.ModwireMermaidFactory |
Build the standard Mermaid façade with every bundled diagram compiler. | standard_registry() -> modwire_mermaid.registry.CompilerRegistrystandard() -> modwire_mermaid.facade.ModwireMermaid |
modwire_mermaid.contracts.CompilerRegistrationError |
Report an invalid compiler registry operation. | — |
modwire_mermaid.contracts.DiagramBuildError |
Report invalid ordering or missing context in a diagram builder. | — |
modwire_mermaid.contracts.DiagramBuilder |
Build one validated diagram without exposing mutable intermediate state. | build() -> +BuiltDiagramT |
modwire_mermaid.contracts.DiagramCompilationError |
Wrap a selected compiler failure with stable diagram context. | — |
modwire_mermaid.contracts.DuplicateCompilerError |
Report an attempt to register the same exact diagram type twice. | — |
modwire_mermaid.contracts.MermaidDiagram |
Structural contract accepted by compiler registries and the façade. | — |
modwire_mermaid.contracts.ModwireBaseDiagram |
Recommended Pydantic base for built-in and external diagrams. | — |
modwire_mermaid.contracts.ModwireDiagramContract |
Strict frozen Pydantic base for all bundled semantic contracts. | — |
modwire_mermaid.contracts.ModwireMermaidError |
Base class for operational modwire-mermaid failures. | — |
modwire_mermaid.contracts.UnsupportedDiagramError |
Report a diagram whose exact type has no registered compiler. | — |
modwire_mermaid.diagrams.Diagram |
Discriminated union of every bundled diagram contract. | — |
modwire_mermaid.diagrams.DiagramAdapter |
Validate, serialize, and publish schemas for bundled diagrams. | — |
modwire_mermaid.facade.ModwireMermaid |
Compile validated diagram contracts into deterministic Mermaid source. | compile(diagram: modwire_mermaid.contracts.MermaidDiagram) -> str |
modwire_mermaid.registry.CompilerRegistry |
Immutable exact-type compiler registry with explicit conflict semantics. | empty() -> 'CompilerRegistry'with_compiler(compiler: 'DiagramCompiler[DiagramT]') -> 'CompilerRegistry'without(diagram_type: 'type[MermaidDiagram]') -> 'CompilerRegistry'replace(compiler: 'DiagramCompiler[DiagramT]') -> 'CompilerRegistry'merge(other: 'CompilerRegistry') -> 'CompilerRegistry'compile(diagram: 'MermaidDiagram') -> 'str' |
modwire_mermaid.schema.DIAGRAM_SCHEMA_VERSION |
Version of the canonical bundled-diagram JSON Schema. | — |
modwire_mermaid.schema.diagram_json_schema |
Return the canonical versioned schema for every bundled diagram. | — |
Source: compile_timeline.py. This file is executed by the test suite.
from modwire_mermaid.composition import ModwireMermaidFactory
from modwire_mermaid.timeline.diagram import ModwireTimelineBuilder
diagram = (
ModwireTimelineBuilder.create("Release history")
.section("2026")
.period("Q1", "Private beta")
.period("Q2", "Public release", "Documentation")
.build()
)
source = ModwireMermaidFactory.standard().compile(diagram)- Architecture
- Class diagram
- Event modeling
- File tree
- Flowchart
- Mindmap
- Sequence diagram
- State diagram
- Swimlanes
- Timeline
- User journey
Built-in contracts inherit ModwireBaseDiagram; extensions may use that strict Pydantic base or satisfy
the public structural compiler contract. Diagram kinds are discriminated and serializable through
DiagramAdapter. Required semantic roots stay explicit, while immutable empty tuples and ordinary
Mermaid configuration use typed defaults. Omitted optional text and references use typed, non-null
empty-string defaults; explicit None is rejected.
- Typed, frozen Pydantic contracts reject invalid diagram structure before compilation.
- Identical contracts produce identical Mermaid text, making snapshot tests and source diffs stable.
- The standard factory supports every diagram type listed above through one
compile()method. - The package generates text only; it does not render SVG/PNG, invoke Mermaid CLI, or write files.
- Mermaid parser and renderer compatibility must be checked by the consuming application.
- The repository's executable compatibility corpus checks all diagram roots with Mermaid 11.16.0; experimental swimlanes establish that minimum supported Mermaid version.
- Compiler registries are immutable; duplicates fail and replacement is always explicit.
DIAGRAM_SCHEMA_VERSION is "2". Import both schema APIs from modwire_mermaid.schema; use
diagram_json_schema() for the canonical bundled-diagram schema,
or consume the packaged modwire_mermaid/schemas/v2/diagram.schema.json artifact. Schema drift is checked in CI.
Implement DiagramCompiler[YourDiagram], then compose it without mutating the standard registry:
from modwire_mermaid.composition import ModwireMermaidFactory
from modwire_mermaid.facade import ModwireMermaid
registry = ModwireMermaidFactory.standard_registry().with_compiler(MyCompiler())
source = ModwireMermaid(registry).compile(MyDiagram(...))Exact diagram-type dispatch is intentional. Use replace() when overriding an existing compiler.
See the v2 migration guide for the breaking API and model changes.
Run uv sync --all-groups and make verify. Releases use strict SemVer tags and PyPI Trusted
Publishing configured for repository modwire/modwire-mermaid, workflow release.yml, and environment
pypi. Create and push the tag before publishing its GitHub Release; that release uses the shared
Python release workflow from modwire/modwire-architecture, attaches the verified distributions, and
then publishes the same files to PyPI.
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
gh release create vX.Y.Z --verify-tag --generate-notes --title vX.Y.Z