python

name	python
description	Python, .py, pyproject.toml, pytest, ruff -> use when editing, reviewing, or implementing Python code.

Python

Prefer repository-local conventions, supported Python versions, packaging choices, and existing patterns before applying general guidance.

Readability and structure

• Optimize for clear, boring Python: meaningful names, small functions, straightforward control flow, and PEP 8 style.
• Use type hints where they clarify contracts or are expected by the project; avoid noisy annotations that reduce readability.
• Choose dataclasses, TypedDict, Pydantic models, or plain classes according to existing validation and serialization needs.
• Keep dependency boundaries clean: separate I/O, domain logic, framework glue, and persistence where the repo already does so.

Errors, resources, and data

• Raise specific exceptions and preserve context when translating errors across boundaries.
• Avoid swallowing exceptions silently; log or handle only when the code can take useful action.
• Use context managers for files, locks, network clients, database sessions, and other resources that need cleanup.
• Be explicit about mutability, default values, timezone handling, encoding, and input validation at API boundaries.

Testing and tooling

• Prefer pytest style when present: focused fixtures, parametrized cases, and assertions on behavior rather than internals.
• Keep tests deterministic; isolate filesystem, time, network, and environment variable effects.
• Use repository-configured tools first: ruff, black, mypy, pyright, or other commands declared in pyproject.toml.
• When changing packaging, respect the existing pyproject.toml layout, dependency groups, build backend, and lockfile policy.

Maintainability

• Avoid hidden global state and import-time side effects unless established by the framework.
• Prefer explicit dependencies and small modules over large utility files.
• Document non-obvious behavior with concise comments or docstrings; do not restate obvious code.