vizzpy 0.1.0__tar.gz

vizzpy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atul Saurav
+
+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.

vizzpy-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: vizzpy
+Version: 0.1.0
+Summary: Interactive Python call tree visualizer — upload a project, explore its call graph in the browser
+Author: Atul
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/atulsaurav/vizzpy
+Project-URL: Repository, https://github.com/atulsaurav/vizzpy
+Project-URL: Bug Tracker, https://github.com/atulsaurav/vizzpy/issues
+Keywords: python,call-tree,call-graph,ast,visualization,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn[standard]>=0.23
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: graphviz>=0.20
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: anyio[trio]; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Dynamic: license-file
+
+# VizPy
+
+Interactive Python call tree visualizer. Upload a Python project and explore its function call graph in the browser.
+
+## Features
+
+- **Interactive web UI** — zoom, pan, drag nodes, collapse subtrees
+- **Cross-module resolution** — follows imports across files to draw edges between modules
+- **Dark mode** — toggle with one click
+- **Headless mode** — render a static SVG from the command line (requires Graphviz)
+- **Folder or zip upload** — drag-and-drop a `.zip` or browse for a local folder
+
+## Installation
+
+```bash
+pip install vizzpy
+```
+
+Headless SVG rendering additionally requires the [Graphviz](https://graphviz.org/download/) system package:
+
+```bash
+# macOS
+brew install graphviz
+
+# Debian/Ubuntu
+apt install graphviz
+```
+
+## Usage
+
+### Web UI (recommended)
+
+```bash
+vizzpy --serve
+# open http://127.0.0.1:8000
+```
+
+Upload a `.zip` of your Python project or select a local folder, then click **Analyze**.
+
+- **Scroll / pinch** to zoom
+- **Drag background** to pan
+- **Drag nodes** to rearrange
+- **Double-click a node** to collapse/expand its call subtree
+- **Hover** a node to see its docstring
+
+### Headless SVG
+
+```bash
+vizzpy --headless ./myproject --output call_tree.svg
+```
+
+### Options
+
+```
+vizzpy --serve   [--host HOST] [--port PORT]
+vizzpy --headless PROJECT_PATH [--output OUTPUT.svg]
+```
+
+## How it works
+
+VizPy uses Python's `ast` module to do a two-pass analysis of your source files:
+
+1. **Scope pass** — collects every top-level function and class method with its qualified name (`module.ClassName.method`)
+2. **Edge pass** — walks each file again, resolves `self.method()`, `cls.method()`, imported names, and direct calls to project-internal functions
+
+Results are rendered in the browser with [dagre-d3](https://github.com/dagrejs/dagre-d3) (vendored, works offline). Calls to stdlib or third-party libraries are silently excluded.
+
+## Development
+
+```bash
+git clone https://github.com/atulsaurav/vizzpy
+cd vizzpy
+pip install -e ".[dev]"
+
+# run tests
+pytest
+
+# run with coverage
+pytest --cov=vizzpy --cov-report=term-missing
+```
+
+## License
+
+MIT

vizzpy-0.1.0/README.md

@@ -0,0 +1,84 @@
+# VizPy
+
+Interactive Python call tree visualizer. Upload a Python project and explore its function call graph in the browser.
+
+## Features
+
+- **Interactive web UI** — zoom, pan, drag nodes, collapse subtrees
+- **Cross-module resolution** — follows imports across files to draw edges between modules
+- **Dark mode** — toggle with one click
+- **Headless mode** — render a static SVG from the command line (requires Graphviz)
+- **Folder or zip upload** — drag-and-drop a `.zip` or browse for a local folder
+
+## Installation
+
+```bash
+pip install vizzpy
+```
+
+Headless SVG rendering additionally requires the [Graphviz](https://graphviz.org/download/) system package:
+
+```bash
+# macOS
+brew install graphviz
+
+# Debian/Ubuntu
+apt install graphviz
+```
+
+## Usage
+
+### Web UI (recommended)
+
+```bash
+vizzpy --serve
+# open http://127.0.0.1:8000
+```
+
+Upload a `.zip` of your Python project or select a local folder, then click **Analyze**.
+
+- **Scroll / pinch** to zoom
+- **Drag background** to pan
+- **Drag nodes** to rearrange
+- **Double-click a node** to collapse/expand its call subtree
+- **Hover** a node to see its docstring
+
+### Headless SVG
+
+```bash
+vizzpy --headless ./myproject --output call_tree.svg
+```
+
+### Options
+
+```
+vizzpy --serve   [--host HOST] [--port PORT]
+vizzpy --headless PROJECT_PATH [--output OUTPUT.svg]
+```
+
+## How it works
+
+VizPy uses Python's `ast` module to do a two-pass analysis of your source files:
+
+1. **Scope pass** — collects every top-level function and class method with its qualified name (`module.ClassName.method`)
+2. **Edge pass** — walks each file again, resolves `self.method()`, `cls.method()`, imported names, and direct calls to project-internal functions
+
+Results are rendered in the browser with [dagre-d3](https://github.com/dagrejs/dagre-d3) (vendored, works offline). Calls to stdlib or third-party libraries are silently excluded.
+
+## Development
+
+```bash
+git clone https://github.com/atulsaurav/vizzpy
+cd vizzpy
+pip install -e ".[dev]"
+
+# run tests
+pytest
+
+# run with coverage
+pytest --cov=vizzpy --cov-report=term-missing
+```
+
+## License
+
+MIT

vizzpy-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vizzpy"
+version = "0.1.0"
+description = "Interactive Python call tree visualizer — upload a project, explore its call graph in the browser"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Atul" }]
+requires-python = ">=3.10"
+keywords = ["python", "call-tree", "call-graph", "ast", "visualization", "static-analysis"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "fastapi>=0.100",
+    "uvicorn[standard]>=0.23",
+    "python-multipart>=0.0.9",
+    "graphviz>=0.20",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov",
+    "anyio[trio]",
+    "httpx",
+]
+
+[project.scripts]
+vizzpy = "vizzpy.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/atulsaurav/vizzpy"
+Repository = "https://github.com/atulsaurav/vizzpy"
+"Bug Tracker" = "https://github.com/atulsaurav/vizzpy/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["vizzpy*"]
+
+[tool.setuptools.package-data]
+vizzpy = ["static/**/*"]

vizzpy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vizzpy-0.1.0/tests/test_graph.py

@@ -0,0 +1,81 @@
+"""Tests for graph.py: build_graph, _fallback_label, _fallback_module."""
+import pytest
+from pathlib import Path
+
+from vizzpy.graph import build_graph, _fallback_label, _fallback_module
+
+
+# ── _fallback_label / _fallback_module ───────────────────────────────────────
+
+def test_fallback_label_simple():
+    assert _fallback_label("pkg.utils.helper") == "helper"
+
+def test_fallback_label_no_dot():
+    assert _fallback_label("main") == "main"
+
+def test_fallback_module_with_dot():
+    assert _fallback_module("pkg.utils.helper") == "pkg.utils"
+
+def test_fallback_module_no_dot():
+    assert _fallback_module("main") == "main"
+
+
+# ── build_graph ───────────────────────────────────────────────────────────────
+
+def test_build_graph_basic(tmp_path):
+    (tmp_path / "foo.py").write_text("def a(): pass\ndef b():\n    a()")
+    g = build_graph(tmp_path)
+    node_ids = {n["id"] for n in g["nodes"]}
+    assert "foo.a" in node_ids
+    assert "foo.b" in node_ids
+    assert any(e["source"] == "foo.b" and e["target"] == "foo.a" for e in g["edges"])
+
+
+def test_build_graph_edge_count(tmp_path):
+    # Two calls to the same callee → count == 2
+    (tmp_path / "m.py").write_text("def a(): pass\ndef b():\n    a()\n    a()")
+    g = build_graph(tmp_path)
+    edge = next(e for e in g["edges"] if e["source"] == "m.b" and e["target"] == "m.a")
+    assert edge["count"] == 2
+
+
+def test_build_graph_modules_grouping(tmp_path):
+    (tmp_path / "pkg").mkdir()
+    (tmp_path / "pkg" / "utils.py").write_text("def helper(): pass\ndef run():\n    helper()")
+    g = build_graph(tmp_path)
+    assert "pkg.utils" in g["modules"]
+    assert "pkg.utils.helper" in g["modules"]["pkg.utils"]
+
+
+def test_build_graph_node_label_and_module(tmp_path):
+    (tmp_path / "svc.py").write_text("def process(): pass\ndef main():\n    process()")
+    g = build_graph(tmp_path)
+    node = next(n for n in g["nodes"] if n["id"] == "svc.process")
+    assert node["label"] == "process"
+    assert node["module"] == "svc"
+
+
+def test_build_graph_cross_module(tmp_path):
+    (tmp_path / "a.py").write_text("def helper(): pass")
+    (tmp_path / "b.py").write_text("from a import helper\ndef caller():\n    helper()")
+    g = build_graph(tmp_path)
+    assert any(e["source"] == "b.caller" and e["target"] == "a.helper" for e in g["edges"])
+
+
+def test_build_graph_fallback_node_for_unknown_callee(tmp_path):
+    # Callee comes from an external package — still shows up as a node if referenced
+    # within-project edges only (external callee won't appear unless it's in all_names)
+    # This test just verifies build_graph doesn't crash on an empty project.
+    g = build_graph(tmp_path)
+    assert g["nodes"] == []
+    assert g["edges"] == []
+    assert g["modules"] == {}
+
+
+def test_build_graph_node_docstring(tmp_path):
+    (tmp_path / "m.py").write_text(
+        'def a():\n    """Does something."""\n    pass\ndef b():\n    a()'
+    )
+    g = build_graph(tmp_path)
+    node = next(n for n in g["nodes"] if n["id"] == "m.a")
+    assert node["docstring"] == "Does something."

vizzpy-0.1.0/tests/test_project.py

@@ -0,0 +1,97 @@
+"""Tests for project-level analysis: module naming, test exclusion, edge collection."""
+import pytest
+from pathlib import Path
+
+from vizzpy.parser.project import _is_test_file, get_module_name, analyze_project
+
+
+# ── _is_test_file ─────────────────────────────────────────────────────────────
+
+def test_is_test_by_prefix():
+    assert _is_test_file(Path("/proj/test_foo.py"))
+
+def test_is_test_by_suffix():
+    assert _is_test_file(Path("/proj/foo_test.py"))
+
+def test_is_test_by_dir():
+    assert _is_test_file(Path("/proj/tests/helper.py"))
+
+def test_is_test_nested_dir():
+    assert _is_test_file(Path("/proj/src/test/utils.py"))
+
+def test_not_test_file():
+    assert not _is_test_file(Path("/proj/src/utils.py"))
+
+def test_not_test_file_with_test_in_name():
+    # "testament.py" should not be excluded
+    assert not _is_test_file(Path("/proj/testament.py"))
+
+
+# ── get_module_name ───────────────────────────────────────────────────────────
+
+def test_module_name_simple(tmp_path):
+    f = tmp_path / "utils.py"
+    f.touch()
+    assert get_module_name(f, tmp_path) == "utils"
+
+def test_module_name_nested(tmp_path):
+    (tmp_path / "services").mkdir()
+    f = tmp_path / "services" / "order.py"
+    f.touch()
+    assert get_module_name(f, tmp_path) == "services.order"
+
+def test_module_name_init(tmp_path):
+    (tmp_path / "services").mkdir()
+    f = tmp_path / "services" / "__init__.py"
+    f.touch()
+    assert get_module_name(f, tmp_path) == "services"
+
+
+# ── analyze_project ───────────────────────────────────────────────────────────
+
+def test_basic_edges(tmp_path):
+    (tmp_path / "foo.py").write_text("def a(): pass\ndef b():\n    a()")
+    edges, node_info = analyze_project(tmp_path)
+    assert ("foo.b", "foo.a") in edges
+    assert "foo.a" in node_info
+    assert "foo.b" in node_info
+
+
+def test_excludes_test_files(tmp_path):
+    (tmp_path / "foo.py").write_text("def a(): pass")
+    test_dir = tmp_path / "tests"
+    test_dir.mkdir()
+    (test_dir / "test_foo.py").write_text(
+        "from foo import a\ndef test_it():\n    a()"
+    )
+    edges, node_info = analyze_project(tmp_path)
+    # test functions must not appear as nodes or callers
+    assert not any("test_it" in qn for qn in node_info)
+    assert not any("test_it" in e[0] for e in edges)
+
+
+def test_cross_module_edges(tmp_path):
+    (tmp_path / "a.py").write_text("def helper(): pass")
+    (tmp_path / "b.py").write_text(
+        "from a import helper\ndef caller():\n    helper()"
+    )
+    edges, _ = analyze_project(tmp_path)
+    assert ("b.caller", "a.helper") in edges
+
+
+def test_syntax_error_file_skipped(tmp_path):
+    (tmp_path / "good.py").write_text("def ok(): pass")
+    (tmp_path / "bad.py").write_text("def broken(: pass")  # syntax error
+    # Should not raise; the bad file is silently skipped
+    edges, node_info = analyze_project(tmp_path)
+    assert "good.ok" in node_info
+
+
+def test_no_duplicate_edges(tmp_path):
+    # Two calls from the same caller to the same callee → one edge with count 2
+    (tmp_path / "m.py").write_text(
+        "def a(): pass\ndef b():\n    a()\n    a()"
+    )
+    edges, _ = analyze_project(tmp_path)
+    matching = [e for e in edges if e == ("m.b", "m.a")]
+    assert len(matching) == 2  # raw edges — duplicates expected; build_graph deduplicates

vizzpy-0.1.0/tests/test_server.py

@@ -0,0 +1,134 @@
+"""Tests for the FastAPI server endpoints."""
+import io
+import zipfile
+import pytest
+from httpx import AsyncClient, ASGITransport
+
+from vizzpy.server import app, _find_project_root
+from pathlib import Path
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def _make_zip(files: dict[str, str]) -> bytes:
+    """Build an in-memory zip from {relative_path: content} pairs."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w") as zf:
+        for name, content in files.items():
+            zf.writestr(name, content)
+    return buf.getvalue()
+
+
+@pytest.fixture
+async def client():
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:
+        yield c
+
+
+# ── GET / ─────────────────────────────────────────────────────────────────────
+
+@pytest.mark.anyio
+async def test_index_returns_html(client):
+    r = await client.get("/")
+    assert r.status_code == 200
+    assert "text/html" in r.headers["content-type"]
+
+
+# ── POST /api/analyze ─────────────────────────────────────────────────────────
+
+@pytest.mark.anyio
+async def test_analyze_valid_zip(client):
+    zip_bytes = _make_zip({
+        "proj/foo.py": "def a(): pass\ndef b():\n    a()",
+    })
+    r = await client.post(
+        "/api/analyze",
+        files={"file": ("proj.zip", zip_bytes, "application/zip")},
+    )
+    assert r.status_code == 200
+    data = r.json()
+    assert "nodes" in data and "edges" in data and "modules" in data
+    node_ids = {n["id"] for n in data["nodes"]}
+    assert "foo.a" in node_ids
+
+
+@pytest.mark.anyio
+async def test_analyze_rejects_non_zip(client):
+    r = await client.post(
+        "/api/analyze",
+        files={"file": ("code.py", b"def f(): pass", "text/plain")},
+    )
+    assert r.status_code == 400
+    assert "zip" in r.json()["detail"].lower()
+
+
+@pytest.mark.anyio
+async def test_analyze_rejects_bad_zip(client):
+    r = await client.post(
+        "/api/analyze",
+        files={"file": ("bad.zip", b"not a zip", "application/zip")},
+    )
+    assert r.status_code == 400
+
+
+@pytest.mark.anyio
+async def test_analyze_zip_single_top_level_dir(client):
+    # Zip wraps everything in a top-level folder — _find_project_root should unwrap it
+    zip_bytes = _make_zip({
+        "myproject/utils.py": "def helper(): pass\ndef run():\n    helper()",
+    })
+    r = await client.post(
+        "/api/analyze",
+        files={"file": ("myproject.zip", zip_bytes, "application/zip")},
+    )
+    assert r.status_code == 200
+    node_ids = {n["id"] for n in r.json()["nodes"]}
+    assert "utils.helper" in node_ids  # module name from inside myproject/, not myproject.utils
+
+
+# ── POST /api/analyze-folder ──────────────────────────────────────────────────
+
+@pytest.mark.anyio
+async def test_analyze_folder_basic(client):
+    files = [
+        ("files", ("proj/foo.py", b"def a(): pass\ndef b():\n    a()", "text/x-python")),
+    ]
+    r = await client.post("/api/analyze-folder", files=files)
+    assert r.status_code == 200
+    data = r.json()
+    node_ids = {n["id"] for n in data["nodes"]}
+    assert "foo.a" in node_ids
+
+
+@pytest.mark.anyio
+async def test_analyze_folder_multiple_files(client):
+    files = [
+        ("files", ("pkg/a.py", b"def helper(): pass", "text/x-python")),
+        ("files", ("pkg/b.py", b"from a import helper\ndef caller():\n    helper()", "text/x-python")),
+    ]
+    r = await client.post("/api/analyze-folder", files=files)
+    assert r.status_code == 200
+    data = r.json()
+    assert any(e["source"] == "b.caller" and e["target"] == "a.helper" for e in data["edges"])
+
+
+# ── _find_project_root ────────────────────────────────────────────────────────
+
+def test_find_project_root_unwraps_single_dir(tmp_path):
+    inner = tmp_path / "myproject"
+    inner.mkdir()
+    (inner / "foo.py").touch()
+    assert _find_project_root(tmp_path) == inner
+
+
+def test_find_project_root_keeps_flat(tmp_path):
+    (tmp_path / "foo.py").touch()
+    (tmp_path / "bar.py").touch()
+    assert _find_project_root(tmp_path) == tmp_path
+
+
+def test_find_project_root_ignores_dot_files(tmp_path):
+    (tmp_path / ".DS_Store").touch()
+    inner = tmp_path / "src"
+    inner.mkdir()
+    assert _find_project_root(tmp_path) == inner