py2dag 0.3.22
Convert Python function plans to DAG (JSON, pseudo, optional SVG).
License: MIT
Requires Python: <4.0,>=3.8

# 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`.