merrimanind / drawpyo Goto Github PK

View Code? Open in Web Editor NEW

146.0 1.0 5.0 4.04 MB

A Python library for programmatically generating Draw.io charts.

Home Page: https://pypi.org/project/drawpyo/

License: MIT License

Python 100.00%

diagrams diagramsnet drawio drawio-tools python

drawpyo's Introduction

drawpyo

Drawpyo is a Python library for programmatically generating Diagrams.net/Draw.io charts. It enables creating a diagram object, placing and styling objects, then writing the object to a file.

History/Justification

I love Draw.io! Compared to expensive and heavy commercial options like Visio and Miro, Draw.io's free and lightweight app allows wider and more universal distribution of diagrams. Because the files are stored in plaintext they can be versioned alongside code in a repository as documentation. The XML-based file format makes these diagrams semi-portable, and could easily be ported to other applications if Draw.io ever failed you. For these reason, I think it's one of the best options for documentation diagrams.

When I had a need to generate heirarchical tree diagrams of requirement structures I was surprised to find there wasn't even a single existing Python library for working with these files. I took the project home and spent a weekend building the initial functionality. I've been adding functionality, robustness, and documentation intermittently since.

Full Documentation

Available here!

https://merrimanind.github.io/drawpyo/

Basic Usage

The basic mode of interacting with drawpyo is to manually create, style, and place objects just like you would using the Draw.io UI. There are a number of ways to style objects and you can write your own functionality for automatically handling style or placement.

Make a new file

import drawpyo
file = drawpyo.File()
file.file_path = r"C:\drawpyo"
file.file_name = "Test Generated Edges.drawio"
# Add a page
page = drawpyo.Page(file=file)

Add an object

item = drawpyo.diagram.Object(page=page, value="new object")
item.position = (0, 0)

Create an object from the base style libraries available in the Draw.io UI

item_from_lib = drawpyo.diagram.object_from_library(
    page=page,
    library="general",
    obj_name="process",
    value="New Process",
    )

Style an object from a string

item_from_stylestr = drawpyo.diagram.Object(page=page)
item_from_stylestr.apply_style_string("rounded=1;whiteSpace=wrap;html=1;fillColor=#6a00ff;fontColor=#ffffff;strokeColor=#000000;gradientColor=#FF33FF;strokeWidth=4;")

Write the file

file.write()

Usage with a diagram type

There is also functionality available in drawpyo that extends what can be done in Draw.io's app! These diagram types allow for easy and automatic creation of specific diagrams.

The only diagram type that's released is the tree diagram. Varying level of conceptual work has been started for:

Automatic class/object/inheritance diagrams of a python module
Flowcharts
Process diagrams

Working with TreeDiagrams

Create a new tree diagram:

from drawpyo.diagram_types import TreeDiagram, NodeObject

tree = TreeDiagram(
    file_path = path.join(path.expanduser('~'), "Test Drawpyo Charts"),
    file_name = "Coffee Grinders.drawio",
    direction = "down",
    link_style = "orthogonal",
    )

The direction property sets which way the leaf nodes grow from the root: up, down, left, or right. The link_style can be orthogonal, straight, or curved.

Create some NodeObjects:

# Top object
grinders = NodeObject(tree=tree, value="Appliances for Grinding Coffee", base_style="rounded rectangle")

# Main categories
blade_grinders = NodeObject(tree=tree, value="Blade Grinders", parent=grinders)
burr_grinders = NodeObject(tree=tree, value="Burr Grinders", parent=grinders)
blunt_objects = NodeObject(tree=tree, value="Blunt Objects", parent=grinders)

Note that the base_style was manually declared for the first object. But NodeObjects will default to "rounded rectangle" so it's not necessary for every one. Any NodeObject can be a parent, so you can keep adding objects down the tree:

# Other
elec_blade = NodeObject(tree=tree, value="Electric Blade Grinder", parent=blade_grinders)
mnp = NodeObject(tree=tree, value="Mortar and Pestle", parent=blunt_objects)

# Conical Burrs
conical = NodeObject(tree=tree, value="Conical Burrs", parent=burr_grinders)
elec_conical = NodeObject(tree=tree, value="Electric", parent=conical)
manual_conical = NodeObject(tree=tree, value="Manual", parent=conical)

