Metadata-Version: 2.4
Name: importy
Version: 0.1.0
Summary: Visualize Python import graphs
Author: theveryheavy
License-Expression: MIT
Keywords: python,imports,dependency-graph,cli,architecture
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# importy

[![PyPI Version](https://img.shields.io/pypi/v/importy.svg)](https://pypi.org/project/importy/)
[![Python Versions](https://img.shields.io/pypi/pyversions/importy.svg)](https://pypi.org/project/importy/)
[![License](https://img.shields.io/pypi/l/importy.svg)](https://pypi.org/project/importy/)
[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/importy/)
[![Downloads (Month)](https://img.shields.io/pepy/dm/importy.svg)](https://pepy.tech/project/importy)
[![Downloads (Total)](https://img.shields.io/pepy/dt/importy.svg)](https://pepy.tech/project/importy)

`importy` is a Python CLI that makes import dependencies visible.

It statically analyzes `.py` files, builds a dependency graph, highlights architecture risks, and can profile real import startup time.

## Why use it

- See what your code actually depends on
- Understand unfamiliar projects faster
- Catch circular dependencies early
- Find refactor hotspots (high fan-out/hub modules)
- Profile import startup cost in milliseconds

## Visual preview

### Graph mode

```text
╭─ pyimports summary ─╮
│ Files        27     │
│ Imports      132    │
│ Local        41     │
│ Stdlib       28     │
│ Third-party  6      │
│ Unresolved   57     │
╰─────────────────────╯
app\main.py
├── app.api.main (local)
├── app.core.config (local)
├── fastapi (third_party)
└── sentry_sdk (third_party)
```

### Doctor mode

```text
╭──── pyimports doctor ────╮
│ Dependency health report │
╰──────────────────────────╯
High: No local circular dependencies detected
Medium: 57 unresolved imports across 23 files
Info: Most used third-party imports
Suggestion: Files with high dependency fan-out
Architecture: Top directory layers in scan
```

## Installation

```bash
pip install importy
```

For development:

```bash
pip install -e .[dev]
```

## Commands

### `graph`

Scan a file or directory and print dependency tree or JSON.

```bash
importy graph path/to/file_or_dir
importy graph path/to/dir --format json
importy graph path/to/app --project-root path/to/repo_root
```

### `cycles`

Detect circular local dependencies.

```bash
importy cycles path/to/dir --project-root path/to/repo_root
```

`cycle` is also supported as an alias.

### `doctor`

Print a prioritized dependency health report.

```bash
importy doctor path/to/dir --project-root path/to/repo_root
```

### `why`

Find who imports a module.

```bash
importy why app.models path/to/dir --project-root path/to/repo_root
```

### `time`

Profile real import startup cost with Python `-X importtime`.

```bash
importy time path/to/entry.py --top 20
```

## Notes on accuracy

- `local` / `third_party` classification depends on interpreter environment.
- Use `--project-root` for monorepos or nested app layouts.
- `time` runs real imports and requires target dependencies installed.

## Roadmap

- `doctor --json` for CI integration
- Better local-path resolution in graph tree annotations
- Layering policy checks (example: `api -> service -> db`)
- Lazy import suggestion mode
