pyruff

Native Python API for the Ruff linter and formatter.

pyruff compiles Ruff's Rust crates directly into a Python extension module via PyO3 and Maturin. No ruff CLI needed at runtime — everything runs natively in-process with zero overhead.

Installation

pip install pyruff

Quick Start

import pyruff

# Format code
formatted = pyruff.format_string("x=1\n")
# "x = 1\n"

# Lint code
diagnostics = pyruff.check("import os\n")
for d in diagnostics:
    print(f"{d.code}: {d.message}")
# F401: `os` imported but unused

# Auto-fix violations
result = pyruff.fix("import os\nimport sys\nprint(sys.path)\n")
print(result.output)
# import sys\nprint(sys.path)\n

# List rules
all_rules = pyruff.rules()
r = pyruff.rule("F401")
print(f"{r.code}: {r.name} ({r.linter})")

Features

• Linting — check(), check_file(), check_paths() with full rule selection
• Auto-fix — fix() with safe/unsafe fix support
• Formatting — format_string(), format_file() with all formatting options
• Rules — rules(), rule(), linters() for rule metadata and introspection
• Config resolution — Automatically discovers ruff.toml / pyproject.toml config, just like ruff CLI
• Python 3.11 — 3.14 support

Config Resolution

pyruff automatically discovers and applies your existing ruff configuration:

import pyruff

# Auto-discovers ruff.toml / pyproject.toml from CWD
diagnostics = pyruff.check("import os\n")

# Explicit config path
diagnostics = pyruff.check("import os\n", config="path/to/ruff.toml")

# Ignore all config, use defaults
diagnostics = pyruff.check("import os\n", isolated=True)

# Explicit params override config values
formatted = pyruff.format_string(code, line_length=120)

Versioning

pyruff's version matches the ruff version it's built against. For example, pyruff==0.15.1 uses ruff 0.15.1 crates internally.

Documentation

• Getting Started
• Linting API — check(), fix(), check_file(), check_paths()
• Formatting API — format_string(), format_file()
• Rules API — rules(), rule(), linters()
• Configuration — Config discovery and resolution
• Upgrading Ruff — Step-by-step guide for ruff version upgrades

Development

Prerequisites

• Python 3.11+ (3.14 supported)
• Rust 1.91+ (install via rustup)
• Maturin (Python build tool for Rust extensions)

Setup

# Clone the repo
git clone https://github.com/emilt27/pyruff.git
cd pyruff

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dev dependencies
pip install maturin pytest ruff

Build

# Development build (debug, installed in .venv)
maturin develop

# Or use the helper script
bin/build

Run Tests

pytest tests/ -v

# Or use the helper script
bin/test

Linting & Formatting

# Rust
cargo fmt --check
cargo clippy -- -D warnings

# Python
ruff check python/ tests/
ruff format --check python/ tests/

# Or use the helper scripts
bin/lint
bin/fmt-check

Helper Scripts

The bin/ directory contains convenience scripts for common dev tasks:

Release

Releases are automated via GitHub Actions. To release a new version:

1. Update version in Cargo.toml and pyproject.toml
2. Commit and push
3. Create a git tag: git tag v0.15.1 && git push origin --tags
4. CI builds wheels for Linux/macOS/Windows and publishes to PyPI

License

MIT