pymport 0.0.3

A lightweight Python linter for checking unused docstrings.

pymport

About

A lightweight Python linter for checking unused imports in your Python files.

Features

• 🧹 Detects unused or shadowed imports that linters like ruff may miss
• 🚫 Use noqa comments to ignore imports you want to keep
• ⚙️ Minimalist CLI interface for easy integration in CI/CD pipelines
• 🐍 No external dependencies beyond the Python standard library
• ✅ 100% test coverage with automated tests

[!IMPORTANT] False positives

This tool is not possible to assure a 100% false positive free result due to the possible collateral execution effects when importing a module. This is, importing a module can affect or enable some feature needed somewhere else, so not using anything from that imported package/module does not necessarily mean is not needed.

A minimal typical example could be:

import os.path

print(os.curdir)

📦 Installation

To install pymport using pip, run the following command:

pip install pymport --upgrade

⚡ Quick Start

To run the linter on the current directory, use the following command:

pymport .

• This will check all Python files in the current directory and its subdirectories.

Command-Line Interface

Usage: pymport [FILE] [--help] [--quiet] [--ignore=DIR]

Argument / Option	Description
[FILE]	Files or directories to lint. (Need at least one file or dir to check.)
[--help]	Show help message and exit.
[--quiet]	Decrease verbosity.
[--ignore]	Directory basename to ignore. Can be used multiple times.

[!NOTE]

Option --ignore defaults to: .venv, .env, .git, .hg, .pytest_cache, .ruff_cache, __pycache__

[!TIP] Ignoring Unused Imports

Use a comment like # noqa: unused-import to ignore the line.

Output

When unused imports are detected, they will be reported in the following format:

path/to/file.py:LINE-NUMBER: UNUSED-IMPORT-NAME

[!NOTE]

• Exit code 0 means no unused imports were found; exit code 1 indicates that unused imports were detected.
• When no unused imports are found, success message is printed, unless --quiet is used.

🛠️ Development

To contribute to the project, you can run the following commands for testing and documentation:

First, ensure you have the latest version of pip:

python -m pip install --upgrade pip

Running Tests

pip install --group=test --upgrade # Install test dependencies, skip if already installed
python -m pytest tests/ # Run all tests
python -m pytest tests/ --cov # Run tests with coverage

Running Linter

pip install --group=lint --upgrade  # Install lint dependencies, skip if already installed
ruff check . # Run linter

🗒️ License

This project is licensed under the MIT license.