Metadata-Version: 2.4
Name: importlens-py
Version: 0.1.0
Summary: See exactly what your imports are doing — unused, missing, and circular import detection.
License: MIT
Project-URL: Homepage, https://github.com/yourusername/importlens
Project-URL: Issues, https://github.com/yourusername/importlens/issues
Keywords: imports,linter,ast,unused,circular,devtools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# 🔍 importlens

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

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 🤔 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.

```bash
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

```bash
pip install importlens
```

---

## 🚀 Usage

### CLI
```bash
# 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
```python
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

```python
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

```bash
pip install pytest
pytest tests/ -v
```

---

## 📄 License

MIT — free to use in personal and commercial projects.
