importlens-py 0.1.0

See exactly what your imports are doing — unused, missing, and circular import detection.

🔍 importlens

See exactly what your imports are doing — unused, missing, and circular import detection using Python's AST.

---

🤔 Why importlens?

Unused imports slow down startup time, confuse readers, and clutter code. Missing entries in requirements.txt break other people's installs. Circular imports cause cryptic runtime errors.

importlens catches all three — using Python's own ast module, no external dependencies needed.

importlens scan ./myproject

  📄 api.py
     🔴 unused   line 1    import json
     🔴 unused   line 3    requests

  📄 utils.py
     🔴 unused   line 2    pathlib.Path as p

  🟡 Packages used but not in requirements.txt:
     ❌ httpx

  🔄 Circular imports detected:
     🔄 models.py → db.py → models.py

  ──────────────────────────────────────────────────
  📊 Scanned 8 file(s) | 34 import(s) | 3 unused

---

📦 Installation

pip install importlens

---

🚀 Usage

CLI

# Scan current directory
importlens scan .

# Scan a specific folder
importlens scan ./myproject

# Scan a single file
importlens scan app.py

# Skip certain checks
importlens scan . --no-circular
importlens scan . --no-unused
importlens scan . --no-missing

# Specify requirements file
importlens scan . --req requirements-dev.txt

Library

from importlens import scan_file, scan_directory

# Scan a single file
report = scan_file("app.py")
print(report.imports)   # all imports
print(report.unused)    # unused imports
print(report.used)      # used imports

# Scan a whole directory
reports = scan_directory("./myproject")
for report in reports:
    if report.unused:
        print(f"{report.filepath}: {len(report.unused)} unused imports")

---

🔍 What importlens detects

import os                        # ✅ detects
import numpy as np               # ✅ detects alias
from pathlib import Path         # ✅ detects
from os.path import join as pj   # ✅ detects alias
from typing import List, Dict    # ✅ detects multiple

---

🆚 importlens vs flake8/pylint

Feature	importlens	flake8	pylint
Unused imports	✅	✅	✅
Circular imports	✅	❌	✅
Missing in requirements.txt	✅	❌	❌
Zero dependencies	✅	❌	❌
Beginner-friendly output	✅	⚠️	⚠️

---

🧪 Running Tests

pip install pytest
pytest tests/ -v

---

📄 License

MIT — free to use in personal and commercial projects.