Skip to main content

PyPI version Python versions CI License: MIT

minport

A Python linter that finds unnecessarily long import paths and suggests shorter alternatives by tracing re-export chains.

The Problem

Python packages expose public APIs through re-exports, but developers often import from deep internal paths instead of the canonical public interface:

# Unnecessarily long — these reach into internal modules
from pydantic.fields import FieldInfo
from sqlalchemy.orm.session import Session
from myproject.domain.user.models import User

# Shorter — these use the public re-export path
from pydantic import FieldInfo
from sqlalchemy.orm import Session
from myproject.domain import User

Long import paths are:

  1. Harder to read: Internal paths obscure the public interface
  2. Fragile: Internal paths break when package maintainers refactor internals (re-exports are the stable API)
  3. Inconsistent: Same name imported from different paths across the codebase

Installation

pip install minport
# or with uv
uv add --dev minport
# or with pipx (for global CLI usage)
pipx install minport

Requirements: Python 3.11+ / No runtime dependencies.

Quick Start

minport check src/
# src/models.py:3:1: MP001 `from pydantic.fields import FieldInfo` can be shortened to `from pydantic import FieldInfo`
# Found 1 error (checked 12 files, 1 fixable with `minport check --fix`).

minport check src/ --fix
# Found 1 error (checked 12 files, fixed 1 in 1 file).

Usage

minport check src/                       # Check a directory
minport check src/models.py              # Check a single file
minport check src/ --src src/            # Set import resolution root
minport check src/ --exclude "tests/*"   # Exclude patterns (overrides defaults)
minport check src/ --extend-exclude "generated/*"  # Add to default excludes
minport check src/ --config path/to/pyproject.toml  # Custom config path
minport check src/ --fix                 # Auto-fix in place
minport check src/ --quiet               # Suppress the summary line
minport check src/ --output-format github  # output for github annotations
minport check src/ --no-cache            # Disable the persistent cache for this run

Exit codes: 0 = no violations, 1 = violations found, 2 = error (e.g. path not found).

Configuration

Configure minport in pyproject.toml:

[tool.minport]
src = ["src"]                        # Import resolution root(s)
exclude = ["tests/*", "migrations/*"]  # Exclude patterns (overrides defaults)
extend-exclude = ["generated/*"]     # Add patterns without overriding defaults

CLI arguments override pyproject.toml settings.

Default Excludes

minport automatically skips common non-source directories (.venv, __pycache__, .git, node_modules, dist, site-packages, etc.). Use --exclude to override these defaults entirely, or --extend-exclude to add patterns on top of them.

Environment Variables

Variable Effect
MINPORT_NO_CACHE=1 Skip the persistent find_spec cache (same as --no-cache).
MINPORT_CACHE_DIR=<path> Override the cache root. Defaults to $XDG_CACHE_HOME/minport or ~/.cache/minport.
XDG_CACHE_HOME=<path> Standard XDG base dir; minport stores the cache under <path>/minport.

The persistent cache is invalidated by content hash of the project's lock file (uv.lock, poetry.lock, Pipfile.lock, requirements.lock, requirements.txt, or pyproject.toml — first one found, in that order). Changing dependencies switches the cache to a fresh file; the previous one is left untouched.

Rules

Code Name Description Fixable
MP001 shorter-import-available A shorter import path is available via re-exports Yes

Inline Suppression

Add # minport: ignore to suppress violations on specific imports.

Single-line import:

from pydantic.fields import FieldInfo  # minport: ignore

Multi-line import — suppress all names:

from pydantic.fields import (  # minport: ignore
    FieldInfo,
    Field,
)

Multi-line import — suppress a specific name:

from pydantic.fields import (
    FieldInfo,  # minport: ignore  ← only FieldInfo is suppressed
    Field,      # ← this can still be flagged
)

How It Works

For each from X.Y.Z import Name:

  1. Decompose the module path: [X, X.Y, X.Y.Z]
  2. For each candidate path (shortest first), check if Name is re-exported there
  3. Re-export detection via AST analysis of __init__.py:
    • from .submodule import Name — explicit re-export
    • from .submodule import Name as Name — PEP 484 explicit form
    • from .submodule import * — wildcard (recursively resolved, respects __all__)
    • __all__ = ["Name", ...] — public API declaration
  4. Return the shortest match (if shorter than the original)

Works with both project packages (analyzes __init__.py files) and third-party packages (uses importlib.util.find_spec + AST analysis, no runtime imports).

Safety

  • No modifications without --fix: Read-only by default
  • Collision detection: If a name exists in multiple candidate paths, the import is not flagged
  • Syntax error tolerance: Malformed Python files are skipped with a warning
  • --fix writes in place: Always verify changes with git diff before committing

Integrations

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: minport
        name: minport
        entry: minport check
        language: python
        types: [python]
        additional_dependencies: ["minport"]

GitHub Actions

# .github/workflows/lint.yml
jobs:
  minport:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.13"
      - uses: actions/cache@v4
        with:
          path: ~/.cache/minport
          key: minport-${{ runner.os }}-${{ hashFiles('**/uv.lock') }}
          restore-keys: minport-${{ runner.os }}-
      - run: pip install minport
      - run: minport check src/ --output-format github

The --output-format github flag emits GitHub Actions workflow commands, so violations appear as inline annotations on the PR file view. The actions/cache step persists ~/.cache/minport across runs so the second invocation skips re-resolving third-party packages.

Limitations

  • Only rewrites from X.Y.Z import Name (not import X.Y.Z)
  • Does not analyze dynamic or runtime imports
  • No IDE integration yet

Contributing

git clone https://github.com/KinjiKawaguchi/minport.git
cd minport
uv sync
uv run pytest --cov=minport
uv run ruff check src/ tests/
  • DeepWiki — AI-generated codebase documentation

License

MIT

Metadata

Release files for minport 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for minport 0.3.1
File Size Uploaded Provenance Actions
minport-0.3.1.tar.gz 181.1 kB With provenance Details for minport-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for minport 0.3.1
File Interpreter ABI Platform Actions
minport-0.3.1-py3-none-any.whl Python 3 none any Details for minport-0.3.1-py3-none-any.whl

Total release size: 214.1 kB

Release files / minport-0.3.1.tar.gz

Download URL minport-0.3.1.tar.gz
Size 181.1 kB
Tags Source
SHA-256 checksum
How to use checksums
cc66509ce9bb780cd86380ee42153002fd92c0bb81e5450992fa9c8d24bc06b5
BLAKE2b-256 checksum
How to use checksums
fab64dfea3a9a6b129206bbfae011c2db6ed6c3cff1262b4174c8feb787ee6df
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 11, 2026.

Transparency log

Release files / minport-0.3.1-py3-none-any.whl

Download URL minport-0.3.1-py3-none-any.whl
Size 33.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2696177a2be7983837c740788ce68376095f8b28cc9ccfa4ce4ddcb45f3dbade
BLAKE2b-256 checksum
How to use checksums
8494d5212c36b4ea9a58c040692d76dbb01fb6df723017e79c98822382227443
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 11, 2026.

Transparency log

Security for minport 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for minport-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page