Skip to main content

Merman For Python

PyPI Python License: MIT License: Apache-2.0

Parse, analyze, lay out, and render Mermaid diagrams from Python without a browser or JavaScript runtime. The package ships Merman's Rust engine and exposes it through UniFFI.

This guide documents Merman and Python package version 0.10.0. Check the host installation guide for verified versions and channel availability. Use the stable upgrade guide when migrating from 0.9.3 or a 0.10.0 alpha.

Python's stable PEP 440 version is 0.10.0, matching native Merman 0.10.0. It uses direct UniFFI binding API 7, Options JSON schema 3, facts schema 3, and theme execution evidence schema 2, independently of the C ABI and text-measurement protocol. Install the Python wrapper and native library as one wheel rather than mixing releases.

Install

Install the exact version documented here:

python -m pip install --only-binary=:all: 'merman==0.10.0'

The package supports Python >=3.9 through the UniFFI/ctypes transport with five native wheels:

Rust target Wheel platform
aarch64-apple-darwin macosx_11_0_arm64
x86_64-apple-darwin macosx_10_13_x86_64
aarch64-unknown-linux-gnu manylinux_2_28_aarch64
x86_64-unknown-linux-gnu manylinux_2_28_x86_64
x86_64-pc-windows-msvc win_amd64

Linux wheels build, undergo auditwheel repair, and run installed consumers in pinned official manylinux_2_28 images on their native CPU. They require glibc 2.28+; musl Linux and Windows ARM64 are outside this matrix. Normal wheel installation needs no Rust compiler. There is no qualified source distribution; use the repository's explicit source helper when building from the matching 0.10.0 source revision. Build the wrapper and native library together to preserve the binding contract.

For the previous stable 0.9.3 installation, use the tagged guide. That release uses Options JSON schema 2, omits math, and has three wheels, including a manylinux_2_35_x86_64 wheel. Its binaries do not provide the theme API documented here.

Render A Diagram

import merman

client = merman.Merman()

source = "flowchart TD\nA[Hello] --> B[World]"
svg = client.render_svg(source, None)
print(svg[:4])  # <svg

The same one-shot facade exposes render_png, render_jpeg, render_pdf, render_ascii, parse_json, layout_json, analyze_json, validate, theme and lint metadata, ASCII support grades, and the complete diagram-family capability catalog. The ordinary wheel supports SVG including math, Cytoscape and ELK layout, ASCII, semantic/layout operations, analysis, validation, and document analysis. PNG, JPEG, and PDF methods remain available for custom current-contract libraries; the ordinary wheel raises MermanError.Binding with MISSING_CAPABILITY and the exact codec capability ID. MermanOperationRequestV4 plus client.execute() is the generic, descriptor-owned form of those named methods and returns binary-safe data with media type and typed operation metadata. Generic options belong in MermanOperationRequestV4.options_json; execute() has no separate options argument. The binding API is 7; MermanOperationRequestV4 retains its record name and carries an optional MermanOperationControl for cooperative cancellation and relative deadlines. ASCII capability records expose layout/width/encoding/fallback admission arrays, and ASCII output plans use schema 3 with explicit encoding, requested/effective layouts, and Compact-attempt information.

Ordinary interactive rendering handles formulas:

svg = client.render_svg('flowchart TD\nA["$$x^2$$"] --> B[Done]', None)

The constrained resource policy still excludes the native math backend. A constrained engine can render ordinary text diagrams and rejects formula input with the typed missing math capability error. Choose resource policy for the input's trust level; installing a math-capable wheel does not relax resource admission.

Reuse An Engine

Construct MermanEngine directly when calls share baseline options:

engine = merman.MermanEngine(
    options_json='{"svg":{"pipeline":"readable"}}',
    services=None,
)
svg = engine.render_svg(source, '{"svg":{"diagram_id":"preview"}}')
facts = engine.analyze_document_facts_json(
    "```mermaid\n" + source + "\n```",
    "file:///workspace/README.md",
    None,
)
engine.close()

options_json is optional and follows Options JSON schema 3. Invalid options and engine failures raise typed MermanError variants. Reusable request options deeply merge over the construction baseline for one operation without mutating it. They cannot change the constructor-owned runtime_policy. MermanError.Binding.kind distinguishes UNKNOWN_OPERATION from MISSING_CAPABILITY; only the latter carries a non-null, descriptor-owned capability_id.

