python

name	python
description	Python engineering guidance for type hints, pydantic validation, httpx usage, pytest conventions, pyproject structure, async patterns, and lightweight dependency injection. Use when building or reviewing Python services and libraries.

Python

Prefer typed, explicit Python with validation at boundaries, modern async I/O, and simple seams over framework-heavy indirection.

When to Activate

• Add or refactor Python modules
• Choose a model type for request or domain data
• Write an outbound HTTP integration
• Add async handlers or background jobs
• Configure pytest, typing, or packaging
• Replace hidden globals with explicit dependencies
• Review Python code for type and validation drift

Typing and Modeling

Pattern	Preferred	Avoid
Public functions	Full parameter and return annotations	Unannotated signatures
Collections	list[str], dict[str, int]	List, Dict unless compatibility requires it
Optional values	`str	None`

Need	Use
External input validation	pydantic.BaseModel
Internal immutable value object	@dataclass(frozen=True)
Loosely structured mapping shape	TypedDict

HTTP and Async

BAD

import requests

response = requests.get(url, timeout=30)

GOOD

import httpx

async with httpx.AsyncClient(timeout=10.0) as client:
    response = await client.get(url)

Rule	Why
Use async only for real I/O boundaries	Avoid fake async complexity
Do not call blocking I/O inside async handlers	Prevent event loop stalls
Batch concurrent I/O with asyncio.TaskGroup or gather where safe	Improve latency deterministically

Project Layout and DI

Section	Purpose
[project]	Metadata and dependencies
[tool.pytest.ini_options]	Test discovery and markers
[tool.ruff] or [tool.black]	Lint and format configuration
[tool.mypy]	Type checking configuration

Preferred	Avoid
Pass collaborators through constructors or function parameters	Global singletons hidden inside modules
Build objects in a wiring layer	Import-time side effects creating clients

BAD

def create_user(data):
    return User(**data)

GOOD

class CreateUserInput(BaseModel):
    email: EmailStr
    name: str


def create_user(data: CreateUserInput) -> User:
    return User(email=data.email, name=data.name)

Checklist

• Public functions and methods have type hints
• Boundary inputs are validated with pydantic where appropriate
• httpx is used for outbound HTTP unless a project standard overrides it
• Async code avoids blocking calls
• pyproject.toml centralizes tool configuration
• Data models use BaseModel, dataclass, or TypedDict intentionally
• Dependencies are injected explicitly