Conventions & Style Guide

Agreed Python idioms for the team - formatting, naming, typing, errors, and commits - enforced by ruff in CI and documented here so reviews focus on design, not taste.

Recipe

from __future__ import annotations
 
from pathlib import Path
 
DATA_DIR = Path(__file__).resolve().parent / "data"
 
 
def load_config(path: Path) -> dict[str, str]:
    try:
        text = path.read_text(encoding="utf-8")
    except OSError as exc:
        raise ConfigError(f"cannot read {path}") from exc
    return parse_env(text)

When to reach for this:

• Writing new modules in shared services
• Reviewing PRs for consistency
• Onboarding developers from other languages
• Resolving "which pattern do we use?" debates

Working Example

# modules/billing/services/tax.py
from decimal import Decimal
 
from billing.domain.models import LineItem
from billing.settings import Settings
 
 
class TaxService:
    def __init__(self, settings: Settings) -> None:
        self._rate = Decimal(settings.vat_rate)
 
    def compute(self, items: list[LineItem]) -> Decimal:
        subtotal = sum((i.unit_price * i.quantity for i in items), start=Decimal("0"))
        return (subtotal * self._rate).quantize(Decimal("0.01"))

Commit message:

feat(billing): apply VAT to EU line items [BILL-91]
 
Uses Decimal for money math. Adds regression test for zero-quantity lines.

What this demonstrates:

• from __future__ import annotations for forward refs
• Decimal for currency - not float
• Private _rate attribute; public typed methods
• Ticket id in commit subject

Deep Dive

How It Works

• ruff - Replaces flake8, isort, pyupgrade; config in pyproject.toml.
• Line length - Typically 88 or 100 - team picks one.
• Naming - PEP 8: snake_case functions, PascalCase classes, SCREAMING_SNAKE constants.
• Imports - isort rules via ruff; no wildcard from module import *.

Team Defaults

Python Notes

# pyproject.toml excerpt
[tool.ruff.lint]
select = ["E", "F", "I", "UP", "B", "SIM"]
ignore = ["E501"]  # if formatter handles line length

Gotchas

• Per-developer black/ruff versions - CI fails locally passed PR. Fix: uv sync pins tool versions.
• Type ignores without ticket - Debt accumulates. Fix: # type: ignore[arg-type] # BILL-99.
• Float literals for money - 0.1 + 0.2 bugs. Fix: Decimal or int cents.
• Bare except: - Masks KeyboardInterrupt. Fix: catch Exception minimum, preferably specific types.
• Mutable class attributes - Shared state bugs. Fix: dataclass instances or instance attrs.
• Inconsistent framework patterns - Flask globals in FastAPI app. Fix: follow service ADR.

Alternatives

FAQs

Related

• PEP 8 and Style Reference - reference
• 50 Python Rules - rules list
• Ruff and Formatters - tooling
• Code Review Guidelines - review focus

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.