Important Note: TreeDiagrams do not currently support NodeObjects with multiple parents! It may not ever as this seriously complicates the auto layout process. However, you can add links between any two objects in the tree and render them in the diagram. They just may look ugly until you manually rearrange the diagram.

Finally, before writing the diagram you'll want to run the magic penultimate step: auto layout.

tree.auto_layout()
tree.write()

drawpyo's People

Contributors

Stargazers

Watchers

Forkers

kinow mark-iv-ii iamyb sciumo mis7ern9o

drawpyo's Issues

Create import from Draw.io file function

This will be a bigger task to get to eventually and for at least awhile there will be Draw.io features not supported in Draw.pyo. But it would be useful eventually to be able to generate a Python object from a Draw.io file and modify it.

Integrate drawpyo-export Docker image

@rlespinasse created a useful Docker image with an export drawpyo file action. This could be integrated to drawpyo to support exporting a diagram to another file.

https://github.com/rlespinasse/drawio-export

There's also a Github action that can be integrated into build scripts for generating documentation! Ain't that cool.

https://github.com/rlespinasse/drawio-export-action?tab=readme-ov-file

Remove mkdocstrings from install dependencies

Not sure how this package wound up in the dependencies of the wheel but it's not necessary and should be removed.

Add Page size presets

Such as A4, US-Legal, etc.

TreeDiagram doesn't place blocks with no bottom level children

Obvious in hindsight

Add SequenceDiagram custom diagram type

Sequence diagrams are common in system interaction and user interface design. Adding some kind of automated graph support for this would be useful!

Add a from_template to object creation

It would be nice to be able to define an object with the formatting desired then create new objects that mirror the formatting by passing the template in as an argument.

Make leading whitespaces in XML output prettier

This is a low priority since Draw.io doesn't care about white space and as soon as the file is opened and saved in Draw.io the formatting is cleaned up. But the current XML output doesn't have pretty whitespace and it bothers me.

Add FamilyTree diagram type

A new diagram type for creating actual family trees would be useful for geneological work. This could be mostly a subclass of TreeDiagrams. But it will need some added complexity to support pairs of parents as parent nodes.

Select toml vs tomllib conditionally based on Python version in build process

Starting in 3.11, Python started shipping tomllib as a standard library. Prior to that, a library had to be imported with the best option being toml. Currently, drawpyo has no dependencies except this library so it would be nice to preserve that independence. However, it would also be nice to have compatibility with Python pre 3.11.

The way it's currently handled is with a version check and a conditional import:

    if version_info.minor < 11:
        import toml

        data = toml.load(file_name)
    else:
        import tomllib

        with open(file_name, "rb") as f:
            data = tomllib.load(f)

But this won't work with builds and releases. It has to be seen if a conditional dependency can be set based on major Python version for a build.

Support Draw.io's XML based library file structure

The Draw.io app supports importing and exporting from an XML file format. This should be supported.

Also, if the base libraries that ship with the Draw.io app are saved in this format then this could supplant the TOML defs for the built in libraries.

Need to escape illegal characters in XML

These are some HTML type escapes that may work:
xmlize = {}
xmlize[">"] = ">"
xmlize["<"] = "<"
xmlize["\n"] = "
"

Add BasicObject .create_from_style() function

Draw.io allows users to see the style attribute for any shape. This should be an option for parse any style attribute string into its component properties and generate a Draw.pyo BasicObject with those properties.

Add FlowChart diagram type

Add a custom diagram type for working with FlowCharts.

Sub classes should include:

Start
End
Process
Decision
Each class should have the appropriate functions for linking. FlowChart should have an .auto_layout() function that will attempt to make it pretty.

Add screenshots from Draw.io to mkdocs

It would be helpful to have screenshots from Draw.io showing the effects of various formatting choices.

Adding object from lib behaves incorrect

Thanks for the repo first.

If I only add with the ellipse, then the page only displays the basic object without ellipse
item_from_lib = drawpyo.diagram.object_from_library( page=page, library="general", obj_name="ellipse", value="ellipse" )

I have to add one more line to make it working.
item_from_lib.apply_style_string("ellipse;")