Metadata-Version: 2.4
Name: import-cruiser
Version: 0.2.38
Summary: Analyze, validate, and visualize Python import dependencies — like dependency-cruiser for Python.
License: MIT
Author: kevin91nl
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
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: Programming Language :: Python :: 3.14
Requires-Dist: click (>=8.1,<9.0)
Requires-Dist: tomli (>=2.0,<3.0)
Description-Content-Type: text/markdown

# import-cruiser

[![PyPI version](https://img.shields.io/pypi/v/import-cruiser.svg)](https://pypi.org/project/import-cruiser/)
[![Python versions](https://img.shields.io/pypi/pyversions/import-cruiser.svg)](https://pypi.org/project/import-cruiser/)
[![Workflow](https://github.com/kevin91nl/import-cruiser/actions/workflows/workflow.yml/badge.svg?branch=main)](https://github.com/kevin91nl/import-cruiser/actions/workflows/workflow.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](#license)

Analyze, validate, and visualize Python import dependencies.

`import-cruiser` helps you quickly answer:
- Where are tight couplings?
- Are there circular imports?
- Are architecture rules respected?

## Why teams use it

- Fast graph export to `html`, `svg`, and `dot`
- Rule-based validation for CI (`validate --strict`)
- Readable interactive HTML output for architecture reviews
- Works out of the box on regular Python codebases

## See it in action: project self-graph

Dependency graph of `src/import_cruiser`, generated by the tool itself:

![import-cruiser self graph](./artifacts/self-graph/import-cruiser-self-graph.svg)

Run `make self-graph` to refresh these artifacts—the script passes `--show-loc` so clusters include LOC badges in the DOT/HTML/SVG exports (with `--cluster-mode module --cluster-depth 1`, the self-graph renders a single top-level `import_cruiser` cluster and skips the `src` path layer).
The target also passes `--include-external-deps`, so non-dev third-party packages render as a grouped green block labeled “External dependencies” (without LOC badges). External roots are read from both `tool.poetry.dependencies` and `project.dependencies`.

## Install

```bash
pip install import-cruiser
```

## 60-second quick start

From your repo root:

```bash
# 1) Generate an interactive dependency graph
import-cruiser export . --format html --output deps.html

# 2) Generate an embeddable SVG
import-cruiser export . --format svg --output deps.svg

# 3) Detect cycles and get a JSON report
import-cruiser analyze . --output report.json
```

For larger repos, filter noise:

```bash
import-cruiser export . \
  --format html \
  --include-path '^src/' \
  --exclude-common-noise-paths \
  --output deps-src.html
```

## Commands

```text
import-cruiser analyze  <path>   # analyze imports, output json/dot/svg/html
import-cruiser export   <path>   # export graph dot/svg/html
import-cruiser validate <path>   # enforce dependency rules
```

## Most useful options

- `--format {json,dot,svg,html}`
- `--include`, `--exclude`
- `--include-path`, `--exclude-path`
- `--exclude-common-noise-paths`
- `--cluster-depth`, `--cluster-mode`
- `--include-db-connectors`, `--include-http-hosts`
- `--show-loc` to show LOC per node/cluster and total LOC badge in HTML
- `--include-external-deps` to surface non-dev third-party packages as grouped green nodes (auto-enabled in the self-graph)
- `--external-deps-include`, `--external-deps-exclude` to filter which external dependency roots are surfaced

## Validate architecture in CI

Minimal `import-cruiser.json` example:

```json
{
  "rules": [
    {
      "name": "no-data-to-ui",
      "severity": "error",
      "from": { "path": "\\.data" },
      "to": { "path": "\\.ui" },
      "allow": false
    }
  ]
}
```

Run in CI:

```bash
import-cruiser validate . --config import-cruiser.json --strict --output-format github
```

## Development

```bash
poetry install
poetry run pytest
```

## License

MIT

