py2dag 0.1.2__tar.gz

py2dag-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ron Vergis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

py2dag-0.1.2/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.3
+Name: py2dag
+Version: 0.1.2
+Summary: Convert Python function plans to DAG (JSON, pseudo, optional SVG).
+License: MIT
+Author: rvergis
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: svg
+Requires-Dist: graphviz (>=0.20.3,<0.21.0) ; extra == "svg"
+Description-Content-Type: text/markdown
+
+# py2dag
+Convert Python function plans to a DAG (JSON, pseudo, optional SVG).
+
+## 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
+```
+
+
+- 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` is used, `plan.html`.
+
+### 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, create tag, and push it (this triggers the workflow):
+
+```
+make release
+```
+
+Or do individual steps:
+
+```
+make bump-patch
+make tag
+make push-tags
+```
+
+You can also install from the local build with `pip install dist/*.whl`.
+

py2dag-0.1.2/README.md

@@ -0,0 +1,109 @@
+# py2dag
+Convert Python function plans to a DAG (JSON, pseudo, optional SVG).
+
+## 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
+```
+
+
+- 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` is used, `plan.html`.
+
+### 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, create tag, and push it (this triggers the workflow):
+
+```
+make release
+```
+
+Or do individual steps:
+
+```
+make bump-patch
+make tag
+make push-tags
+```
+
+You can also install from the local build with `pip install dist/*.whl`.

py2dag-0.1.2/py2dag/__init__.py

@@ -0,0 +1,14 @@
+"""py2dag package.
+
+Public modules:
+- parser: parse() and parse_file() from the DSL
+- pseudo: generate() for pseudo-code
+- export_svg: export() for svg rendering (optional dependency)
+"""
+
+__all__ = [
+    "parser",
+    "pseudo",
+    "export_svg",
+]
+

py2dag-0.1.2/py2dag/cli.py

