repository·main·Indexed 19 days ago
https://github.com/merrimanind/drawpyoA Python library for programmatically generating Diagrams.net/Draw.io charts. It enables developers to create, style, and position diagram objects, write them to XML-based .drawio files, and load existing diagrams for modification. The library supports basic object placement, external shape library registration, and high-level diagram types with automated layout, including TreeDiagram, BarChart, PieChart, and BinaryTreeDiagram.
Drawpyo's core functionality mirrors the Draw.io app. You can:
For detailed implementation steps, refer to the Basic Diagrams - Usage guide.
Drawpyo resolves colors using a specific hierarchy. When an object needs a color, it checks sources in this order of priority:
fill_color, stroke_color, or fontColor via text_format) have the highest priority and override everything else.ColorScheme.Hierarchy Summary:
Object-specific colors > Color scheme colors > Default colors
A ColorScheme is a reusable object that groups fill_color, stroke_color, and font_color. Each color value in a scheme can be None, a hex string (format #RRGGBB), or a StandardColor enum value. Invalid hex strings will raise a ValueError.
from drawpyo import ColorScheme, StandardColor
scheme = ColorScheme(
fill_color=StandardColor.BLUE5,
stroke_color="#FF0000",
)
# You can also update components after creation
scheme.set_fill_color("#ABCDEF")
scheme.set_stroke_color(StandardColor.GRAY7)
scheme.set_gradient(None)TextFormat object. You can access and configure these parameters through the Edge.text_format attribute. For detailed text styling options (like font, size, etc.), refer to the TextFormat documentation.Binary trees in drawpyo are managed using two specialized classes: BinaryTreeDiagram and BinaryNodeObject.
BinaryTreeDiagram: Extends TreeDiagram to provide binary-friendly layout defaults and helper methods. It manages the overall structure and layout.BinaryNodeObject: A subclass of NodeObject that enforces the strict binary tree rule (at most two children). It provides dedicated left and right properties to manage child slots.This pairing ensures that the tree structure remains valid (no node has more than two children) and provides intuitive ways to navigate and link nodes.
from drawpyo.diagram_types import BinaryTreeDiagram, BinaryNodeObject
tree = BinaryTreeDiagram(file_path="path/to/diagram", file_name="Binary Tree.drawio")
root = BinaryNodeObject(tree=tree, value="Root")You can make a parent object automatically expand or contract to fit its children. This behavior is disabled by default.
To enable it, use the following parameters:
autosize_to_children: Set to True to allow the parent to expand to fit its contents.autosize_margin: An integer defining the margin (in pixels) to maintain around child objects. Note that this margin is inclusive of the container's title block.autocontract: Set to True if you want the parent to also contract when children are removed or resized. If False, the parent will expand but never shrink.Manual Triggering:
You can manually trigger the autofit logic at any time by calling the resize_to_children() method on the object. This method respects the configured autosize_margin and autocontract settings.
# Example configuration
parent_container = drawpyo.diagram.Object(
autosize_to_children=True,
autosize_margin=20,
autocontract=True,
page=page
)
# Manually trigger resize
parent_container.resize_to_children()The BinaryNodeObject enforces several structural guarantees:
[left, right]. If you provide only one child during creation (e.g., BinaryNodeObject(tree_children=[child])), the second slot is automatically set to None ([child, None]).tree_children (e.g., BinaryNodeObject(tree_children=[a, b, c])) will raise a ValueError.left and right slots of a parent at the same time. Assigning a node to a new parent automatically detaches it from its old one.Drawpyo preserves the parent-child relationships used by Draw.io containers, swimlanes, and groups. You can navigate the hierarchy by accessing the .objects attribute of a container object, which returns its direct children. Drawpyo applies absolute positioning recursively, so child coordinates are relative to their parent.
# Access a parent container
parent_container = diagram.get_by_id("2292288764992")
# List all child objects
for child in parent_container.objects:
print(f"- {child.value} at ({child.geometry.x}, {child.geometry.y})")Object class. They provide convenience for complex Draw.io objects that are actually small groups of objects (like a container with multiple children). While they offer more functionality than a standard Object, they are not as complex as full custom diagram types. Currently, the List is the primary extended object implemented.You can customize the visual appearance of an edge using color, shading, and boolean effects.
| Parameter | Effect |
|---|---|
opacity | The opacity of the edge (0-100) |
strokeColor | The color of the edge or the stroke around the edge shape ('default', 'none', or a hex color code) |
strokeWidth | The width of the edge or the stroke around the edge shape (1-999) |
fillColor | The fill color of the edge shape ('default', 'none', or a hex color code) |
Set these boolean parameters to enable specific visual effects:
roundedshadowsketchflowAnimation (animates in Draw.io)By default, PieChart labels slices using the format: "{label}: {percentage:.1f}%".
You can override this behavior by providing a label_formatter callable to the PieChart constructor. The callback must accept three arguments: category (the string label), value (the numerical value), and total (the sum of all values in the dataset).
def label_formatter(category: str, value: float, total: float) -> str:
return f"{category}: {value/total*100:.1f}%"
chart = PieChart(data, label_formatter=label_formatter)