py2dag 0.3.18

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

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.

1. In GitHub repo settings, add a repository secret named PYPI_API_TOKEN with your PyPI token (format: pypi-***).

2. 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.