@@ -0,0 +1,34 @@
+import argparse
+import json
+
+from . import parser as dsl_parser
+from . import pseudo as pseudo_module
+from . import export_svg
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Convert Python function plan to DAG")
+    ap.add_argument("file", help="Python file containing the plan function")
+    ap.add_argument("--func", default="plan", help="Function name to parse")
+    ap.add_argument("--svg", action="store_true", help="Also export plan.svg via Graphviz (requires dot)")
+    ap.add_argument("--html", action="store_true", help="Also export plan.html via Dagre (no system deps)")
+    args = ap.parse_args()
+
+    plan = dsl_parser.parse_file(args.file, function_name=args.func)
+    with open("plan.json", "w", encoding="utf-8") as f:
+        json.dump(plan, f, indent=2)
+    pseudo_code = pseudo_module.generate(plan)
+    with open("plan.pseudo", "w", encoding="utf-8") as f:
+        f.write(pseudo_code)
+    if args.html:
+        from . import export_dagre
+        export_dagre.export(plan, filename="plan.html")
+    elif args.svg:
+        try:
+            export_svg.export(plan, filename="plan.svg")
+        except RuntimeError as e:
+            print(f"Warning: SVG export skipped: {e}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

py2dag-0.1.2/py2dag/export_dagre.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict
+
+
+HTML_TEMPLATE = """<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>py2dag Plan</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Arial, sans-serif; margin: 0; padding: 0; }
+    header { padding: 10px 16px; background: #111; color: #eee; font-size: 14px; }
+    #container { padding: 12px; }
+    svg { width: 100%; height: 80vh; border-top: 1px solid #ddd; }
+    .node rect { stroke: #666; fill: #fff; rx: 4; ry: 4; }
+    .node.note rect { fill: #fff8dc; }
+    .edgePath path { stroke: #333; fill: none; stroke-width: 1.2px; }
+  </style>
+  <script src="https://d3js.org/d3.v5.min.js"></script>
+  <script src="https://unpkg.com/dagre-d3@0.6.4/dist/dagre-d3.min.js"></script>
+</head>
+<body>
+  <header>py2dag — Dagre graph</header>
+  <div id="container">
+    <svg><g/></svg>
+  </div>
+  <script>
+    const plan = __PLAN_JSON__;
+
+    function showMessage(msg) {
+      const el = document.getElementById('container');
+      el.innerHTML = '<div style="padding:12px;color:#b00;background:#fff3f3;border-top:1px solid #f0caca;">' +
+        msg + '</div>' +
+        '<pre style="margin:0;padding:12px;white-space:pre-wrap;">' +
+        (typeof plan === 'object' ? JSON.stringify(plan, null, 2) : '') + '</pre>';
+    }
+
+    if (typeof window.d3 === 'undefined' || typeof window.dagreD3 === 'undefined') {
+      showMessage('Failed to load Dagre assets (d3/dagre-d3). Check internet connectivity or vendor the JS locally.');
+    } else {
+      try {
+        const g = new dagreD3.graphlib.Graph({ multigraph: true })
+          .setGraph({ rankdir: 'LR', nodesep: 30, ranksep: 40 });
+        // Ensure edges have an object for labels/attrs to avoid TypeErrors
+        g.setDefaultEdgeLabel(() => ({}));
+
+        // Add op nodes
+        (plan.ops || []).forEach(op => {
+          g.setNode(op.id, { label: op.op, class: 'op', padding: 8 });
+        });
+
+        // Add output nodes and edges from source to output
+        (plan.outputs || []).forEach(out => {
+          const outId = `out:${out.as}`;
+          g.setNode(outId, { label: out.as, class: 'note', padding: 8 });
+          g.setEdge(out.from, outId);
+        });
+
+        // Add dependency edges between ops
+        (plan.ops || []).forEach(op => {
+          (op.deps || []).forEach(dep => {
+            g.setEdge(dep, op.id);
+          });
+        });
+
+        const svg = d3.select('svg');
+        const inner = svg.select('g');
+        const render = new dagreD3.render();
+        render(inner, g);
+
+        // Centering
+        const { width, height } = g.graph();
+        const svgWidth = document.querySelector('svg').clientWidth;
+        const xCenterOffset = (svgWidth - width) / 2;
+        inner.attr('transform', 'translate(' + Math.max(10, xCenterOffset) + ', 20)');
+        svg.attr('height', height + 40);
+      } catch (e) {
+        showMessage('Failed to render Dagre graph: ' + e);
+      }
+    }
+  </script>
+</body>
+</html>
+"""
+
+
+def export(plan: Dict[str, Any], filename: str = "plan.html") -> str:
+    """Export the plan as an interactive HTML using Dagre (via dagre-d3).
+
+    Returns the written filename.
+    """
+    html = HTML_TEMPLATE.replace("__PLAN_JSON__", json.dumps(plan))
+    path = Path(filename)
+    path.write_text(html, encoding="utf-8")
+    return str(path)

py2dag-0.1.2/py2dag/export_svg.py

@@ -0,0 +1,48 @@
+from typing import Dict, Any
+
+try:
+    from graphviz import Digraph
+except Exception:  # pragma: no cover
+    Digraph = None  # type: ignore
+
+try:  # optional: only available when graphviz is installed
+    from graphviz.backend.execute import ExecutableNotFound  # type: ignore
+except Exception:  # pragma: no cover
+    ExecutableNotFound = None  # type: ignore
+
+
+def export(plan: Dict[str, Any], filename: str = "plan.svg") -> str:
+    """Export the plan as an SVG using graphviz.
+
+    Writes a true SVG file at `filename`. If Graphviz system binaries are
+    missing, raises RuntimeError with a helpful message. This avoids leaving a
+    stray DOT file named `plan.svg` when rendering fails.
+    """
+    if Digraph is None:
+        raise RuntimeError("Python package 'graphviz' is required for SVG export")
+
+    graph = Digraph(format="svg")
+    for op in plan.get("ops", []):
+        graph.node(op["id"], label=op["op"])
+        for dep in op.get("deps", []):
+            graph.edge(dep, op["id"])
+    for out in plan.get("outputs", []):
+        out_id = f"out:{out['as']}"
+        graph.node(out_id, label=out['as'], shape="note")
+        graph.edge(out["from"], out_id)
+
+    try:
+        # Use pipe() to obtain SVG bytes directly so we only write the
+        # destination file on successful rendering.
+        svg_bytes = graph.pipe(format="svg")
+    except Exception as e:  # pragma: no cover - depends on local system
+        if ExecutableNotFound is not None and isinstance(e, ExecutableNotFound):
+            raise RuntimeError(
+                "Graphviz 'dot' executable not found. Install Graphviz (e.g., 'brew install graphviz' on macOS) "
+                "or run without --svg."
+            ) from e
+        raise
+
+    with open(filename, "wb") as f:
+        f.write(svg_bytes)
+    return filename

py2dag-0.1.2/py2dag/parser.py

@@ -0,0 +1,173 @@
+import ast
+import json
+import re
+from typing import Any, Dict, List, Optional
+
+VALID_NAME_RE = re.compile(r'^[a-z_][a-z0-9_]{0,63}$')
+
+
+class DSLParseError(Exception):
+    """Raised when the mini-DSL constraints are violated."""
+
+
+def _literal(node: ast.AST) -> Any:
+    """Return a Python literal from an AST node or raise DSLParseError."""
+    if isinstance(node, ast.Constant):
+        return node.value
+    if isinstance(node, (ast.List, ast.Tuple)):
+        return [_literal(elt) for elt in node.elts]
+    if isinstance(node, ast.Dict):
+        return {_literal(k): _literal(v) for k, v in zip(node.keys, node.values)}
+    raise DSLParseError("Keyword argument values must be JSON-serialisable literals")
+
+
+def _get_call_name(func: ast.AST) -> str:
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        parts: List[str] = []
+        while isinstance(func, ast.Attribute):
+            parts.append(func.attr)
+            func = func.value
+        if isinstance(func, ast.Name):
+            parts.append(func.id)
+            return ".".join(reversed(parts))
+    raise DSLParseError("Only simple or attribute names are allowed for operations")
+
+
+def parse(source: str, function_name: str = "plan") -> Dict[str, Any]:
+    if len(source) > 20_000:
+        raise DSLParseError("Source too large")
+    module = ast.parse(source)
+    fn = None
+    for node in module.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == function_name:
+            fn = node
+            break
+    if fn is None:
+        raise DSLParseError(f"Function {function_name!r} not found")
+
+    defined: set[str] = set()
+    ops: List[Dict[str, Any]] = []
+    outputs: List[Dict[str, str]] = []
+    settings: Dict[str, Any] = {}
+
+    returned_var: Optional[str] = None
+    for i, stmt in enumerate(fn.body):
+        if isinstance(stmt, ast.Assign):
+            if len(stmt.targets) != 1 or not isinstance(stmt.targets[0], ast.Name):
+                raise DSLParseError("Assignment targets must be simple names")
+            var_name = stmt.targets[0].id
+            if not VALID_NAME_RE.match(var_name):
+                raise DSLParseError(f"Invalid variable name: {var_name}")
+            if var_name in defined:
+                raise DSLParseError(f"Duplicate variable name: {var_name}")
+
+            value = stmt.value
+            if isinstance(value, ast.Await):
+                value = value.value
+            if isinstance(value, ast.Call):
+                op_name = _get_call_name(value.func)
+
+                deps: List[str] = []
+                for arg in value.args:
+                    if not isinstance(arg, ast.Name):
+                        raise DSLParseError("Positional args must be variable names")
+                    if arg.id not in defined:
+                        raise DSLParseError(f"Undefined dependency: {arg.id}")
+                    deps.append(arg.id)
+
+                kwargs: Dict[str, Any] = {}
+                for kw in value.keywords:
+                    if kw.arg is None:
+                        raise DSLParseError("**kwargs are not allowed")
+                    kwargs[kw.arg] = _literal(kw.value)
+
+                ops.append({"id": var_name, "op": op_name, "deps": deps, "args": kwargs})
+            elif isinstance(value, ast.JoinedStr):
+                # Minimal f-string support: only variable placeholders
+                deps: List[str] = []
+                parts: List[str] = []
+                for item in value.values:
+                    if isinstance(item, ast.Constant) and isinstance(item.value, str):
+                        parts.append(item.value)
+                    elif isinstance(item, ast.FormattedValue) and isinstance(item.value, ast.Name):
+                        name = item.value.id
+                        if name not in defined:
+                            raise DSLParseError(f"Undefined dependency: {name}")
+                        deps.append(name)
+                        parts.append("{" + str(len(deps) - 1) + "}")
+                    else:
+                        raise DSLParseError("f-strings may only contain variable names")
+                template = "".join(parts)
+                ops.append({
+                    "id": var_name,
+                    "op": "TEXT.format",
+                    "deps": deps,
+                    "args": {"template": template},
+                })
+            else:
+                raise DSLParseError("Right hand side must be a call or f-string")
+            defined.add(var_name)
+
+        elif isinstance(stmt, ast.Expr):
+            call = stmt.value
+            if isinstance(call, ast.Await):
+                call = call.value
+            if not isinstance(call, ast.Call):
+                raise DSLParseError("Only call expressions allowed at top level")
+            name = _get_call_name(call.func)
+            if name == "settings":
+                for kw in call.keywords:
+                    if kw.arg is None:
+                        raise DSLParseError("settings does not accept **kwargs")
+                    settings[kw.arg] = _literal(kw.value)
+                if call.args:
+                    raise DSLParseError("settings only accepts keyword literals")
+            elif name == "output":
+                if len(call.args) != 1 or not isinstance(call.args[0], ast.Name):
+                    raise DSLParseError("output requires a single variable name argument")
+                var = call.args[0].id
+                if var not in defined:
+                    raise DSLParseError(f"Undefined output variable: {var}")
+                filename = None
+                for kw in call.keywords:
+                    if kw.arg in {"as", "as_"}:
+                        filename = _literal(kw.value)
+                    else:
+                        raise DSLParseError("output only accepts 'as' keyword")
+                if filename is None or not isinstance(filename, str):
+                    raise DSLParseError("output requires as=\"filename\"")
+                outputs.append({"from": var, "as": filename})
+            else:
+                raise DSLParseError("Only settings() and output() calls allowed as expressions")
+        elif isinstance(stmt, ast.Return):
+            if i != len(fn.body) - 1:
+                raise DSLParseError("return must be the last statement")
+            if not isinstance(stmt.value, ast.Name):
+                raise DSLParseError("return must return a variable name")
+            var = stmt.value.id
+            if var not in defined:
+                raise DSLParseError(f"Undefined return variable: {var}")
+            returned_var = var
+        else:
+            raise DSLParseError("Only assignments, expression calls, and a final return are allowed in function body")
+
+    if not outputs:
+        if returned_var is not None:
+            outputs.append({"from": returned_var, "as": "return"})
+        else:
+            raise DSLParseError("At least one output() call required")
+    if len(ops) > 200:
+        raise DSLParseError("Too many operations")
+
+    plan: Dict[str, Any] = {"version": 1, "ops": ops, "outputs": outputs}
+    if settings:
+        plan["settings"] = settings
+    return plan
+
+
+def parse_file(filename: str, function_name: str = "plan") -> Dict[str, Any]:
+    with open(filename, "r", encoding="utf-8") as f:
+        src = f.read()
+    return parse(src, function_name=function_name)

py2dag-0.1.2/py2dag/pseudo.py

@@ -0,0 +1,28 @@
+import json
+from typing import Dict, Any
+
+
+def generate(plan: Dict[str, Any]) -> str:
+    """Generate human readable pseudo-code from a plan dict."""
+    lines = []
+    settings = plan.get("settings")
+    if settings:
+        args = ", ".join(f"{k}={json.dumps(v)}" for k, v in settings.items())
+        lines.append(f"settings({args})")
+        lines.append("")
+    for op in plan.get("ops", []):
+        deps = op.get("deps", [])
+        kw = op.get("args", {})
+        parts = []
+        if deps:
+            parts.extend(deps)
+        if kw:
+            parts.extend(f"{k}={json.dumps(v)}" for k, v in kw.items())
+        arg_str = ", ".join(parts)
+        lines.append(f"{op['id']} = {op['op']}({arg_str})")
+    if plan.get("ops"):
+        lines.append("")
+    for out in plan.get("outputs", []):
+        lines.append(f"output({out['from']}, as={json.dumps(out['as'])})")
+    return "\n".join(lines).rstrip() + "\n"
+

py2dag-0.1.2/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["poetry-core>=1.8.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "py2dag"
+version = "0.1.2"
+description = "Convert Python function plans to DAG (JSON, pseudo, optional SVG)."
+authors = ["rvergis"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.8"
+graphviz = { version = "^0.20.3", optional = true }
+
+[tool.poetry.extras]
+svg = ["graphviz"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+
+[tool.poetry.scripts]
+py2dag = "py2dag.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]