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.