Python Import Dependency Analyzer

A powerful tool for analyzing Python file import dependencies using AST parsing and BFS traversal. Perfect for understanding complex codebases and detecting import cycles.

Quick Start

# Analyze dependencies starting from a Python file
python import_dependency_analyzer.py my_module.py

# Simple file listing
python import_dependency_analyzer.py my_module.py -s

# Claude Code optimized output
python import_dependency_analyzer.py my_module.py -c

# Machine-readable JSON output
python import_dependency_analyzer.py my_module.py -m

Table of Contents

• Features
• Installation
• Usage
• Examples
• Technical Implementation
• Contributing
• License

Installation

From Source

git clone https://github.com/your-username/import-dependency-analyzer.git
cd import-dependency-analyzer
python import_dependency_analyzer.py your_file.py

Using pip (Local Installation)

# Install from local directory
pip install .

# Now you can use either command:
import-dependency-analyzer your_file.py
# or the short alias:
ida your_file.py

Using pip (When Published to PyPI)

pip install import-dependency-analyzer
import-dependency-analyzer your_file.py
# or use the short alias:
ida your_file.py

Features

• Supports import module and from module import name statements
• Breadth-first traversal (BFS) of dependencies
• Automatic cycle detection to prevent infinite traversal
• List format output
• Ignores standard library and third-party packages, only analyzes local modules
• Handles relative imports and subdirectory modules

Usage

Basic Usage (After pip installation)

# Using full command name
import-dependency-analyzer <start_file>

# Using short alias
ida <start_file>

Simple Mode

import-dependency-analyzer <start_file> -s
# or
ida <start_file> -s

Claude Code Mode

import-dependency-analyzer <start_file> -c
# or
ida <start_file> -c

Machine Readable Mode

import-dependency-analyzer <start_file> -m
# or
ida <start_file> -m

Command Line Arguments

• start_file: Starting Python file path (required)
• -s, --simple: Simple mode: list all files without showing dependencies
• -c, --claude-code: Claude Code mode: optimized output for Claude Code
• -m, --machine-readable: Machine readable mode: output in JSON format
• -h, --help: Show help message

Examples

Space Exploration Example

The tool comes with a complete space exploration example in the space_exploration directory:

space_exploration/
├── mission_control.py          # Main entry point
├── spacecraft.py               # Main spacecraft class
├── navigation.py               # Navigation system
├── communication.py            # Communication system
├── science.py                  # Science module
├── systems/                    # Subsystems
│   ├── propulsion.py
│   ├── power.py
│   └── life_support.py
├── utils/                      # Utility modules
│   ├── coordinates.py
│   └── calculations.py
├── protocols/                  # Communication protocols
│   ├── radio.py
│   └── laser.py
├── instruments/                # Scientific instruments
│   ├── telescope.py
│   └── spectrometer.py
└── data/                       # Data analysis
    └── analysis.py

Run command (after pip installation):

ida space_exploration/mission_control.py
# or
import-dependency-analyzer space_exploration/mission_control.py

Output (partial):

Python Import Dependencies:
==================================================

D:\tools\import_tool\space_exploration\mission_control.py:
  └── D:\tools\import_tool\space_exploration\spacecraft.py
  └── D:\tools\import_tool\space_exploration\navigation.py
  └── D:\tools\import_tool\space_exploration\communication.py
  └── D:\tools\import_tool\space_exploration\science.py

D:\tools\import_tool\space_exploration\spacecraft.py:
  └── D:\tools\import_tool\space_exploration\systems\propulsion.py
  └── D:\tools\import_tool\space_exploration\systems\power.py
  └── D:\tools\import_tool\space_exploration\systems\life_support.py

D:\tools\import_tool\space_exploration\navigation.py:
  └── D:\tools\import_tool\space_exploration\utils\coordinates.py
  └── D:\tools\import_tool\space_exploration\utils\calculations.py

... (continues through all dependencies)

Run in simple mode:

ida space_exploration/mission_control.py -s

Output:

Python Files List:
==================================================
D:\tools\import_tool\space_exploration\mission_control.py
D:\tools\import_tool\space_exploration\spacecraft.py
D:\tools\import_tool\space_exploration\navigation.py
D:\tools\import_tool\space_exploration\communication.py
D:\tools\import_tool\space_exploration\science.py
D:\tools\import_tool\space_exploration\systems\propulsion.py
D:\tools\import_tool\space_exploration\systems\power.py
D:\tools\import_tool\space_exploration\systems\life_support.py
D:\tools\import_tool\space_exploration\utils\coordinates.py
D:\tools\import_tool\space_exploration\utils\calculations.py
D:\tools\import_tool\space_exploration\protocols\radio.py
D:\tools\import_tool\space_exploration\protocols\laser.py
D:\tools\import_tool\space_exploration\instruments\telescope.py
D:\tools\import_tool\space_exploration\instruments\spectrometer.py
D:\tools\import_tool\space_exploration\data\analysis.py

Run in Claude Code mode:

ida space_exploration/mission_control.py -c

Output (partial):

# Python Import Dependency Analysis

## Summary
- Total files analyzed: 15
- Files with dependencies: 5
- Files without dependencies: 10

## Dependency Graph

### mission_control.py
File: `D:\tools\import_tool\space_exploration\mission_control.py`
**Imports:**
- `spacecraft.py` (`D:\tools\import_tool\space_exploration\spacecraft.py`)
- `navigation.py` (`D:\tools\import_tool\space_exploration\navigation.py`)
- `communication.py` (`D:\tools\import_tool\space_exploration\communication.py`)
- `science.py` (`D:\tools\import_tool\space_exploration\science.py`)

... (continues with all files)

Run in machine readable mode:

ida space_exploration/mission_control.py -m

Output (partial):

{
  "summary": {
    "total_files": 15,
    "files_with_dependencies": 5,
    "files_without_dependencies": 10
  },
  "dependency_graph": {
    "D:\\tools\\import_tool\\space_exploration\\mission_control.py": {
      "basename": "mission_control.py",
      "dependencies": [
        "D:\\tools\\import_tool\\space_exploration\\spacecraft.py",
        "D:\\tools\\import_tool\\space_exploration\\navigation.py",
        "D:\\tools\\import_tool\\space_exploration\\communication.py",
        "D:\\tools\\import_tool\\space_exploration\\science.py"
      ],
      "dependency_count": 4
    },
    ... (continues with all files)
  }
}

Technical Implementation

• Uses Python's ast module to parse Python file syntax trees
• Breadth-first traversal (BFS) algorithm for dependency traversal
• Uses sets to track visited nodes and prevent cycles
• Simple list format output for clarity

Limitations

• Currently supports relative imports (e.g., from .module import name)
• Analyzes Python files in current directory and subdirectories
• Ignores Python standard library and third-party packages

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to get started.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.