ouhammmourachid / mermaid-py

Python Interface for the Popular mermaid-js Library, Simplified for Diagram Creation

Mermaid-py

this package works as an interface for the famous mermaid-js library that uses scripts to create diagrams.

Description

mermaid-py is a dynamic Python library designed to serve as a seamless interface for the renowned Mermaid library. Built upon the powerful capabilities of Python, mermaid-py empowers developers and data enthusiasts to effortlessly create stunning diagrams, flowcharts, and visualizations directly within their Python environments.

Examples

first install mermaid-py by pip install mermaid-py.

• using Mermaid and Graph classes:

import mermaid as md
from mermaid.graph import Graph

graph: Graph = Graph('example-flowchart',"""
flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]
""")
graphe: md.Mermaid = md.Mermaid(graph)
graphe # !! note this work just in notbooke that render html.

the result will be like this

• using mermaidjs magic function in a notebook first import mermaid as md:

%%mermaidjs # with --img flag in case your natebook doesn't render html
flowchart LR
    A-->B
    B-->C

the result:

• using FlowChart etc ...

from mermaid import *
from mermaid.flowchart import *

diagram = Mermaid(Flowchart(...))

diagram

• more examples on mermaid and test-mermaid

Technologies Used

• Python3
• Poetry

To contribute to mermaid-py

If you'd like to contribute to this open source project folow this steps:

1. Forke the repo and then clone it.
2. Navigate to the project directory: cd mermaid-py.
3. create a local enviroment python3 -m venv env.
4. activate the env source env/bin/activate.
5. install the dependecies poetry install.
6. happy coding :) .

List of Diagrames

• FlowChart
• Sequence Diagram
• Class Diagram
• State Diagram
• Entity Relationship Diagram
• User Journey
• Gantt
• Pie Chart
• Quadrant Chart
• Requirement Diagram
• Gitgraph (Git) Diagram 🔥
• C4 Diagram 🦺⚠️
• Mindmaps
• Timeline 🔥
• Zenuml 🔥
• Sankey 🔥
• XYChart 🔥

License

This project is licensed under the MIT License.

Contact

If you have any questions or want to get in touch, you can reach out to me at [email protected].

mermaid-py's Issues

Update supported file format for script saving to `.mmd` or `.mermaid`

We need to enhance the "mermaid-py" library by updating the supported file format for saving scripts. Currently, it only supports saving scripts as .txt files. The goal is to extend the functionality to support saving scripts in both .mmd and .mermaid formats.

This update will improve user flexibility and allow for more versatile script management within the library. The primary tasks for this update include:

• Enabling the library to save scripts in .mmd format.
• Enabling the library to save scripts in .mermaid format.

Please note that this change will require updates to the library's core functionality, documentation, and possibly tests to ensure the new file formats work seamlessly. Let's work together to implement this improvement.

to be done:

• Update the library to support saving scripts in .mmd format.
• Update the library to support saving scripts in .mermaid format.
• Update the documentation to reflect the new supported file formats.
• Add tests to ensure the new file formats work correctly.
• Update any relevant examples or usage instructions.

configure the `bumpversion` workflow with mermaid-py.

change the workflow for bumping version using bumpversion library :

• fix this https://github.com/ouhammmourachid/bumpversion-action so that it create tags and commit code and create tags automatic.
• use this cation in the bumpversion workflow .

If it is possible to use commitizen to bumpversion .

add `bgcolor` attribute to the Mermaid class .

add bgcolor like this
Background colors
Images are generated with a transparent background by default.

As mermaid diagram with light themes are barely readable on dark backgrounds (and vice-versa), it is possible to force a background color by appending the following query parameter to any /svg or /img URL: ?bgColor=. The color value is interpreted as an hexadecimal color code by default, but you can also use named colors by prefixing the value with !.

Examples:

• Add a red background using hexadecimal color: ?bgColor=FF0000
• Add a white background using named color: ?bgColor=!white

add support for style and `style classes`

add style to support the diagrams in mermaid-py.

• add style fill and stroke to flowchart.
• add style fill and stroke to erDiagram.
• add the ability to create style classes and use them on different diagrams.
• add a predefined style class ready to be used.
• add the theme support dark light.

Allow `text_to_snake_case` to be opt-out on `id_` creation

Whenever creating an instance of a flowchart Node, the id provided by the user is forced to be snake case, which this can prevent many issues, but some others may arise. For example, I'm trying to make a tree, which has some constraints that the variables must satisfy. This is the desired output:

---
title: Constraint Satisfaction Problem
---
flowchart TB
	.F_(("F"))
	.F_0.x3_(("x3"))
	valid("Valid State")
	.F_0.x3.err_-1754910954858582633("Constraint failed: F == x3")
	.F_(("F"))
	.F_1.x3_(("x3"))
	.F_1.x3.err_-1754910954858582633("Constraint failed: F == x3")
	valid("Valid State")
	.F_1.x3_ -->|3| .F_1.x3.err_-1754910954858582633
	.F_1.x3_ -->|2| .F_1.x3.err_-1754910954858582633
	.F_1.x3_ -->|1| valid
	.F_1.x3_ -->|0| .F_1.x3.err_-1754910954858582633
	.F_ -->|1| .F_1.x3_
	.F_0.x3_ -->|3| .F_0.x3.err_-1754910954858582633
	.F_0.x3_ -->|2| .F_0.x3.err_-1754910954858582633
	.F_0.x3_ -->|1| .F_0.x3.err_-1754910954858582633
	.F_0.x3_ -->|0| valid
	.F_ -->|0| .F_0.x3_

