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

⚡ 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
visualize	Render html · mermaid · json · c4 · svg/png
readme	Inject/update a Mermaid diagram in any Markdown file (idempotent)
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
health	Architecture health score (A–F) with an SVG badge
export	ARCHITECTURE.json + ARCHITECTURE.md for AI tools

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 · 140 calls · health B+ (87/100) — detail: module

flowchart LR
    g0["main"]
    g1["module_a"]
    g2["module_b"]
    g3["api"]
    g4["cli"]
    g5["config"]
    g6["analyzer"]
    g7["graph"]
    g8["model"]
    g9["resolver"]
    g10["diff"]
    g11["export"]
    g12["gates"]
    g13["impact"]
    g14["inject"]
    g15["metrics"]
    g16["overlays"]
    g17["c4"]
    g18["json_graph"]
    g19["file_discovery"]
    g20["d3"]
    g21["html"]
    g22["mermaid"]
    g0 --> g1
    g0 --> g2
    g2 --> g1
    g3 --> g7
    g3 --> g9
    g3 --> g19
    g4 --> g3
    g4 --> g5
    g4 --> g10
    g4 --> g11
    g4 --> g12
    g4 --> g13
    g4 --> g14
    g4 --> g15
    g4 --> g16
    g4 --> g17
    g4 --> g18
    g4 --> g20
    g4 --> g22
    g10 --> g15
    g11 -.-> g8
    g11 --> g12
    g11 --> g15
    g11 --> g18
    g17 --> g22
    g20 --> g21
    g21 --> g18

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

Contributing

See CONTRIBUTING.md. PyVisualizer is MIT-licensed.