importdoc

Production-Ready Import Diagnostic Tool for Python

Advanced Python import diagnostic tool with deep analysis, subprocess isolation, auto-fixing suggestions, and CI-ready enforcement.

⚡ Quick Start (The "5-Minute Rule")

Prerequisites

• Python: 3.10+
• Dependencies: jsonschema, tqdm, rich (installed automatically)

Install

pip install importdoc

Run

To start diagnosing your package immediately:

importdoc <your_package_name>

Demo

Copy and paste this snippet to audit your package and generate a visual report:

# Install importdoc
pip install importdoc

# Run a full diagnostic check with verbose output
importdoc my_awesome_package --verbose

# Generate an interactive HTML graph of your import structure
importdoc my_awesome_package --html

✨ Features

Core Capabilities

• Import Graph Discovery: Recursively maps and validates imports across your entire project.
• Subprocess Isolation: Imports each module in a sandboxed subprocess to prevent crashes and ensure timeout safety.
• Circular Dependency Detection: Identifies dependency cycles with detailed stack traces.

Performance & Security

• Smart Caching: Speeds up subsequent runs by caching analysis results (--enable-cache).
• Parallel Execution: runs imports in parallel for large codebases (--parallel).
• Safe Mode: Enforces execution within a virtual environment to prevent system pollution.

Advanced Analysis

• Auto-Fix Suggestions: Suggests proper import paths and generates JSON patches for auto-fixing errors.
• AST-Based Resolution: "God Level" analysis parses source code to find undefined symbols and correct import paths.
• Interactive Reports: Generates self-contained HTML reports for exploring import graphs visually.
• CI-Ready JSON: Provides structured JSON output for easy integration with CI/CD pipelines.

🛠️ Configuration

You can configure importdoc using CLI arguments or a configuration file (pyproject.toml or .importdoc.rc).

CLI Arguments

Configuration File (pyproject.toml)

You can persist your configuration in pyproject.toml under the [tool.importdoc] section:

[tool.importdoc]
verbose = true
timeout = 5
enable_cache = true
exclude_patterns = ["tests/*", "migrations/*"]

🏗️ Architecture

Directory Tree

src/
└── importdoc/
    ├── cli.py             # CLI Entry Point
    ├── banner.py          # Logo & Branding
    └── modules/
        ├── diagnostics.py # Core Controller (Orchestrator)
        ├── discovery.py   # File & Module Discovery
        ├── runner.py      # Subprocess Execution Logic
        ├── analysis.py    # AST & Error Analysis
        ├── reporting.py   # JSON/HTML/Console Output
        ├── config.py      # Configuration Loader
        ├── cache.py       # Caching Mechanism
        ├── autofix.py     # Fix Generation Logic
        └── ...

High-Level Flow

1. CLI: Parses arguments and loads configuration.
2. Discovery: Scans the file system to find all Python modules in the target package.
3. Runner: Iterates through discovered modules, spawning isolated subprocesses to import them safely.
4. Analysis: Captures stdout/stderr from subprocesses. If an import fails, analysis.py inspects the error and AST to determine the root cause (e.g., circular dependency, missing symbol).
5. Reporting: Aggregates results and outputs them to the console, JSON file, or HTML report.

🐞 Troubleshooting

Common Issues

Debug Mode

If you are facing unexpected behavior, enable verbose logging and developer traces:

importdoc my_package --verbose --dev-mode --dev-trace

🤝 Contributing

We welcome contributions! Please check out our CONTRIBUTING.md (if available) or follow the steps below.

Dev Setup

1. Clone the repository:

   git clone https://github.com/dhruv13x/importdoc.git
   cd importdoc
   

2. Install dependencies:

   pip install .[dev]
   

3. Run Tests:

   python -m pytest
   

🗺️ Roadmap

We are constantly improving importdoc. Here is a glimpse of what's coming:

• Phase 1 (Done): Subprocess isolation, Circular dependency detection, JSON/HTML output.
• Phase 2 (Current): Performance optimization (Caching, Parallelism), Configuration files.
• Phase 3 (Next): Plugin architecture, IDE integrations (VS Code), GitHub Actions support.
• Phase 4 (Vision): AI-powered architectural refactoring and predictive dependency analysis.

See ROADMAP.md for the full detailed plan.