pattern-engineer-python

When to activate

Activate when writing or editing any .py file, scaffolding a Python service, modifying pyproject.toml, working with FastAPI / Flask / Django / SQLAlchemy / Pydantic / pytest, or running mypy / ruff / bandit / pytest / uv. Skip for non-Python code.

Project memory overlay

After loading this skill, also check $MAIN_ROOT/.claude/memory/patterns/pattern-engineer-python.md in the consuming project (resolve MAIN_ROOT="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"). If present, load it as an additive overlay to the rules below; if absent, skip silently. See memory-convention for the full contract (additivity, severity floor, conflict surfacing).

Patterns

Environment — uv only

• uv is the only supported environment / dependency manager.
• No pip, poetry, pipenv, conda, virtualenv workflows.
• Pin Python version in pyproject.toml via requires-python.
• Commit uv.lock; never edit by hand.
• Prefer uv run <cmd> over activating the venv in scripts.

PEP 8

• 4-space indentation, no tabs.
• Lines ≤ 88 chars (ruff default).
• snake_case for functions / methods / variables / modules.
• PascalCase for classes.
• SCREAMING_SNAKE_CASE for module-level constants.
• Two blank lines between top-level defs; one between methods.
• Imports: stdlib → third-party → local; sorted by ruff (I rules).

Type annotations on every signature

• Every function and method — including __init__, private helpers, and tests — fully annotated.
• Annotate parameters AND the return type. -> None explicitly for procedures.

EAFP over LBYL

• Try the operation; catch the narrowest exception that applies.
• Always raise ... from e to preserve the cause.
• Don't swallow silently; either handle meaningfully or re-raise.

Modern type hints

• Target Python ≥ 3.10.
• Built-in generics: list[int], dict[str, X] — not List / Dict from typing.
• PEP 604 unions: int | None — not Optional[int].
• PEP 695 aliases + generics on 3.12+: type UserId = int; def first[T](items: list[T]) -> T | None: ....

Protocol (duck typing)

• typing.Protocol for collaborator types crossing module boundaries (structural — anything with the right shape satisfies).
• ABCs only when you need shared implementation, not just a shape.

Dataclasses as DTOs

• @dataclass(frozen=True, slots=True) for plain data carriers — request/response payloads, config bundles, value objects.
• frozen=True for immutability; slots=True for memory + attribute safety.
• No behavior beyond trivial derived properties.
• Pydantic only when parsing/validation is needed at a system boundary (FastAPI request bodies, config from env).

Context managers

• Every acquired resource (files, sockets, locks, DB sessions, temp dirs, subprocess handles) released via with.
• Author your own with contextlib.contextmanager or __enter__ / __exit__.
• contextlib.ExitStack to compose a dynamic set of context managers.
• Never try with manual .close() when with would do.

Pythonic idioms

• Mutable default arguments: NEVER def f(x=[]) / def f(x={}) — the default is shared across calls. Use def f(x: list[T] | None = None) and convert to [] inside.
• List comprehensions / generator expressions over C-style accumulating loops (result = []; for ...: result.append(...) → result = [... for ... if ...]).
• isinstance(x, T) over type(x) == T — isinstance respects subclassing; type== doesn't.
• x is None / x is not None — never == None (None is a singleton; identity comparison is both faster and the canonical idiom).
• "".join(parts) over += in a loop — str is immutable; += is quadratic.
• Don't shadow builtins (list, dict, str, id, type, input) — pick a different name.
• No from module import * — namespace pollution and breaks tooling that tracks symbol origins.
• Weak crypto banned for security purposes: no md5 / sha1 for signatures / fingerprints / passwords. Use hashlib.sha256 (or stronger), bcrypt / argon2 for passwords, hmac.compare_digest for HMAC.

Banned APIs (bandit blocks these)

The pre-push hook runs uv run bandit -r . — anything above LOW severity blocks the push. (pattern-reviewer-python carries the per-API bandit codes and rationale.)

Backend layout (src/)

See templates/backend-layout.md. Source under src/<package>/, tests at the top level under tests/{database,unit,integration}/, single pyproject.toml.

• src/ layout avoids accidental imports from CWD.
• api/ holds route/handler modules; models/ holds dataclasses / ORM / DTOs; utils/ holds cross-cutting helpers.
• Shared fixtures live in tests/conftest.py.
• Tool configs ([tool.ruff], [tool.ruff.format], [tool.mypy], [tool.pytest.ini_options]) live in pyproject.toml.

Tooling

Run via uv run so it picks up the project env.

uv run mypy .                  # Type checking
uv run ruff check .            # Fast linting
uv run ruff format --check .   # Format check
uv run bandit -r .             # Static security analysis
uv run pytest                  # Tests

Auto-fix before re-running checks:

uv run ruff format .       # Auto-format
uv run ruff check --fix .  # Auto-fix lint (includes import sorting)

Enforced ruff rule set

[tool.ruff.lint] select in pyproject.toml pins the rule groups the pre-push hook and ci-checks.sh fail on. The scaffold ships this set; treat it as the baseline:

• Security (S) is intentionally NOT in select — bandit -r . owns that gate (see Banned APIs); selecting S too would double-report the same findings.

• FastAPI projects must whitelist the DI idiom so B008 (function-call-in-default) doesn't fire on every Depends()/Query()/… route:

  [tool.ruff.lint.flake8-bugbear]
  extend-immutable-calls = ["fastapi.Depends", "fastapi.Query", "fastapi.Path",
    "fastapi.Header", "fastapi.Cookie", "fastapi.Body", "fastapi.Form",
    "fastapi.File", "fastapi.Security"]

Templates