Python Rules

---
name: python-rules
description: "Python coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .py, .pyi, pyproject.toml, requirements.txt, Pipfile, FastAPI, Django, Flask, pytest, SQLAlchemy, ruff, mypy. Load when writing, reviewing, or editing Python code."
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__` 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.

# Python Security

## Input Validation
- Validate all input with Pydantic models at API boundaries.
- Use `constr`, `conint`, `conlist` for constrained types.
- Never use `eval()`, `exec()`, or `compile()` with user input.
- Never use `pickle.loads()` on untrusted data (arbitrary code execution).

## SQL Injection
- Use ORM query builders (SQLAlchemy, Django ORM) for all queries.
- For raw SQL, always use parameterized queries: `cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))`.
- Never use f-strings or `.format()` to build SQL queries.
- Use `text()` with `:param` syntax in SQLAlchemy raw queries.

## SSTI (Server-Side Template Injection)
- Use Jinja2 with autoescaping enabled: `Environment(autoescape=True)`.
- Never render user input as a template string.
- Use `markupsafe.Markup` only for trusted HTML content.

## Command Injection
- Never use `os.system()` or `subprocess.run(shell=True)` with user input.
- Use `subprocess.run()` with list arguments: `subprocess.run(["ls", "-la", path])`.
- Use `shlex.quote()` if shell=True is absolutely necessary.

## Path Traversal
- Use `pathlib.Path.resolve()` and verify the result is within allowed directory.
- Never concatenate user input into file paths without validation.
- Use `os.path.commonpath()` to verify path containment.

## Secrets
- Use `secrets` module for tokens: `secrets.token_urlsafe(32)`.
- Use `hashlib.scrypt` or `bcrypt` for password hashing.
- Use `hmac.compare_digest()` for constant-time secret comparison.
- Load secrets from environment: `os.environ["SECRET_KEY"]`, never hardcode.

## Dependencies
- Run `pip-audit` or `safety check` in CI.
- Use `uv` or `pip-compile` for reproducible dependency resolution.
- Avoid installing packages with native extensions from untrusted sources.
- Pin all dependency versions. Review dependency updates carefully.

## Deserialization
- Never deserialize untrusted data with `pickle`, `yaml.load()`, or `marshal`.
- Use `yaml.safe_load()` instead of `yaml.load()`.
- Use `json.loads()` for untrusted data (safe by default).
- Validate deserialized data with Pydantic before use.

## Django-Specific
- Set `DEBUG = False` in production. Never expose debug pages.
- Use `django.utils.html.escape()` for manual HTML escaping.
- Use `CSRF_COOKIE_HTTPONLY = True` and `SESSION_COOKIE_SECURE = True`.
- Keep `SECRET_KEY` unique per environment and out of version control.

# Python Testing

## Framework
- Use pytest as the default test framework. No unittest for new code.
- Use pytest-asyncio for async test functions.
- Use pytest-cov for coverage measurement.
- Use hypothesis for property-based testing on parsing/validation logic.

## File Naming
- Test files: `test_*.py` in `tests/` directory.
- Conftest: `conftest.py` at each test directory level for shared fixtures.
- Mirror source: `src/auth/service.py` -> `tests/auth/test_service.py`.

## Fixtures
- Use `@pytest.fixture` for setup. Prefer fixtures over setup/teardown methods.
- Scope fixtures appropriately: `function` (default), `module`, `session`.
- Use `yield` fixtures for setup + teardown: `yield resource; cleanup()`.
- Use `tmp_path` fixture for temporary files, not manual `tempfile`.
- Use `monkeypatch` for patching env vars, attributes, and dict items.

## Parametrize
- Use `@pytest.mark.parametrize` for testing multiple inputs/outputs.
- Use `pytest.param(..., id="descriptive_name")` for readable test IDs.
- Combine parametrize decorators for cross-product testing.

## Mocking
- Use `unittest.mock.patch` or `monkeypatch` for dependency replacement.
- Mock at the import location: `patch("myapp.service.http_client")`.
- Use `MagicMock(spec=ClassName)` to get attribute checking.
- Use `AsyncMock` for async functions.
- Prefer dependency injection over patching when possible.

## Markers
- Use `@pytest.mark.slow` for tests >1s. Exclude from default runs.
- Use `@pytest.mark.integration` for tests requiring external services.
- Register all custom markers in `pyproject.toml` to avoid warnings.

## Async Testing
- Use `@pytest.mark.anyio` or `@pytest.mark.asyncio` for async tests.
- Use `httpx.AsyncClient` for testing FastAPI/Starlette apps.
- Use `aiosqlite` or test containers for async database tests.

## Configuration
- Configure pytest in `pyproject.toml` under `[tool.pytest.ini_options]`.
- Set `addopts = "--strict-markers -ra"` for strict mode.
- Set `testpaths = ["tests"]` to avoid scanning the entire repo.