flowchartlib

A lightweight Python library for generating clean hierarchical flowcharts as SVG files.

Installation

pip install drawsvg

Clone the repo and import directly:

from flowchartlib import FlowchartObject, make_flowchart
from Node import Node

---

Quick Start

Every diagram starts with a FlowchartObject and a root Node.

from flowchartlib import FlowchartObject, make_flowchart
from Node import Node

chart = FlowchartObject()
root = chart.addNode(Node("My Project"))

make_flowchart(chart)
# output saved to Out/flowchart.svg

---

Node API

Node(label, color="white")

Creates a new node with a text label and optional background color.

node = Node("Flight Computer")
node = Node("Flight Computer", color="lightblue")

---

addNode(node) → Node

Adds a single child node. Returns the child so you can chain off it.

root = chart.addNode(Node("Root"))
child = root.addNode(Node("Child"))
grandchild = child.addNode(Node("Grandchild"))

---

addNodeArray(labels) → Node

Adds multiple children at once from a list of label strings. Returns self.

root.addNodeArray(["Avionics", "Software", "Structures"])

---

addNodeCascade(labels) → Node

Creates a chain where each label becomes the child of the previous one, then appends the top of the chain to the current node. Returns the top node of the chain.

# creates: root -> Systems -> Subsystems -> Components
top = root.addNodeCascade(["Systems", "Subsystems", "Components"])

---

setColor(color) → Node

Sets the fill color of the node. Accepts any valid CSS color. Returns self for chaining.

node.setColor("#d0e8ff")
node.setColor("lightgreen")

# chainable at creation
root.addNode(Node("Warning").setColor("orange"))

---

getDescendant(label) → Node | None

Searches all descendants using breadth-first search and returns the first node matching the label. Returns None if not found.

av = root.getDescendant("Avionics")
av.setColor("lightblue")

Note: If multiple nodes share the same label, getDescendant returns the first one found. Labels do not need to be unique — each node is tracked internally by a unique ID.

---

Generating the Chart

make_flowchart(chart, filename="flowchart.svg")

Renders the chart and saves it to the Out/ directory.

make_flowchart(chart)                        # saves to Out/flowchart.svg
make_flowchart(chart, "my_diagram.svg")      # saves to Out/my_diagram.svg

---

Full Example

from flowchartlib import FlowchartObject, make_flowchart
from Node import Node

chart = FlowchartObject()

# root node
root = chart.addNode(Node("Company", color="#e8f0fe"))

# add top-level departments
root.addNodeArray(["Engineering", "Operations", "Marketing"])

# build out Engineering
eng = root.getDescendant("Engineering")
eng.addNodeArray(["Frontend", "Backend", "Infrastructure"])
eng.getDescendant("Frontend").setColor("lightblue")
eng.getDescendant("Backend").setColor("lightblue")

# single child — renders with a shorter edge
backend = eng.getDescendant("Backend")
backend.addNode(Node("API Services"))

# cascade — creates a chain under Infrastructure
eng.getDescendant("Infrastructure").addNodeCascade(["Cloud", "Kubernetes", "Pods"])

# build out Operations
ops = root.getDescendant("Operations")
ops.addNodeArray(["HR", "Finance", "Legal"])

# build out Marketing
mkt = root.getDescendant("Marketing")
mkt.addNodeArray(["Social", "SEO", "Partnerships"])
mkt.getDescendant("Social").setColor("lightyellow")

make_flowchart(chart, "company.svg")

Output layout:

• Single-child edges are rendered at half height for a compact look
• Multi-child edges use a horizontal bus rail connecting all siblings
• Duplicate labels are supported — each node has a unique internal ID

---

Configuration

Visual constants are defined at the top of flowchartlib.py:

Constant	Default	Description
NODE_W	140	Node width in pixels
NODE_H	40	Node height in pixels
H_GAP	20	Horizontal gap between sibling nodes
V_GAP	50	Vertical gap between levels