Metadata-Version: 2.4
Name: py-import-cleaner
Version: 1.0.0
Summary: A production-ready CLI tool that automatically detects and removes unused imports across Python projects safely.
Author-email: Aneesh Rao <aneeshrao@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/aneeshrao/py-import-cleaner
Project-URL: Repository, https://github.com/aneeshrao/py-import-cleaner
Project-URL: Issues, https://github.com/aneeshrao/py-import-cleaner/issues
Keywords: python,linter,imports,cleanup,developer-tools
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# py-import-cleaner

A production-ready CLI tool that automatically detects and removes unused imports across Python projects safely.

## Features

- **AST-based detection** — Accurate unused import detection using Python's Abstract Syntax Tree
- **Safe removal** — Removes unused imports while preserving formatting
- **Safety rules** — Never removes imports inside `try/except ImportError` or referenced in `__all__`
- **Dry-run mode** — Preview what would be removed without making changes
- **Diff preview** — See exact changes before applying
- **Recursive scanning** — Scan entire projects with smart directory exclusion
- **Configurable** — Via `.importcleaner.toml`, `pyproject.toml`, or CLI options
- **Pre-commit integration** — Use as a pre-commit hook
- **CI-friendly** — Non-zero exit code when unused imports are found

## Installation

```bash
pip install py-import-cleaner
```

Or install from source:

```bash
git clone https://github.com/aneeshrao/py-import-cleaner.git
cd py-import-cleaner
pip install -e ".[dev]"
```

## Quick Start

### Scan for unused imports

```bash
py-import-cleaner .
```

### Remove unused imports

```bash
py-import-cleaner . --fix
```

### Preview changes (dry run)

```bash
py-import-cleaner . --dry-run
```

### Show diff of proposed changes

```bash
py-import-cleaner . --diff
```

## CLI Options

| Option | Description |
|---|---|
| `--fix` | Remove unused imports |
| `--dry-run` | Show results without changes |
| `--diff` | Show file diff of proposed changes |
| `--verbose` | Detailed logging |
| `--exclude` | Exclude directories (repeatable) |
| `--include` | Only scan selected paths (repeatable) |
| `--config` | Path to config file |

## Configuration

Create a `.importcleaner.toml` file in your project root:

```toml
[tool.importcleaner]
exclude = ["tests", "migrations"]
ignore_modules = ["typing"]
```

Or add to your existing `pyproject.toml`:

```toml
[tool.importcleaner]
exclude = ["tests", "migrations"]
ignore_modules = ["typing"]
```

## Pre-commit Integration

Add to your `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: https://github.com/aneeshrao/py-import-cleaner
    rev: v1.0.0
    hooks:
      - id: py-import-cleaner
```

## Example Output

```
3 unused imports found

accounts/views.py
  line 3: import sys

utils/helpers.py
  line 5: from datetime import datetime

Run with --fix to remove them
```

## Safety Rules

The tool will **never** remove imports that are:

- Inside `try/except ImportError` blocks (optional dependency patterns)
- Referenced in `__all__` (public API exports)

```python
# This import will NOT be removed
try:
    import uvloop
except ImportError:
    pass
```

## Library Usage

```python
from py_import_cleaner import analyze_source, fix_source

source = """
import os
import sys

print(os.getcwd())
"""

result = analyze_source(source)
for unused in result.unused_imports:
    print(f"Unused: {unused}")

fixed = fix_source(source, result)
print(fixed)
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check src/ tests/

# Run type checker
mypy src/
```

## Supported Import Types

- `import module`
- `import module as alias`
- `from module import name`
- `from module import name as alias`
- `from module import name1, name2, name3`

## Default Excluded Directories

- `.git`
- `.venv` / `venv`
- `__pycache__`
- `node_modules`
- `.mypy_cache`
- `.pytest_cache`
- `.ruff_cache`
- `.tox`
- `dist` / `build`

## Requirements

- Python >= 3.9

## License

MIT
