local-package-visualizer 0.1.3

Local package dependency visualizer tool

📦 Local Package Dependency Visualizer (LPV)

LPV is a Python command-line tool that analyzes a project’s import structure and builds a complete dependency graph. It detects cycles, dead code, oversized modules, risky dynamic imports, and generates ASCII or Graphviz visualizations.

This tool is designed for developers who want fast, accurate insights into Python project architecture — ideal for refactoring, debugging, and CI automation.

---

🚀 Features

• AST-based Parsing
• Dependency Graph Construction
• Cycle Detection (DFS)
• Dead Code Detection (BFS)
• Oversized Module Detection
• Module Split Suggestions
• Dynamic Import Warnings
• ASCII Visualization
• Graphviz Export (DOT, PNG, SVG, PDF)
• Fast & Lightweight

---

📁 Project Structure

lpv/
│
├── parser/
│   ├── ast_parser.py
│   ├── import_resolver.py
│   ├── graph_builder.py
│   └── dynamic_import_detector.py
│
├── analyzer/
│   ├── cycle_detector.py
│   ├── dead_code_detector.py
│   ├── module_analyzer.py
│   ├── split_suggester.py
│   └── visualizer.py
│
├── cli.py
└── README.md

---

📦 Installation

Requirements

• Python 3.7+
• Optional: Graphviz

Install from PyPI:

pip install lpv

Install locally:

pip install -e .

---

🛠 CLI Usage (Using lpv)

Basic:

lpv .

Detect cycles:

lpv . --cycles

ASCII Map:

lpv . --ascii

Graphviz Export:

lpv . --graphviz deps.dot

---

🔥 Complete CLI Command Reference (Using lpv)

Basic Analysis

lpv .

Show Summary

lpv . --summary

Detect Circular Imports

lpv . --cycles

Detect Dead Code

lpv . --dead-code

Detect Dynamic Imports

lpv . --dynamic-imports

ASCII Dependency Map

lpv . --ascii

ASCII Map With Depth Limit

lpv . --ascii --max-depth 4

Oversized Modules (default: 500 lines)

lpv . --oversized 500

Module Split Suggestions

lpv . --suggest-splits

Export Graph as DOT

lpv . --graphviz deps.dot

Export Graph as PNG

lpv . --graphviz deps.png --format png

Exclude Folders (venv, env, dist, build…)

lpv . --exclude venv env dist build

Full Project Audit

lpv . --cycles --dead-code --dynamic-imports --oversized 500 --suggest-splits --ascii --summary

---

🧪 Sample Project Demo

lpv tests/sample_project \
  --cycles \
  --dead-code \
  --oversized 150 \
  --suggest-splits \
  --dynamic-imports \
  --ascii \
  --summary

Or run:

bash tests/run_sample_demo.sh

---

📌 Examples

Circular Dependencies

⚠️  CIRCULAR DEPENDENCIES DETECTED:
  Cycle 1: a.py → b.py → c.py → a.py
  Cycle 2: utils.py → helpers.py → utils.py

Oversized Modules

⚠️  OVERSIZED MODULES (> 300 lines):
  - parser/ast_parser.py : 450
  - analyzer/visualizer.py : 380
  - main.py : 320

Split Suggestions

💡 MODULE SPLIT SUGGESTIONS:

parser/ast_parser.py:
  - Suggest splitting by class groups
  Reason: Contains 5 unrelated class groups

ASCII Map

lpv . --ascii --max-depth 4

PNG Export

lpv . --graphviz deps.png --format png

---

🔗 Pre-commit Integration

Add this:

repos:
  - repo: local
    hooks:
      - id: dependency-check
        name: Check for circular dependencies
        entry: lpv
        language: system
        args: ['.', '--cycles']
        pass_filenames: false
        always_run: true

---

⚙ Algorithms

Feature	Algorithm
Cycle Detection	DFS + recursion stack
Dead Code Detection	BFS reachability
Graph Builder	Directed adjacency graph
Split Suggestions	Heuristic clustering

---

⏱ Performance

• Time: O(V + E)
• Space: O(V + E)
• Handles hundreds of files efficiently

---

⚠ Limitations

• Dynamic imports detected but not resolved
• Dead code detection is heuristic
• External packages not resolved
• Split suggestions are heuristic

---

📄 License

Educational use only.

---

👥 Authors

• Sagar Veeresh Halladakeri — 251810700276
• Nesar Ravishankar Kavri — 251810700211
  Group 127

---

✔ Required PyProject Configuration

Ensure your pyproject.toml includes:

[project.scripts]
lpv = "cli:main"

This enables the lpv command globally.