Release wheels use deterministic runtime state and do not bundle native clock, time-zone, or random adapters. A custom source build may enable the atomic native-runtime feature and then select {"runtime_policy":"native"}. The default wheel raises the generated unsupported-operation error when native policy is requested, and runtime discovery reports concrete adapter IDs only when they are present.

Choose a profile from the shared resource decision table, then use the generated builder:

from merman import ResourceOptionsBuilder, ResourceOverrideId, ResourceProfile

resource_options = (
    ResourceOptionsBuilder()
    .profile(ResourceProfile.CONSTRAINED)
    .limit(ResourceOverrideId.MAX_SOURCE_BYTES, 4 * 1024 * 1024)
    .build()
    .to_options_json()
)
svg = client.render_svg(source, resource_options)

Use CONSTRAINED for untrusted, public, or multi-tenant input; INTERACTIVE is for cooperative local editing. Leave the profile unset when a reusable request must inherit its constructor ceiling. The native CLI's default is intentionally separate (trusted-native).

Call client.runtime_catalog_json() to inspect the loaded runtime catalog and exact resource profile values instead of duplicating limits in application code. Decode client.theme_catalog_json() for the open-ended versioned theme preset and artifact-availability catalog. merman.get_runtime_catalog(client) strictly validates its flat schema 1 artifact facts, package identity, transport API, supported options/payload schema IDs, named metadata IDs, sorted stable IDs, and local output/operation relations as one atomic response. New stable IDs remain forward compatible. This direct binding API version is 7 and is independent from native C ABI and the text-measurement protocol version.

API 7 preserves theme-authoring diagnostics and exposes requested_layout_profile and compact_attempted in the schema-3 ASCII output plan. The effective layout_profile remains Canonical or Compact. When upgrading from API 6, replace binding_api_version_v6() with binding_api_version_v7() and regenerate the package and native library together; historical 0.8.0a6 wheels retain API 6.

Diagnostics use schema 1 and parser facts use schema 3, independently of UniFFI binding API 7. Other facts versions are rejected at the boundary; consumers of the removed TextScan shape and Flowchart-only rich graph must migrate to generic parser-backed items and explicit unavailable bodies. Every diagram now requires appearance with known or unknown state; known declarations carry source provenance and byte spans. See the source appearance migration.

Version 0.10.0a2 uses facts schema 3 and theme execution evidence schema 2; 0.10.0a1 retains facts schema 2 and theme execution evidence schema 1. UniFFI binding API 7 and Options JSON schema 3 are unchanged between these alphas, so upgrade the complete wheel and update JSON consumers together even though the transport version is unchanged.

For generic operations, construct MermanOperationControl(timeout_ms=...), retain it in the host, and put it in MermanOperationRequestV4.control. Calling cancel() from another thread requests cooperative termination. MermanError.Binding.cancellation reports the reason and observed phase; resource failures continue to use the separate resource field. Opaque callbacks may complete before the next checkpoint, so hard preemption requires a worker or process boundary.

Diagram Themes

Use client.theme_catalog_json() to discover 11 design groups with 14 concrete presets, including paper-cut, carbon-copy, and pop-art. Select a preset through schema-3 options:

import json

catalog = json.loads(client.theme_catalog_json())
print([(preset["id"], preset["supported_appearances"]) for preset in catalog["presets"]])
pie_source = 'pie\n"A":35\n"B":65'
themed_svg = client.render_svg(pie_source, '{"version":3,"theme":{"preset":"ghibli"}}')

For a reusable engine, omit theme to inherit its selection, use theme: null to clear it, or supply a complete selection or recipe to replace it.

Each schema-1 catalog entry groups a design's supported_appearances, default_appearance, and appearances. Read swatches, family_designs, application_notes, qualified_cells, and the exact concrete_preset_id from the relevant appearance entry. Select Editor Dark using {"theme":{"preset":"editor","appearance":"dark"}}. Follow-app/editor is host policy; resolve it to light or dark before rendering. Editor, Gruvbox, and Ayu provide both appearances; omitted appearance uses the declared default, and an unsupported explicit appearance fails.

