Pydescope is a static analysis tool designed to help developers visualize the internal structure and dependencies of their Python projects. By parsing source code and mapping imports, it generates interactive 2D/3D graphs using NetworkX and PyVis, allowing you to see how different modules interact without the clutter of virtual environments or external libraries.
- Pydescope renders an interactive dependency map of your codebase.
- Nodes represent Python modules and packages, while
- Edges visualize the directed import relationships between them.
- The interface supports real-time filtering and neighborhood highlighting to help developers audit project coupling and structural integrity at a glance.
- Static Analysis: Scans your .py files and directories to build a map of your code.
- Smart Filtering: Automatically ignores venv, pycache, and other non-source directories.
- Interactive Graphs: Generates an HTML-based visualization where you can drag nodes, zoom, and highlight neighborhoods.
- Module Tracking: Distinguishes between package initializations (init.py) and standard module files.
- Neighborhood Highlight: Click on a node to highlight its direct dependencies and dim the rest of the graph.
- Search/Filter: Use the built-in search bar (powered by TomSelect) to find specific modules.
- Physics Toggle: Enable or disable the physics engine to stabilize the graph layout.
pydescope/
├── .gitignore # Standard git ignore rules
├── pyproject.toml # Build system and dependency configuration
├── README.md # Project documentation
├── CONTRIBUTING.md # Contributing documentation
├── LICENSE.md # License documentation
├── pydescope/ # Core logic package
│ ├── __init__.py # Package initialization
│ ├── analyzer.py # Logic for parsing imports and code analysis
│ ├── graph_builder.py # NetworkX graph construction
| ├── parser.py # Identifes .py files in projects
│ ├── renderer.py # PyVis conversion and HTML generation
│ └── utils.py # Internal helper functions
| └── cli.py # User interaction tool
└── lib/ # Static assets for the final output
└── bindings/
└── utils.js # Custom JS for highlighting and interactivity
- Pydescope is built with a modular design to ensure efficient parsing and rendering:
-
parser.py: The engine that walks through your project and identifies Python files.
-
analyser.py: Scans individual files to extract import statements and determine relationships.
-
graph_builder.py: Uses NetworkX to create a mathematical representation of the project dependency tree.
-
renderer.py: Converts the NetworkX graph into an interactive PyVis HTML file.
-
cli.py: Provides the Command Line Interface for users to interact with the tool.
Clone your repository (or navigate to the project folder):
- Prerequisites Before running Pydescope, ensure you have Python 3.9 or higher installed.
cd pydescopeThis installs the dependencies and allows you to run the pydescope command directly.
pip install -e .Once installed, you can run Pydescope from your terminal.
Point Pydescope at any Python project directory you want to analyze:
pydescope <path_to_target_project>
Command Options
Output Name: Specify a custom name for your HTML report.pydescope <path_to_project> --output my_graph.html
Exclude Directories: Although it ignores venv by default, you can add more exclusions.pydescope <path_to_project> --exclude tests,docs
Visualisation Controls
The generated HTML file includes advanced JavaScript-based controls located in the lib/bindings/utils.js file:- NetworkX Provides the data structure for the graphs and relationships between the files.
- PyVis Takes abstract math from NetworkX and converts it into a beautiful HTML/JS interface, that a user can open in a browser.
- Click Handles all CLI logic
- The project uses repomix for codebase packing and analysis.
- Static assets for the visualization (CSS/JS) are stored in the lib/ directory.
- Built by Roy Peters.😁
