py-lean

Detect and fix missing source-exclude patterns in Python projects built with uv_build.

py-lean is a Python counterpart to cargo-lean. It checks the source-distribution configuration in pyproject.toml so repository-only files don't unnecessarily end up in published archives.

Why?

A Python package's source repository often contains more than consumers need to install and use it. Tests, CI workflows, development configuration, and other repository-specific files can add unnecessary noise and size to source distributions.

py-lean helps make distribution contents intentional by identifying common repository artefacts that are missing from tool.uv.build-backend.source-exclude. It can also add the missing patterns to pyproject.toml.

Your working repository remains intact: py-lean configures what is excluded from the built source distribution; it does not delete those files from your project.

Features

• Lint — Detect common repository artefacts that are not listed in source-exclude.
• Create — Add a source-exclude configuration for detected artefacts.
• Update — Add missing exclusion patterns to an existing configuration.
• Preview changes — Use --dry-run and --diff to review proposed edits before applying them.
• Machine-readable output — Emit lint results as JSON.

Requirements

• Python 3.11 or newer
• uv and a project using the uv_build build backend

Required build-system configuration

py-lean manages tool.uv.build-backend.source-exclude, which is a uv_build configuration. The target project must therefore use uv_build as its build backend for this setting to apply.

For example, the target project's pyproject.toml should include:

[build-system]
requires = ["uv_build"]
build-backend = "uv_build"

If the project uses a different build backend, py-lean's source-exclude configuration will not control that backend's source-distribution contents.

Installation

Install with uv:

uv tool install py-lean-package

Or install from source:

git clone https://github.com/raphaelstolt/py-lean.git
cd py-lean
uv sync
uv run --project . py-lean --help

Usage

Lint

Check for missing patterns in source-exclude:

py-lean lint

Options:

Flag	Description
-m, --manifest-path <PATH>	Path to pyproject.toml (default: pyproject.toml)
--format <text|json>	Output format (default: text)
-p, --patterns <PATTERNS>	Space-separated artefact patterns to check, e.g., "tests/ benchmarks/"
--dry-run	Show what would be done without making changes
--diff	Show a diff of the proposed changes

Examples:

# Lint with JSON output
py-lean lint --format json

# Use a custom manifest path
py-lean lint -m path/to/pyproject.toml

# Check selected artefact patterns
py-lean lint -p "tests/ benchmarks/"

Create

Create a tool.uv.build-backend.source-exclude configuration containing common repository artefacts:

py-lean create

This scans the project for common artefacts, such as tests/, docs/, and .git/, and adds the detected patterns to pyproject.toml.

Options:

Flag	Description
--dry-run	Preview changes without modifying files
--diff	Show a unified diff of the proposed changes

Update

Add missing patterns to an existing source-exclude configuration:

py-lean update

Options:

Flag	Description
--dry-run	Preview changes without modifying files
--diff	Show a unified diff of the proposed changes

Examples:

# Preview changes
py-lean update --dry-run --diff

# Apply changes
py-lean update

Configuration

Pattern precedence

py-lean determines which artefact patterns to check using the following precedence:

1. CLI --patterns — highest priority; replaces other pattern sources.
2. tool.uv.build-backend.source-exclude in pyproject.toml — patterns already configured for the build backend.
3. Built-in defaults — used when neither of the above is configured.

Use --patterns to override the default patterns:

py-lean lint -p "tests/ benchmarks/"

Default artefact patterns

By default, py-lean checks for these 20 patterns:

tests/, docs/, dist/, build/, htmlcov/,
.venv/, __pycache__/, .tox/, .mypy_cache/, .pytest_cache/, .github/,
.idea/, .vscode/, .vs/, .ruff_cache/,
*.egg-info, .DS_Store, *.pyc, *.pyo, .coverage

Note: .git is not included as it is automatically excluded by build backends.

Override them with --patterns:

py-lean lint -p ".idea/ __pycache__/"

TOML configuration files

In addition to the default artefact patterns, py-lean automatically detects TOML configuration files at the project root (e.g., .ruff.toml, mypy.toml) and checks whether they are listed in source-exclude. pyproject.toml is always excluded from this check, as it is the main project file.

TOML files covered by .gitignore are skipped. You can exclude all TOML configs at once by adding *.toml to source-exclude, or list individual files.

CI integration

Add py-lean to your CI pipeline to ensure that source-exclude patterns are kept up to date:

- name: Install py-lean
  run: uv tool install py-lean-package

- name: Check source-exclude patterns
  run: py-lean lint

Failing the build when patterns are missing prevents repository artefacts from ending up in published distributions.

AI disclaimer

This package is developed with the assistance of Artificial Intelligence (AI). AI tools are used throughout the development process, including code generation, documentation, testing, and maintenance.

While reasonable care is taken to review and validate AI-generated contributions, AI-generated code is not inherently correct, secure, or free of defects. All contributions remain subject to human review and project quality standards.

As with any software, use this package at your own risk. No guarantee is made regarding its fitness for a particular purpose, and the maintainers assume no liability for damages resulting from its use.

Development

See CONTRIBUTING.md for development instructions.

License

This project is licensed under the MIT License. See LICENSE.md for details.

Related projects

• lean-package-validator — The PHP equivalent
• cargo-lean — The Rust equivalent.