DotFlow

A Python-based DOT language interpreter with multiple API styles for creating flowcharts and diagrams effortlessly.

Features

• Multiple API Styles: Pythonic, natural language, and textual DSL
• Auto-shapes: Predefined shapes for common elements
• Clustering: Group nodes logically
• Themes: Built-in color schemes
• Export: PNG, SVG, PDF and DOT file export

Installation

pip install dotflow

Quick Start

from dotflow import Flow, create_flow

# Pythonic API
flow = create_flow("my_flow")
(flow.start("Start")
     .process("Process Data")
     .decision("Valid?")
     .connect("Valid?", "End", label="Yes")
     .connect("Valid?", "Process Data", label="No"))

flow.render("png", "my_flow.png")

API Styles

Pythonic API

flow.process("A").connect("A", "B", label="Next")

Natural Language

flow >> "A" >> "B" | "Label"

Textual DSL

flow.parse_dsl("""
A [shape=rect, label='Custom']
B [shape=rect, label="decision"]
C [shape=diamond, label=process]
A->B:Input Data
B{decison}->C:Valid
# End of of diagram
""")

Command Line Interface

DotFlow provides a powerful CLI for generating diagrams without writing Python code.

Basic Usage

# Generate from DSL text - Line breaks a mandatory just lik in dsl file
dotflow generate my_diagram.png --dsl-text \
"
A
B
A->B
" --theme green

# Generate from DSL file
dotflow generate diagram.svg --dsl-file workflow.dsl --theme dark

# Generate DOT file
dotflow generate workflow.dot --dsl-file workflow.dsl --format dot

• Interactive Wizard

# Interactive flow creation
dotflow wizard my_flow.png --interactive

# Quick sample flow
dotflow wizard sample.png

• Validation

# Validate DSL syntax
dotflow validate workflow.dsl

• Examples

# Generate example diagrams
dotflow examples --format svg --theme blue

# Generate DSL cheat sheet
dotflow cheat-sheet

• Themes

# List available themes
dotflow themes

• DSL Syntax

The textual DSL supports:

# Comments
# First lets define the nodes
Start[shape=ellipse]
Valid[shape=diamond, label="Valid?"]
Process
ErrorHandler[label='Error Handler']
Storage
End[shape=ellipse]
# make decisions and connect nodes
# Validate data
Start{decision}->Valid:Validate
Valid->Process:isValid
Process->Storage:Store data
# Handle processing errors
Process->ErrorHandler:Processing Error
Storage->End:Finalize
# Handle invalid data
Valid->ErrorHandler:Invalid data
ErrorHandler->End

Usage Examples

1. Install the package:

pip install -e .

1. Basic CLI usage:

# Generate a simple flow
dotflow generate my_diagram.png --dsl-text \
"
A
B
A->B
" \
--theme dark

# Use interactive wizard
dotflow wizard my_flow.png --interactive

# Validate DSL file
dotflow validate my_workflow.dsl

# Generate all examples
dotflow examples --format svg

1. Using as Python module:

python -m dotflow generate diagram.png --dsl-text "
A
B
A->B
" \
--theme blue

This CLI implementation provides:

[] Multiple Commands: generate, wizard, validate, themes, examples, cheat-sheet

[] Interactive Mode: Build flows step-by-step

[] Comprehensive Validation: DSL syntax checking

[] Theme Support: All available themes accessible via CLI

[] Example Generation: Pre-built example diagrams

[] Error Handling: Robust error messages and exit codes

[] Testing: Complete test suite for CLI functionality

[] Flexible Output: Multiple formats (PNG, SVG, PDF, DOT)

The CLI makes the package accessible to users who prefer command-line tools or want to integrate diagram generation into scripts and automation workflows.

Documentation

See full documentation for advanced usage.

License

• This product is licensed under MIT license see license

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions