🗺️ py-code-visualizer

Deterministic, AST-verified architecture ground truth for Python. LLMs guess your architecture. py-code-visualizer proves it — every edge is traceable to a file:line.

py-code-visualizer: pip install, then visualize your project into a self-contained interactive map

⚡ Try it live in your browser → · drop a .py file, see the graph, nothing uploaded

py-code-visualizer reads your Python source with static analysis (no code is ever imported or executed) and produces a call graph you can trust: self-healing README diagrams, PR architecture-change reports, CI gates that block circular dependencies, and a fully offline interactive map. Because the output is deterministic, it lives in your pipelines and never drifts.

pip install py-code-visualizer && py-code-visualizer visualize .

Why this exists (and why an LLM can't do it)

An LLM asked to diagram your repo produces the architecture it expects a repo like yours to have — plausible, confident, and subtly wrong. It invents links between modules that never call each other, silently drops what didn't fit the context window, and gives a different answer every run, so you can never diff it or put it in CI.

PyVisualizer is the opposite by construction:

	LLM diagram	PyVisualizer
Correctness	Inferred, often hallucinated	Parsed from the AST
Provenance	None	Every edge → `file:line`
Determinism	Different every run	Byte-identical
Ambiguity	Hidden behind confidence	Flagged, with candidates kept
CI-able	No	Yes — gates, diffs, drift checks
Code leaves the machine	Usually	Never

When a call genuinely can't be resolved to one target, we don't pick one and pretend — we tag the edge ambiguous and keep the full candidate list. That honesty is the whole product.

Install

pip install py-code-visualizer

60-second start

# Interactive, fully self-contained HTML map (opens offline, zero network)
py-code-visualizer visualize ./your_project -o architecture.html

# Keep a live diagram inside your README forever
py-code-visualizer readme ./your_project

# Fail CI on new circular dependencies
py-code-visualizer check ./your_project --fail-on-cycles

# What breaks if I touch this function?
py-code-visualizer impact your_pkg.core.save ./your_project

For a scrappy startup 🚀

You will never schedule a "docs sprint." So don't. Add one line to CI and your README always carries a current architecture diagram — investor- and due-diligence-ready for free — while every PR gets a comment showing exactly what changed structurally.

# .github/workflows/architecture.yml
- uses: haider1998/PyVisualizer@v2
  with: { mode: readme }

A new contractor onboards from the interactive map instead of a three-day Slack Q&A. Pivots stop being archaeology.

For a Fortune 500 enterprise 🏛️

Code never leaves the machine. Pure AST, no execution, no API calls — the anti-LLM tool for security review. Generated HTML is a single file with zero network requests (air-gap safe).
Architecture-as-code gates. Declare layers and forbidden dependencies; the build fails on violations — at the call-graph level, stricter than import linters.
Audit trail. Deterministic diagrams committed by CI make git history your dated, attributable architecture change-log (SOC 2 / review boards).
Monorepo scale. Hierarchical rollup (module → class → function), never silent sampling.

# pyproject.toml
[tool.pyvisualizer.rules]
layers = ["api", "domain", "infra"]
forbid = ["domain -> api", "domain -> infra"]

Commands

Command	What it does
`review <path> --base <ref>`	PR review report: changed functions, blast radius, risk flags, focused subgraph — clickable `file:line` on every reference
`context <path> --focus <fn>`	Verified context pack for AI agents: task-scoped, budget-bounded, zero guessed edges
`visualize`	Render `html` · `mermaid` · `json` · `c4` · `svg`/`png`
`readme`	Inject/update a Mermaid diagram in any Markdown file (idempotent) + jump-to-source index
`json`	Emit the canonical, diffable graph JSON
`diff base.json head.json`	PR-ready architecture-change report (+ new-cycle gate)
`check`	Enforce layering rules & cycles — CI gate (`--dead-code` too)
`impact <fn>`	Blast-radius: transitive callers/callees + risk line (`--format markdown`)
`health`	Architecture health score (A–F) with an SVG badge
`export`	`ARCHITECTURE.json` + `ARCHITECTURE.md` + AGENTS.md wiring (`--check` freshness gate)
`init`	Opt-in setup — generate only the automation you choose (`review`/`readme`/`context`/`gates`)

Two jobs, one engine. review makes code review on a large repo a focused few-minute pass; context gives an AI agent a verified, ~96%-smaller slice of the architecture instead of the whole repo. See VISION.md and the use-case walkthroughs.

Use cases (real commands, real output)

Three end-to-end walkthroughs, each backed by a runnable fixture in examples/scenarios/ — every command and every line of output is reproducible, nothing is staged:

🗺️ The orphan monolith — onboard onto an undocumented codebase with visualize + health + check --dead-code.
🛡️ The audit deadline — enforce layering rules at the call-graph level and produce dated SOC 2 evidence.
🧨 The fearless refactor — impact blast radius, then a diff gate that fails a PR on a new cycle.

See the full use-case index + a recipe for every command.

Measured (reproduce with python benchmarks/bench.py → docs/benchmarks.json): a 98,669-line project maps to a full call graph in ~4.9 s (26,658 functions), 100% of edges carry file:line, output is byte-identical across runs, and the generated HTML makes 0 network requests. (macOS arm64, Python 3.14; speed is hardware-dependent — provenance, determinism, and zero-network are structural.)

The interactive map

A single self-contained HTML file (no CDN, works offline):

Layered abstraction — toggle module → class → function views
Click any node — signature, file:line, callers & callees (all clickable)
⌘K command palette, live search, module filter
Deep links — the URL encodes the selected node; paste it in Slack and your teammate lands on the exact function
Tour mode — auto-generated walkthrough from detected entry points
Overlays — cycles (red), ambiguity (dashed), and --churn git-heatmap
Minimap, pan/zoom/drag, light/dark, SVG export

Feed the graph to your AI tools

py-code-visualizer export --for-ai ./your_project

Point Cursor / Claude at the verified ARCHITECTURE.json instead of asking a model to re-derive structure from raw source. Point your agent at the graph, not the repo.

Accuracy guarantees

Nested classes, methods, and closures are collected with correct qualified names (pkg.Outer.Inner.method, mod.func.<locals>.inner).
Chained calls (get_client().fetch()), comprehensions, and lambdas are captured.
super()/inherited calls resolved through the computed MRO (tagged inherited).
Parameter and variable type annotations drive method resolution.
Calls to stdlib/third-party code produce no edge — we never invent one.
Ambiguous calls are tagged and kept as candidates; --strict drops them.

See docs/integrations.md for GitHub Actions, GitLab CI, and pre-commit setup.

Configuration

[tool.pyvisualizer]
exclude = ["tests", "migrations"]
max_nodes = 120
target = "README.md"
detail = "module"          # module | class | function

Roadmap

⏳ Time-travel — scrub your architecture's evolution across releases
🔁 Watch mode — live-reloading map while you refactor
🔌 MCP server — who_calls, what_breaks_if_i_change as agent tools

Architecture

The diagram below is generated by PyVisualizer itself and kept in sync by CI.

120 functions · 175 calls · health C (74/100) — detail: module

flowchart LR
    g0["bench"]
    g1["genproject"]
    g2["main"]
    g3["cli"]
    g4["pipeline"]
    g5["core"]
    g6["service"]
    g7["core"]
    g8["billing"]
    g9["db"]
    g10["api"]
    g11["changes"]
    g12["cli"]
    g13["config"]
    g14["context"]
    g15["analyzer"]
    g16["graph"]
    g17["diff"]
    g18["export"]
    g19["gates"]
    g20["impact"]
    g21["inject"]
    g22["metrics"]
    g23["overlays"]
    g24["review"]
    g25["c4"]
    g26["json_graph"]
    g27["setup_init"]
    g28["file_discovery"]
    g29["d3"]
    g30["html"]
    g31["mermaid"]
    g0 --> g1
    g0 --> g10
    g0 --> g26
    g0 --> g30
    g3 --> g4
    g5 --> g6
    g6 --> g5
    g8 --> g9
    g10 --> g16
    g10 --> g28
    g11 --> g23
    g12 --> g4
    g12 --> g10
    g12 --> g13
    g12 --> g14
    g12 --> g17
    g12 --> g18
    g12 --> g19
    g12 --> g20
    g12 --> g21
    g12 --> g22
    g12 --> g23
    g12 --> g24
    g12 --> g25
    g12 --> g26
    g12 --> g29
    g12 --> g31
    g14 --> g11
    g14 --> g19
    g14 --> g20
    g14 --> g22
    g14 --> g23
    g17 --> g22
    g18 --> g19
    g18 --> g21
    g18 --> g22
    g18 --> g26
    g20 --> g11
    g24 --> g11
    g24 --> g19
    g24 --> g22
    g24 --> g31
    g25 --> g31
    g26 --> g11
    g27 --> g10
    g27 --> g13
    g27 --> g18
    g27 --> g21
    g27 --> g22
    g27 --> g31
    g29 --> g30
    g30 --> g26

_{🔒 Deterministic, AST-verified — no code executed. Generated by py-code-visualizer.}

📍 Jump to source (120 functions)

Contributing

See CONTRIBUTING.md. PyVisualizer is MIT-licensed.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_code_visualizer-2.2.0.tar.gz (86.9 kB view details)

Uploaded Jul 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

py_code_visualizer-2.2.0-py3-none-any.whl (89.9 kB view details)

Uploaded Jul 20, 2026 Python 3

File details

Details for the file py_code_visualizer-2.2.0.tar.gz.

File metadata

Download URL: py_code_visualizer-2.2.0.tar.gz
Upload date: Jul 20, 2026
Size: 86.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.15

File hashes

Hashes for py_code_visualizer-2.2.0.tar.gz
Algorithm	Hash digest
SHA256	`94b2d441f19fc457c18709184c820f67f440ba879335053ae4e91164b56d0aa3`
MD5	`12a9d877373c7949bcd09d020ae48a14`
BLAKE2b-256	`4f3be8c5acae2f7cdb972683e4787539423caba802389403130aa773664744cd`

See more details on using hashes here.

File details

Details for the file py_code_visualizer-2.2.0-py3-none-any.whl.

File metadata

Download URL: py_code_visualizer-2.2.0-py3-none-any.whl
Upload date: Jul 20, 2026
Size: 89.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.15

File hashes

Hashes for py_code_visualizer-2.2.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`ff72eece2d11337654aa8b671d822a0aaf86830f67b6e96752ac0b8ff5131464`
MD5	`48057c6fd90ad21a5f0e099534f1a857`
BLAKE2b-256	`d30be3579dc0c1c5a4f70620d3721ed2ab9a84a15ee385f7c37565e654c7f986`