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 <PATTERN>	Artefact patterns to check, such as tests/
--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/" -p "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/" -p "benchmarks/"

By default, py-lean checks a built-in set of common repository artefacts.

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.