Python Style Guide¶

Status: 🟢 Active  |  Owner: Python Guild

Base Standard¶

PEP 8 is the base, with Black as the authoritative formatter (Black's output overrides PEP 8 where they differ).

Configuration¶

# pyproject.toml
[tool.black]
line-length = 120
target-version = ["py310", "py311", "py312"]

[tool.ruff]
line-length = 120
target-version = "py310"
select = [
    "E", "W",   # pycodestyle
    "F",        # pyflakes
    "I",        # isort
    "N",        # pep8-naming
    "UP",       # pyupgrade
    "B",        # flake8-bugbear
    "S",        # bandit security
    "C4",       # flake8-comprehensions
    "RET",      # flake8-return
    "SIM",      # flake8-simplify
]
ignore = ["E501"]  # line length handled by black

[tool.mypy]
strict = true
python_version = "3.10"
warn_return_any = true
disallow_untyped_defs = true

Key Standards¶

Type Hints (Mandatory)¶

All function signatures in production code must have type hints:

# ✅ Required
def calculate_total(order: Order, tax_rate: Decimal) -> Money:
    ...

# ❌ Not allowed in production code
def calculate_total(order, tax_rate):
    ...

Use from __future__ import annotations for forward references.

Dataclasses and Pydantic¶

• Use @dataclass(frozen=True) for immutable value objects.
• Use Pydantic v2 BaseModel for all API request/response schemas and config models.
• Use pydantic.dataclasses for domain objects requiring validation.

f-strings¶

Use f-strings for all string interpolation. Avoid % formatting and .format().

# ✅
message = f"Order {order.id} placed by {customer.name}"

# ❌
message = "Order %s placed by %s" % (order.id, customer.name)

Last reviewed: 2025-Q4  |  Owner: Python Guild