Ruff: Linter & Formatter¶

Ruff is an extremely fast Python linter and code formatter written in Rust by Astral. It replaces Flake8, Black, isort, pydocstyle, pyupgrade, autoflake, and dozens of Flake8 plugins.

What It Does¶

Ruff performs comprehensive static analysis and automatic code formatting on Python source code. It replaces more than a dozen legacy tools—including Flake8, Black, isort, pydocstyle, and pyupgrade—with a single Rust-native binary that implements over 800 lint rules covering code style, complexity, performance, docstring standards, and potential runtime flaws.

In addition to drop-in formatting compatibility with Black, Ruff organizes import statements deterministically and applies safe in-place fixes across codebases in tens of milliseconds.

Why It's in Zenith¶

Zenith integrates Ruff with all rule categories and preview rules enabled (select = ["ALL"]) to establish a zero-drift standard of code excellence. Enabling preview rules catches subtle defects early, such as mutable default arguments, unclosed file handles, insecure pseudorandom generators, and unparenthesized generator expressions.

Because Ruff operates at sub-second speeds even across large multi-module repositories, formatting and lint checks run before every commit and during CI without introducing developer latency or style debates.

Configuration in Zenith¶

Configured in ruff.toml at the project root:

# ==============================================================================
# Ruff Configuration (ruff.toml)
#
# Tool: Ruff (https://github.com/astral-sh/ruff)
# Purpose: Extremely fast Python linter and code formatter written in Rust.
# Why it's in Zenith: Replaces Flake8, Black, isort, pydocstyle, pyupgrade, and
# dozens of other plugins. Configured with strict rule selection (ALL), preview
# mode, and docstring formatting for spotless, uniform Python style.
# ==============================================================================

exclude     = [".venv", "site", "dist"]
line-length = 88

[lint]
    future-annotations = true
    ignore = [
        "blank-line-before-class",
        "incorrect-blank-line-before-class",
        "missing-copyright-notice",
        "missing-trailing-comma",
        "multi-line-summary-second-line",
    ]
    preview = true
    select = ["ALL"]

    [lint.flake8-bugbear]
        extend-immutable-calls = ["typer.Argument", "typer.Option"]

    # CLI defaults are Annotated typer.Typer parameters, not raw boolean traps.
    [lint.flake8-boolean-trap]
        extend-allowed-calls = ["typer.Argument", "typer.Option"]

    [lint.flake8-tidy-imports]
        ban-relative-imports = "all"

    [lint.flake8-type-checking]
        exempt-modules = ["typing", "typing_extensions"]
        runtime-evaluated-base-classes = ["pydantic.BaseModel"]
        runtime-evaluated-decorators = [
            "attrs.define",
            "attrs.frozen",
            "attrs.mutable",
            "dataclasses.dataclass",
            "pydantic.dataclasses.dataclass",
            "pydantic.validate_call",
        ]

    [lint.isort]
        combine-as-imports = true
        required-imports   = ["from __future__ import annotations"]

    [lint.per-file-ignores]
        # pytest idioms: tests are assertion-driven and have no production
        # assert surface to protect.
        "tests/**/*" = ["assert"]

        # Maintenance scripts: subprocess drives repo-owned tooling on
        # repo-controlled paths.
        "scripts/*" = ["suspicious-subprocess-import"]

    [lint.pyupgrade]
        keep-runtime-typing = true

[format]
    docstring-code-format = true

Key Policy Highlights¶

Mandatory Future Annotations: required-imports = ["from __future__ import annotations"] (via rule I002) and future-annotations = true ensure that every Python module defers runtime annotation evaluation. This eliminates runtime typing overhead, supports postponed typing syntax across all files, and allows flake8-type-checking to safely move type-only imports into if TYPE_CHECKING: blocks.
Absolute Imports Mandate: ban-relative-imports = "all" eliminates ambiguous relative imports (from ..module import func), ensuring every import path is explicit and readable.
Docstring Code Formatting: docstring-code-format = true automatically formats Python snippets embedded inside docstrings.
Trailing Comma & Formatter Compatibility: Disables COM812 and ISC001 to prevent conflicts between the linter and formatter.

Key Invocations¶

uv run poe lint          # Lint source files with ruff check
uv run poe format        # Format code with ruff format
uv run poe format-check  # Verify code format without mutating files
uv run poe fix           # Auto-fix lint violations and apply formatting