---
description: "Python coding conventions: PEP 8, type hints, pydantic, pytest, async patterns, project structure"
globs: ["**/*.py", "**/*.pyx", "**/*.pxd", "**/pyproject.toml", "**/requirements*.txt"]
---
# Python

- Follow PEP 8: snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants
- Use type hints on all function signatures; validate with `mypy` or `pyright`
- Use `pydantic` for data validation and serialization
- Import order: stdlib -> third-party -> local; use absolute imports
- Use context managers (`with`) for resource management
- Catch specific exceptions, never bare `except:`; use custom exception classes
- Use `async`/`await` with `asyncio` for I/O-bound concurrency
- Use `pytest` for testing (not `unittest`); fixtures for setup/teardown
- **NEVER install packages globally** (`pip install` / `pip3 install` without a venv). ALWAYS use a virtual environment (`venv`, `poetry`, or `conda env`). If no venv exists for the project, create one first (`python3 -m venv .venv && source .venv/bin/activate`) before installing anything. Pin dependencies.
- Format with `black`; lint with `ruff` or `flake8`

## Cython
- In `cdef class` methods, prefer `cdef` over `cpdef` unless the method must be callable from Python. `cdef` = C-only (fastest), `cpdef` = C + Python, `def` = Python-only. Check all call sites before choosing.