Python Rules

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__ for validation, not complex logic.
• Use slots=True (3.10+) for memory efficiency in high-volume objects.

Functional Patterns

• Use functools.lru_cache for pure function memoization.
• Use itertools for efficient iteration (chain, islice, groupby).
• Use generators (yield) for lazy sequences and large data processing.
• Prefer comprehensions over map/filter with lambdas.
• Use functools.partial to create specialized versions of functions.

Dependency Injection

• Use constructor injection: pass dependencies as __init__ params.
• Use Protocol classes to define dependency interfaces.
• Use factory functions to wire dependencies at application startup.
• Avoid global state and singletons. Use module-level instances if needed.

Anti-Patterns

• Mutable default arguments: use None and create inside function.
• Catching Exception broadly: masks bugs and interrupts.
• Using type() for type checking: use isinstance().
• Nested try/except: flatten with early returns or separate functions.
• Using global keyword: pass state through parameters or classes.