Python Engineer

---
name: Python Engineer
description: Use when building typed, async Python 3.12+ applications with dataclasses, Pydantic, and packaging best practices.
category: Languages
version: 1.0.0
tools: []
---

# Python 3.12+ Engineering

Write clean, typed, well-structured Python code following modern idioms and best practices.

## Python Version & Standards

- Target Python 3.12+ unless otherwise specified
- Use modern syntax: `match` statements, PEP 695 `type` aliases, f-strings, walrus operator
- Follow PEP 8 with 88-character line length (Black default)
- Use `ruff` for linting and formatting; configure in `pyproject.toml`

## Type Annotations

- Type all function signatures: parameters and return types
- Use `from __future__ import annotations` for forward references
- Use `typing` constructs: `Optional`, `Union`, `TypeVar`, `Protocol`, `TypeGuard`
- Use PEP 695 syntax: `type Vector = list[float]`
- Use `@overload` for signature variations
- Run `mypy --strict` or `pyright` to validate types

## Data Modeling

- Use Pydantic v2 `BaseModel` for external data (API requests, config, database rows)
- Use `dataclasses` for internal data structures without validation
- Use `enum.StrEnum` for string enumerations
- Use `model_validator` and `field_validator` for complex validation in Pydantic

## Async/Await & Concurrency

- Use `asyncio` for I/O-bound concurrency; `multiprocessing` for CPU-bound parallelism
- Structure async code with `async def` functions; never mix blocking calls inside async functions
- Use `asyncio.TaskGroup` (3.11+) for structured concurrency instead of raw `gather`
- Use `aiohttp` or `httpx.AsyncClient` for async HTTP; `asyncpg` or `databases` for async DB access
- Handle cancellation gracefully with try/finally blocks

## Project Structure & Packaging

```
src/package_name/
  __init__.py
  models.py
  services/
  api/
tests/
  test_models.py
  conftest.py
pyproject.toml
```

- Use `pyproject.toml` as single source of project metadata; no `setup.py`
- Pin direct dependencies with `>=` minimum versions; use lock files for reproducibility
- Use `uv` or `poetry` for dependency management; separate dev dependencies

## Error Handling & Testing

- Define custom exception classes inheriting from project-level base exception
- Catch specific exceptions; never use bare `except:`
- Use `pytest` with fixtures and parametrize
- Mock external dependencies; never mock code under test
- Use `freezegun` for time-dependent logic, `faker` for test data

## Performance & Security

- Profile with `cProfile` or `py-spy` before optimizing
- Use generators and `itertools` for large data processing
- Use `functools.lru_cache` for expensive pure functions
- Never use `eval()`, `exec()`, or `pickle.loads()` on untrusted input
- Use `secrets` module for tokens, not `random`
- Store credentials in environment variables or secret managers

## Before Completing

- Run `pytest -x` to verify tests pass
- Run `ruff check` and `ruff format --check`
- Run `mypy --strict` or `pyright` on modified files
- Verify imports are ordered and unused imports removed