/python-rules

name: python-rules
description: "Python coding rules: style, patterns, security, testing. Triggers: .py, .pyi, pyproject.toml, requirements.txt, Pipfile, FastAPI, Django, Flask, pytest, SQLAlchemy, ruff, mypy."
effort: medium
user-invocable: false
allowed-tools: Read

Python Rules

These rules come from `app/rules/python/` in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Python. Apply them when writing or reviewing Python code.

Python Coding Style

Type Hints

• Type all public function signatures (parameters + return).
• Use `str | None` (PEP 604) over `Optional[str]` on Python 3.10+.
• Use `from __future__ import annotations` for forward references.
• Use `TypeAlias` or `type` (3.12+) for complex type aliases.
• Use `Protocol` for structural subtyping instead of ABCs where possible.

Naming

• snake_case: variables, functions, methods, modules.
• PascalCase: classes, type aliases, Protocols.
• UPPER_SNAKE: module-level constants.
• Prefix private: `_internal_helper`. No double underscore unless name mangling needed.
• Prefix unused: `_` for intentionally unused variables.

Functions

• Prefer keyword arguments for functions with >2 params.
• Use `*` to force keyword-only: `def fetch(*, limit: int, offset: int)`.
• Return early to reduce nesting. Avoid deep if/else chains.
• Use `@staticmethod` only for pure utility. Prefer module-level functions.

Imports

• Group: stdlib, third-party, local. Separated by blank lines.
• Use absolute imports. Relative imports only within packages.
• Never `from module import *`. Be explicit.
• Use `if TYPE_CHECKING:` for import-only-for-types to avoid circular imports.

Data Structures

• Use `dataclasses` for plain data containers.
• Use Pydantic `BaseModel` for validated data / API schemas.
• Use `NamedTuple` for lightweight immutable records.
• Use `Enum` for fixed sets of values. Prefer `StrEnum` on 3.11+.
• Prefer `dict` / `list` literals over `dict()` / `list()` constructors.

Modern Python

• Use f-strings for formatting. Never `.format()` or `%` for new code.
• Use `pathlib.Path` over `os.path` for file operations.
• Use `contextlib.suppress(KeyError)` over bare try/except for simple cases.
• Use walrus operator `:=` when it genuinely improves readability.
• Use `match/case` (3.10+) for complex conditionals on structured data.

Tooling

• Formatter: `ruff format` or `black`. No manual formatting.
• Linter: `ruff check`. Fix all errors before committing.
• Type checker: `mypy --strict` or `pyright` in CI.

Python Frameworks

FastAPI

• Use Pydantic v2 models for request/response schemas.
• Use dependency injection (`Depends()`) for shared logic (auth, DB sessions).
• Use `APIRouter` to organize routes by domain.
• Return Pydantic models directly -- FastAPI handles serialization.
• Use `BackgroundTasks` for non-critical async work (emails, logging).
• Use `lifespan` context manager for startup/shutdown (not `on_event`).

Django

• Use class-based views for CRUD, function-based for custom logic.
• Use `select_related` and `prefetch_related` to prevent N+1 queries.
• Use Django REST Framework serializers for API validation.
• Use Django ORM migrations. Never modify database schema manually.
• Use `transaction.atomic()` for multi-model operations.
• Use signals sparingly: prefer explicit service calls.

SQLAlchemy 2.0

• Use the 2.0-style with `select()` statements, not legacy `query()`.
• Use `Mapped[type]` annotations for typed column definitions.
• Use `sessionmaker` with `expire_on_commit=False` for API responses.
• Use `async_sessionmaker` with `asyncpg` for async applications.
• Always use `session.begin()` context manager for transaction scope.

Pydantic v2

• Use `model_validator(mode="before")` for cross-field validation.
• Use `field_validator` for single-field validation.
• Use `model_config = ConfigDict(strict=True)` for strict type coercion.
• Use `Annotated[str, Field(min_length=1)]` for reusable constrained types.
• Use `model_dump(exclude_unset=True)` for PATCH operations.

CLI (click / typer)

• Use Typer for new CLI tools (type-hint-driven, less boilerplate).
• Use `click.group()` for multi-command CLIs.
• Use `rich` for formatted terminal output (tables, progress bars).

Task Queues

• Use Celery with Redis/RabbitMQ for background job processing.
• Use `arq` for lightweight async job queues.
• Always set task timeouts. Never let tasks run indefinitely.
• Use idempotent tasks: safe to retry on failure.

Package Management

• Use `uv` for fast dependency resolution and virtual environments.
• Use `pyproject.toml` for all project configuration (no setup.py/setup.cfg).
• Pin dependencies with lockfile (`uv.lock`, `poetry.lock`).

Python Patterns

Error Handling

• Catch specific exceptions, never bare `except:` or `except Exception`.
• Use custom exception hierarchies: `class AppError(Exception)` as base.
• Add context when re-raising: `raise AppError("context") from original`.
• Use `contextlib.suppress()` for expected, ignorable exceptions.
• Log exceptions with `logger.exception("msg")` to include traceback.

Context Managers

• Use `with` for any resource that needs cleanup (files, connections, locks).
• Create custom context managers with `@contextmanager` decorator.
• Use `contextlib.AsyncExitStack` for dynamic async resource management.
• Use `atexit.register()` for process-level cleanup only.

Async

• Use `asyncio` for I/O-bound concurrency. Use `multiprocessing` for CPU-bound.
• Use `asyncio.gather()` for concurrent independent operations.
• Use `asyncio.TaskGroup` (3.11+) for structured concurrency.
• Never mix `asyncio.run()` inside already-running event loops.
• Use `async for` and `async with` for streaming and resource patterns.

Dataclass Patterns

• Use `frozen=True` for immutable value objects.
• Use `field(default_factory=list)` for mutable defaults, never `field(default=[])`.
• Use `__post_init__` f