client.execute() already carries the complete authoring workflow through MermanOperationRequestV4. export-theme-preset-json takes the plain editor ID and returns the complete ThemeRecipeV1; shared values live in design, with local exceptions in design.appearances and a design.default_appearance. Keep that document for saving and editing. materialize-theme-json accepts schema-1 action: "inspect" with recipe to validate every appearance, or action: "materialize" with an optional concrete appearance to obtain its spec. Save the complete recipe with json.dumps(recipe, indent=2), edit its design values, and reload it with json.loads(...), preserving schema_version and kind. Use json.dumps({"theme": {"recipe": recipe, "appearance": "dark"}}) for render options. The authoring example shows the exact MermanOperationRequestV4 calls, complete-pair export, inspection, editing, and reuse through one-shot and independent clients.

Built-in presets are alpha, with empty public qualification cells. Catalog availability and family design scope do not certify the result for every diagram or output target. Flowchart glow and shadow effects support the documented shapes in Classic and Neo. Other families retain their own look and output restrictions; selecting a preset does not change the look or layout engine. Fonts must be supplied by the host and final SVG viewer; font-stack names do not embed fonts, and caller-provided font resources in recipes are rejected. The wheel does not expose the native C/WASI memory-font constructor. See the theme guide for version-1 recipes, support discovery, and portability policy.

Text Measurement

Merman owns a deterministic, font-agnostic text measurer by default. Keep it for servers, CLIs, CI, and documentation builds.

GUI, browser automation, and WebView hosts can implement MermanTextMeasurer, start with MermanEngineServices(), call with_text_measurer(...), and pass the returned immutable bundle to MermanEngine(options_json, services). The original bundle remains unchanged, and the callback is immutable for that engine; construct a different engine to change or remove it. Text-measurement protocol 1 exposes 23 exact operations (0..22), and each handled MermanTextMeasureResult must use the MermanTextMeasurementResultKind required by request.operation. Return None for operations that cannot be measured synchronously and faithfully. Invalid results and Python exceptions delivered through UniFFI's generated callback trampoline fall back for that operation; Merman does not claim to catch arbitrary foreign unwinds outside that generated boundary.

Use a real font API from the surface that displays the SVG rather than estimating width from character counts. Keep callbacks fast and do not re-enter the same reusable engine while its callback is active. Callback-free engines allow concurrent operations; callback engines serialize admission and report typed BUSY to a competing caller, while same-engine callback reentry reports REENTRANT_CALL. The host measurement guide documents every operation and fallback; the repository's Python smoke example demonstrates one representative callback path while owner-local tests enforce the complete protocol.

The generated callback is measure(self, request), not measure_text. One-shot and reusable operations accept request-local options_json; reusable values deeply merge over the construction baseline for that call. The linked smoke example remains the source-owner callback and theme reference. Final wheel qualification uses the standalone installed consumer, which can run outside the repository.

Output And Platform Limits

  • SVG may contain styles, markers, and foreignObject HTML labels; the final viewer must support the selected SVG pipeline.
  • All APIs are synchronous. Run expensive rendering outside a GUI event loop.
  • Wheels bundle a platform-specific native library and are not portable across operating systems or CPU families.
  • Merman targets structural and semantic Mermaid compatibility; browser font rendering and DOM measurements can still differ unless the host provides matching metrics.

Query diagram_family_capabilities() and ascii_capabilities() at runtime instead of assuming that every build profile or output format supports every family.

Custom artifacts with binary exports expose MermanOutputPlan as an open record. Switch on kind, inspect raster, pdf_filter_images, or ascii for known plans, and retain raw_json so a newer native library can report a future plan without forcing Python into a closed enum. The ASCII plan records the selected projection, encoding, emitted dimensions, and viewport fallback outcome.

Local Development

The Python package build backend supports Python 3.9 or newer. Its isolated environment selects setuptools>=82.0.1,<83 on Python 3.9 and setuptools>=84.2.1 on Python 3.10 or newer; Setuptools 83 dropped Python 3.9 support. These build-only requirements do not change the wheel's Python >=3.9 runtime requirement.

Build the descriptor-owned native library, regenerate bindings, assemble a wheel, install it into an isolated environment, and run the smoke test with:

python3 scripts/build-python-uniffi-wheel.py --run-smoke

The helper resolves the python-uniffi-native artifact recipe and chooses the platform library name (.dylib, .so, or .dll). The bundled release library excludes binding-generation; only source generation enables that feature. It also embeds the checked-in Rust dependency license report for the selected target rather than the union of every published wheel target. For manual binding generation, follow the UniFFI maintainer guide.

--run-smoke installs the built wheel without dependency resolution into a temporary environment and executes the standalone consumer with isolated imports outside the checkout. It checks wrapper/library identity, actual formula glyph geometry, constrained-policy rejection, and absent codecs. A local Linux helper build is a host wheel; only the release owner's pinned manylinux build/repair/execution qualifies the advertised glibc baseline. The owner separately repeats the installed-wheel consumer on Python 3.9 and 3.14 for each target.

Documentation And Releases

PyPI is the supported registry channel for the Python package. Use the host installation guide to select a verified PyPI version or GitHub Release wheel; this README does not imply support for platforms without a listed wheel.

License And Notices

This package is available under MIT or Apache-2.0. The installed distribution carries the exact release license, notices, and upstream texts under its .dist-info/licenses/ directory. Online copies live in the repository's Python package directory.

Metadata

Release files for merman 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for merman 0.10.0
File Actions
merman-0.10.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details for merman-0.10.0-py3-none-win_amd64.whl
merman-0.10.0-py3-none-manylinux_2_28_x86_64.whl Python 3 none Linux glibc 2.28+ x86-64 Details for merman-0.10.0-py3-none-manylinux_2_28_x86_64.whl
merman-0.10.0-py3-none-manylinux_2_28_aarch64.whl Python 3 none Linux glibc 2.28+ ARM64 Details for merman-0.10.0-py3-none-manylinux_2_28_aarch64.whl
merman-0.10.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details for merman-0.10.0-py3-none-macosx_11_0_arm64.whl
merman-0.10.0-py3-none-macosx_10_13_x86_64.whl Python 3 none macOS 10.13+ x86-64 Details for merman-0.10.0-py3-none-macosx_10_13_x86_64.whl

Total release size: 63.0 MB

Release files / merman-0.10.0-py3-none-win_amd64.whl

Download URL merman-0.10.0-py3-none-win_amd64.whl
Size 13.4 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
2b535df229ec282c93ae5f3a626429a610398a978c2b361ae0e63d3668233fbf
BLAKE2b-256 checksum
How to use checksums
ed95f9aab38aeed83ff05f64b09633209e7b5674f61386f4c2080f9b14c9d06d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / merman-0.10.0-py3-none-manylinux_2_28_x86_64.whl

Download URL merman-0.10.0-py3-none-manylinux_2_28_x86_64.whl
Size 13.1 MB
Tags Linux glibc 2.28+ x86-64 Python 3
SHA-256 checksum
How to use checksums
242b6a490bfefc2db9e85948fe16dea995406a57ede051b3da72cead01d67675
BLAKE2b-256 checksum
How to use checksums
d5c58c22ab8a4fc2cec7f332841a4e1f7b89b6546604726f03707fb18cdc15fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / merman-0.10.0-py3-none-manylinux_2_28_aarch64.whl

Download URL merman-0.10.0-py3-none-manylinux_2_28_aarch64.whl
Size 12.0 MB
Tags Linux glibc 2.28+ ARM64 Python 3
SHA-256 checksum
How to use checksums
1ae0b017d07df98023da19cccfd41101b0e2125895d718aaf26ae02f2cfc927f
BLAKE2b-256 checksum
How to use checksums
8e4c22492c4fd29e7de8c207626c894dac18f1e702904297c492938ac3f6889e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / merman-0.10.0-py3-none-macosx_11_0_arm64.whl

Download URL merman-0.10.0-py3-none-macosx_11_0_arm64.whl
Size 11.9 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
d2003ffc077dfaea6ea2d4800233298d3d5d6b5e64bcf0da67bb64cd2286d7d0
BLAKE2b-256 checksum
How to use checksums
fe3e5fa7dcb4a80c10a200a2a19b4403b5363bf91c8f86d04dae680e346fbd0d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / merman-0.10.0-py3-none-macosx_10_13_x86_64.whl

Download URL merman-0.10.0-py3-none-macosx_10_13_x86_64.whl
Size 12.5 MB
Tags Python 3 macOS 10.13+ x86-64
SHA-256 checksum
How to use checksums
bc8c95968c28b8ec2fdadd81ae95d0ed8ab9ba3fcf9c07cb60135c9fda0c2e61
BLAKE2b-256 checksum
How to use checksums
6ef65d90284474643539dea76ec12b0d314dbc10bde2e6b4f35da271fcb268b0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for merman 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for merman-0.10.0-py3-none-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page