Here's a link to the mermaid live editor which contains the previous code. This is the generated diagram from the previous code, as you can see we can make us of dots (.) and dashes (-) in the node identifiers.

But instead I get this by using the library:

---
title: Constraint Satisfaction Problem
---
flowchart TB
	_f_(("F"))
	_f_0_x3_(("x3"))
	valid("Valid State")
	_f_0_x3_err__1754910954858582633("Constraint failed: F == x3")
	_f_(("F"))
	_f_1_x3_(("x3"))
	_f_1_x3_err__1754910954858582633("Constraint failed: F == x3")
	valid("Valid State")
	_f_1_x3_ -->|3| _f_1_x3_err__1754910954858582633
	_f_1_x3_ -->|2| _f_1_x3_err__1754910954858582633
	_f_1_x3_ -->|1| valid
	_f_1_x3_ -->|0| _f_1_x3_err__1754910954858582633
	_f_ -->|1| _f_1_x3_
	_f_0_x3_ -->|3| _f_0_x3_err__1754910954858582633
	_f_0_x3_ -->|2| _f_0_x3_err__1754910954858582633
	_f_0_x3_ -->|1| _f_0_x3_err__1754910954858582633
	_f_0_x3_ -->|0| valid
	_f_ -->|0| _f_0_x3_

So, I need to preserve the dots because of how I'm traversing the search space, the dots (.) allow me to detect how deep in the tree I am and the underscores (_) allow me to know the value of the branch itself which I'm currently on, but I lose all of that information because of the resulting code:

mermaid-py/mermaid/flowchart/node.py

Line 75 in 9914ed1

self.id_: str = text_to_snake_case(id_)

One way could be creating an optional boolean argument for the constructor (this way could be backwards compatible which is much preferred), or another is to modify the regex to allow dots (.) and dashes (-). This regex is found here:

mermaid-py/mermaid/_utils.py

Lines 44 to 45 in 9914ed1

	# Remove non-alphanumeric characters except underscores and replace spaces with underscores
	out: str = re.sub(r'[^a-zA-Z0-9_]', '_', text)

This regex could be modified to allow . and -, like so:

    # Remove non-alphanumeric characters except underscores, dots and dashes and replace everything else with underscores
    out: str = re.sub(r'[^a-zA-Z0-9_\.-]', '_', text)

I could open a PR, by allowing users to opt-out from the conversion made by text_to_snake_case in the constructor Node, just so the user can override this behavior (at their own risk). Or just modify the regular expression, this wouldn't be backwards compatible, but it'd work too.

Let me know what you think and what would work best for this project, I fixed it locally, but still, I think this could improve the usability of this library. Thank you for creating this library, it has helped me a lot!

Hope to hear back from you @ouhammmourachid 😄

add `>>` operation for fast creation of flow chart diagrams.

add >> operation for fast creation of flow chart diagrams with simple:

• add overide build in >> for Node .
• add appropriate unit test for this operation.

add `User Journey` diagram to supported diagram

to add the user Joerney diagram refer to the official docs on mermaid user Journey
folow this steps

• add actor classs .
• add Task class.
• add section class.
• add the main UserJourny class.

add support of `requirements diagram` to mermaid-py.

add support for the requirement diagram with mermaid-py
use the official mermaid-docs to add the necessary class
Requirement Diagram
here is the steps to folows :

• add requiremet class with its propre unittest.
• add element class with its propre unittest.
• add Link classs with its propre unittest.
• add RequirementDigram class with its propre unittest.

remove print statment in the `piechart` diagram

remove the print statment from the code in this two line of code so that when you create a diagram we don't get any mesage
https://github.com/ouhammmourachid/mermaid-py/blob/main/mermaid/piechart.py#L16
https://github.com/ouhammmourachid/mermaid-py/blob/main/mermaid/piechart.py#L17

here is helpful screen shots

add `pie` diagram .

add the pie digram to list of supported digrams:

• add piechart diagram.
• add unit test for this diagram.
• create a new realease.

use this a refrence

Use pre-commit actions for linter

https://github.com/ouhammmourachid/mermaid-py/blob/diagram%2Fclassdiagram/.github%2Fworkflows%2Fmake-list.yml#L15-L20

you should change the type id to be of type `str` instead of `int`

you should change the type id to be of type str instead of int becouse is may be 1.1.1

Move the Mermaid class from `mermaid/_main.py` to `mermaid/__init__.py` .

add documentation for the existing code .

add documentation for the diagram that allready writen.
list of models:

• flowchart.
• entity realtionship diagram.
• graphe.
• utils.

create a custom cell magic in Jupyter Notebook for mermaid

create a custom cell magic in jupyter Notebook that execute mermaid scripts and create diagram

base on this screen shout build this custom cell magic

managinng documentation using `mkdocs` .

in order to consider this item do you should:

• add mkdocs and mkdocstrings[python] annd mkdocs-material as dev dependecy.
• create the started for the docs .
• chnage the name .
• generate html in the site folder .
• using Github pages deploy the docs .

add `--img` option to the mermaidjs magic function

add --img option to the mermaidjs magic function like in this screen shoots

add LinkShape and LinkHead enum to flowchart

support `Timeline` diagram in mermaid-py

use `Nextra` in mermaid-py docs