Skip to main content

MerGram

Programmatically generate Mermaid diagrams and charts using Python.

Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public. Python version badge license release Ruff

MerGram currently supports constructing Mermaid flowcharts, with plans to expand support for additional diagram and chart types in future releases.

Features

  • Build Mermaid flowcharts using Python classes
  • Support for nodes, links, and subgraphs, and style assignments
  • Export diagrams to Mermaid .mmd or .mermaid files
  • Optional integration with networkx for graph conversion

What's New in

v0.3.0

  • Style class that can be used to add style ... lines to flowcharts
  • Fixes to style-related outputs for nodes

v0.2.0

  • Flowchart.to_markdown function to get a string representation of the flowchart embedded in a Markdown Mermaid code block.
  • Flowchart.to_html function to get a string representation of the flowchart embedded in HTML.

Installation

pip install mergram

To enable networkx integration:

pip install mergram[networkx]

Usage

Basic Flowchart

from mergram.flowchart import Flowchart, Node, Link

fc = Flowchart("Example Flowchart")
a = Node("A", label="Start")
b = Node("B", label="End", shape='circle')
fc += a
fc += b
fc += Link(a, b, text="to end")

print(fc)

Generates the following mermaid diagram code:

---
title: Example Flowchart
---
flowchart TB
    A@{ shape: rect, label: Start }
    B@{ shape: circle, label: End }
    A-->|to end|B
    style A fill:#fff, stroke:#000, stroke-width:2px, color:#000
    style B fill:#fff, stroke:#000, stroke-width:2px, color:#000

That looks like:

---
 title: Example Flowchart
---
flowchart TB
    A@{ shape: rect, label: Start }
    B@{ shape: circle, label: End }
    A-->|to end|B
    style A fill:#fff, stroke:#000, stroke-width:2px, color:#000
    style B fill:#fff, stroke:#000, stroke-width:2px, color:#000

From NetworkX

import networkx as nx
from mergram.flowchart import Flowchart

G = nx.DiGraph()
G.add_edge("A", "B", label="to B")
G.add_edge("B", "A", label="to A")
fc = Flowchart("From NetworkX", orientation='LR')
fc.from_networkx(G)
print(fc)
---
title: From NetworkX
---
flowchart LR
    B@{ shape: rect, label: B }
    A@{ shape: rect, label: A }
    A-->|to B|B
    B-->|to A|A
    style A fill:#fff, stroke:#000, stroke-width:2px, color:#000
    style B fill:#fff, stroke:#000, stroke-width:2px, color:#000
---
 title: From NetworkX
---
flowchart LR
    B@{ shape: rect, label: B }
    A@{ shape: rect, label: A }
    A-->|to B|B
    B-->|to A|A
    style A fill:#fff, stroke:#000, stroke-width:2px, color:#000
    style B fill:#fff, stroke:#000, stroke-width:2px, color:#000

Export to File

fc.write("diagram.mmd")

Optional Dependencies

  • networkx: For converting existing graphs to Mermaid flowcharts.

License

MIT License

Contributing

Contributions are welcome! Please open issues or pull requests.

Metadata

Release files for mergram 0.3.0

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

Source distribution (sdist)

Source distribution for mergram 0.3.0
File Size Uploaded Provenance Actions
mergram-0.3.0.tar.gz 7.3 kB With provenance Details for mergram-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mergram 0.3.0
File Interpreter ABI Platform Actions
mergram-0.3.0-py3-none-any.whl Python 3 none any Details for mergram-0.3.0-py3-none-any.whl

Total release size: 14.7 kB

Release files / mergram-0.3.0.tar.gz

Download URL mergram-0.3.0.tar.gz
Size 7.3 kB
Tags Source
SHA-256 checksum
How to use checksums
7594fb3d4f98e3c52ab4fe34f87f3d0c724bb574d3d5cbc4702a91d6cf81c6a4
BLAKE2b-256 checksum
How to use checksums
1581606d6d8de19d01adf2a6bd4cd3d9055014e12a7c4dc5be38ea2dee835b5d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

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 Jul 11, 2025.

Transparency log

Release files / mergram-0.3.0-py3-none-any.whl

Download URL mergram-0.3.0-py3-none-any.whl
Size 7.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4193f57ccc67c921b40162a029f0e8c39e7c9b801b6be0f20381900d446e925c
BLAKE2b-256 checksum
How to use checksums
1985035b26d33bd15e5647867b0d9ae2187aa6b05d7b87e2314ac565cbd0266b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.9

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 Jul 11, 2025.

Transparency log

Security for mergram 0.3.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

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mergram-0.3.0.tar.gz

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 Jul 11, 2025.

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