py2dag

Convert Python function plans to a DAG (JSON, pseudo, optional HTML/SVG).

Features

Writes plan.json with explicit nodes and edges for downstream tools.
Generates human-readable pseudo code at plan.pseudo.
Optional exports:
- --html for an interactive Dagre graph with color-coded nodes.
- --svg for a Graphviz-rendered SVG.
Node colors are chosen deterministically so the same op type is colored consistently across runs.

Install

From PyPI (once published):

pip install py2dag

From source using Makefile targets (recommended for development):

make setup         # create .venv and install deps (SVG extra by default)

Dev Environment via Makefile

Install Poetry (see poetry docs or pipx install poetry).
From the repo root:

poetry install

Notes:

HTML export uses Dagre via CDN (d3.js + dagre-d3). No local system deps, but an internet connection is required when opening plan.html. If you are offline or behind a firewall, the page will show a message; vendor the JS locally or open with internet access.
Optional Graphviz SVG export (--svg) requires Graphviz system binaries (e.g., brew install graphviz).

Local Virtualenv (.venv)

Create/update venv and install deps: make setup
Open interactive shell inside venv: make shell
.venv/ is ignored by git.

Usage

Run via Makefile (dev) — generates an interactive Dagre HTML graph:

make run FILE=path/to/your_file.py ARGS=--html

Run the installed CLI (after pip install py2dag):

py2dag path/to/your_file.py --html  # interactive HTML
py2dag path/to/your_file.py --svg   # Graphviz SVG

Or directly with Python (inside venv):

poetry run python cli.py path/to/your_file.py --html

This generates plan.json, plan.pseudo, and if --html/--svg is used, plan.html or plan.svg.

Function name: By default the tool auto-detects a suitable function in the file. To target a specific function, pass --func NAME.

Offline HTML (no internet)

plan.html references d3 and dagre-d3 from CDNs. To view graphs fully offline, download those files and place them next to plan.html, then edit the two <script> tags in py2dag/export_dagre.py to point at your local copies.

Example (download once):

wget https://d3js.org/d3.v5.min.js -O d3.v5.min.js
wget https://unpkg.com/dagre-d3@0.6.4/dist/dagre-d3.min.js -O dagre-d3.min.js

Then update the script tags to ./d3.v5.min.js and ./dagre-d3.min.js and regenerate plan.html.

Tests

Run tests using the Makefile (prints visible with -s):

make test

Build

Build the package artifacts (wheel and sdist):

make build

Releasing to PyPI

This repo includes a GitHub Actions workflow that publishes to PyPI when you push a Git tag like v0.1.1.

In GitHub repo settings, add a repository secret named PYPI_API_TOKEN with your PyPI token (format: pypi-***).
Bump patch version, commit, and tag locally; then push tags to trigger the workflow:

make patch        # bumps version, commits, and tags vX.Y.Z
make release      # pushes commits and tags to GitHub (triggers publish)

Or trigger the "Patch release" GitHub Action from the Actions tab to bump, commit, tag, and push directly from GitHub.

Or push tags manually:

git push --tags

You can also install from the local build with pip install dist/*.whl.

Metadata

Release files for py2dag 0.3.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for py2dag 0.3.22
File	Size	Uploaded
py2dag-0.3.22.tar.gz	19.7 kB	Sep 22, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for py2dag 0.3.22
File	Interpreter	ABI	Platform	Reset
py2dag-0.3.22-py3-none-any.whl 21.4 kB Sep 22, 2025	Python 3	none	any	Details

Total release size: 41.1 kB

Release files / py2dag-0.3.22.tar.gz

Download URL	py2dag-0.3.22.tar.gz
Size	19.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`fff3079663c8919c94a6fa4090709a3d47db107f9033443a80da649c2a54f90a`
BLAKE2b-256 checksum How to use checksums	`c0c99eaf301486486cea73a294c6ddc1547d6606a3b931e3015dbc35ce0b8622`
Upload date	Sep 22, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.8`

Release files / py2dag-0.3.22-py3-none-any.whl

Download URL	py2dag-0.3.22-py3-none-any.whl
Size	21.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`673e16ede8318f15e104fe2ecf1535584feb70759e8635dd960a030b7fa8c01d`
BLAKE2b-256 checksum How to use checksums	`0ec897ac3428827e3890e746863df25ee33e1072d8cf305f2dca23cd1f3dbdf0`
Upload date	Sep 22, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.8`