jaymd96-pants-baseline

An opinionated Python code quality baseline plugin for the Pants build system.

Overview

This plugin integrates modern, high-performance tools from the Astral ecosystem to enforce consistent code quality standards across Python projects:

Installation

Add the plugin to your pants.toml:

[GLOBAL]
backend_packages = [
    "pants.backend.python",
    "pants_baseline",
]

plugins = [
    "jaymd96-pants-baseline==0.2.0",
]

Quick Start

1. Define a baseline project

Create a BUILD file in your project root:

baseline_python_project(
    name="my_project",
    sources=["src/**/*.py"],
    test_sources=["tests/**/*.py"],
    python_version="3.13",
    line_length=120,
    strict=True,
    coverage_threshold=80,
)

2. Run quality checks

# Lint with Ruff
pants baseline-lint ::

# Format with Ruff
pants baseline-fmt ::

# Type check with ty
pants baseline-typecheck ::

# Run tests with coverage
pants baseline-test ::

# Security audit with uv
pants baseline-audit ::

Configuration

Global Configuration (pants.toml)

[python-baseline]
# Enable/disable all baseline checks
enabled = true

# Target Python version
python_version = "3.13"

# Maximum line length
line_length = 120

# Source and test directories
src_roots = ["src"]
test_roots = ["tests"]

# Minimum coverage threshold
coverage_threshold = 80

# Enable strict mode for all tools
strict_mode = true

# Patterns to exclude
exclude_patterns = [
    ".venv",
    "__pycache__",
    "migrations",
]

Ruff Configuration

[ruff]
version = "0.2.0"

# Lint rules to enable
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # pyflakes
    "I",      # isort
    "N",      # pep8-naming
    "UP",     # pyupgrade
    "B",      # flake8-bugbear
    "C4",     # flake8-comprehensions
    "SIM",    # flake8-simplify
    "RUF",    # Ruff-specific
]

# Rules to ignore
ignore = ["E501"]

# Formatting options
quote_style = "double"
indent_style = "space"

# Auto-fix options
fix = true
unsafe_fixes = false

ty Configuration

[ty]
version = "0.1.0"

# Enable strict type checking
strict = true

# Reporting options
report_missing_imports = true
report_unused_imports = true
report_unused_variables = true

# Include/exclude paths
include = ["src", "tests"]
exclude = [".venv", "dist"]

# Output format (text, json, github)
output_format = "text"

uv Configuration

[uv]
version = "0.5.0"

# Security auditing
audit_enabled = true
audit_ignore_vulns = []
audit_fail_on_warning = false

# Lock file
lock_file = "uv.lock"
require_lock = true

# Output format
output_format = "text"

Target Fields

The baseline_python_project target supports the following fields:

Goals

baseline-lint

Run Ruff linting on Python files.

pants baseline-lint src/::

baseline-fmt

Format Python files with Ruff.

pants baseline-fmt src/::

# Check formatting without modifying files
pants baseline-fmt --check src/::

baseline-typecheck

Run ty type checking.

pants baseline-typecheck src/::

baseline-test

Run pytest with coverage.

pants baseline-test tests/::

# Run specific test markers
pants baseline-test --pytest-args="-m unit" tests/::

baseline-audit

Run uv security audit on dependencies.

pants baseline-audit ::

# Ignore specific vulnerabilities
pants --uv-audit-ignore-vulns="['GHSA-xxxx']" baseline-audit ::

Example Project Structure

my-project/
├── BUILD
├── pants.toml
├── pyproject.toml
├── uv.lock
├── src/
│   └── my_package/
│       ├── BUILD
│       ├── __init__.py
│       └── main.py
└── tests/
    ├── BUILD
    ├── conftest.py
    └── test_main.py

Root BUILD file

baseline_python_project(
    name="my_project",
    sources=["src/**/*.py"],
    test_sources=["tests/**/*.py"],
)

pants.toml

[GLOBAL]
pants_version = "2.30.1"
backend_packages = [
    "pants.backend.python",
    "pants_baseline",
]
plugins = ["jaymd96-pants-baseline==0.2.0"]

[python]
interpreter_constraints = ["CPython>=3.13,<4"]

[python-baseline]
python_version = "3.13"
line_length = 120
coverage_threshold = 80

[ruff]
select = ["E", "F", "I", "B", "UP", "RUF"]

[ty]
strict = true

Why This Stack?

Performance Comparison

Tool Consolidation

Claude Code Integration

This plugin bundles recommended Claude Code plugins for enhanced AI-assisted development workflows.

Install Bundled Claude Plugins

When combined with jaymd96-pants-claude-plugins:

# pants.toml
[GLOBAL]
plugins = [
    "jaymd96-pants-baseline==0.2.0",
    "jaymd96-pants-claude-plugins>=0.2.0",
]
backend_packages = [
    "pants_baseline",
    "pants_claude_plugins",
]

Then run:

pants claude-install --include-bundled ::

This automatically installs:

• github - GitHub integration for PR workflows and issue management
• commit-commands - Git workflow commands for commits, pushes, and PRs

Development

Setup

cd python-baseline
hatch env create

Run tests

hatch run test
hatch run test-cov

Lint and format

hatch run lint
hatch run fmt

License

Apache License 2.0

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

Credits

Built with tools from:

• Astral - Ruff, ty, uv
• Pants - Build system
• pytest - Testing framework