🗺️ 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 .

Who is this for? Any Python developer, whatever your stack: Django (real request flow, not just the model schema) · FastAPI (every route's blast radius, async + decorators) · ML pipelines (map the pipeline, find dead experiments). See the honest comparison and measured facts.

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
`context <path> --task "<prose>"`	Same pack, seeded from a natural-language task description (named symbols first, lexical matches as labeled hints; `--strategy graph\|text\|hybrid`)
`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.

MCP server (agents pull, mid-task)

The same engine is available as an MCP server, so Claude Code / Cursor / any MCP client can query the verified graph exactly when a task needs it instead of receiving a guessed pack up front:

pip install 'py-code-visualizer[mcp]'   # Python 3.10+
pyvisualizer-mcp /path/to/project

Three tools, deliberately few: search_code (lexical search over every function's name and source), context_pack (the budget-bounded verified pack, seeded by task and/or focus), and impact (blast radius before you change a function). The server watches file mtimes and rebuilds its in-memory graph only when the project actually changes.

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~~ — shipped: pyvisualizer-mcp (search_code, context_pack, impact)

Architecture

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

120 functions · 213 calls · health F (46/100) — detail: module

flowchart LR
    g0["bench"]
    g1["genproject"]
    g2["main"]
    g3["models"]
    g4["services"]
    g5["urls"]
    g6["repos"]
    g7["services"]
    g8["evaluate"]
    g9["features"]
    g10["ingest"]
    g11["pipeline"]
    g12["train"]
    g13["cli"]
    g14["pipeline"]
    g15["transforms"]
    g16["core"]
    g17["service"]
    g18["billing"]
    g19["api"]
    g20["changes"]
    g21["cli"]
    g22["config"]
    g23["context"]
    g24["analyzer"]
    g25["graph"]
    g26["diff"]
    g27["export"]
    g28["gates"]
    g29["impact"]
    g30["inject"]
    g31["mcp_server"]
    g32["metrics"]
    g33["overlays"]
    g34["retrieval"]
    g35["review"]
    g36["c4"]
    g37["json_graph"]
    g38["setup_init"]
    g39["file_discovery"]
    g40["d3"]
    g41["html"]
    g42["mermaid"]
    g0 --> g1
    g0 --> g19
    g0 --> g37
    g0 --> g41
    g1 --> g6
    g4 --> g3
    g7 -.-> g4
    g7 --> g6
    g11 --> g8
    g11 --> g9
    g11 --> g10
    g11 --> g12
    g13 --> g14
    g14 -.-> g7
    g14 --> g15
    g15 -.-> g4
    g17 --> g16
    g19 --> g25
    g19 --> g31
    g19 --> g39
    g20 --> g31
    g20 --> g33
    g21 --> g14
    g21 --> g19
    g21 --> g22
    g21 --> g23
    g21 --> g26
    g21 --> g27
    g21 --> g28
    g21 --> g29
    g21 --> g30
    g21 --> g31
    g21 --> g32
    g21 --> g33
    g21 --> g35
    g21 --> g36
    g21 --> g37
    g21 --> g40
    g21 --> g42
    g22 --> g31
    g23 --> g4
    g23 --> g20
    g23 --> g28
    g23 --> g29
    g23 --> g31
    g23 --> g32
    g23 --> g33
    g23 --> g34
    g24 --> g31
    g25 --> g4
    g25 --> g31
    g26 --> g4
    g26 --> g31
    g26 --> g32
    g27 --> g28
    g27 --> g30
    g27 --> g31
    g27 --> g32
    g27 --> g37
    g28 --> g31
    g29 --> g20
    g31 --> g19
    g31 --> g23
    g31 --> g29
    g31 --> g34
    g32 --> g31
    g32 --> g34
    g33 --> g31
    g34 --> g4
    g34 --> g31
    g35 --> g20
    g35 --> g28
    g35 --> g31
    g35 --> g32
    g35 --> g42
    g36 --> g42
    g37 --> g31
    g38 --> g19
    g38 --> g30
    g38 --> g31
    g38 --> g32
    g38 --> g42
    g39 --> g4
    g39 --> g6
    g40 --> g41
    g41 --> g37
    g42 --> g31

_{🔒 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.3.0.tar.gz (103.3 kB view details)

Uploaded Jul 25, 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.3.0-py3-none-any.whl (102.7 kB view details)

Uploaded Jul 25, 2026 Python 3

File details

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

File metadata

Download URL: py_code_visualizer-2.3.0.tar.gz
Upload date: Jul 25, 2026
Size: 103.3 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.3.0.tar.gz
Algorithm	Hash digest
SHA256	`f14f2deafe4ba8889f10cb086eacda745cbbbb3b32c88963006f97cdca670c70`
MD5	`999f4453ced3d37d88ca0e22ba51fb09`
BLAKE2b-256	`fee6a8e35b5afa2a7cda11463e3f69050be331e8e8d3798c17aef2d4f61d5656`

See more details on using hashes here.

File details

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

File metadata

Download URL: py_code_visualizer-2.3.0-py3-none-any.whl
Upload date: Jul 25, 2026
Size: 102.7 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.3.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`dcd08c93c1566754c1d5756e0762b4beb386a86f9c8c3fc5acb3d935d8e19bd8`
MD5	`461232d90b495d180bfb6e776a8f2dca`
BLAKE2b-256	`6ed332c1225625eff1d06963aaf6a5bca244ec24fbbfc940838ad2bd777c6c18`