python-best-practices

# Python Best Practices Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers language-specific idioms only. ## Make Illegal States Unrepresentable Use Python's type system to prevent invalid states at type-check time. **Frozen dataclasses for immutable domain models:** ```python from dataclasses import dataclass from datetime import datetime @dataclass(frozen=True) class User: id: str email: str name: str created_at: datetime # Frozen dataclasses are immutable — no accidental mutation ``` **Discriminated unions with Literal:** ```python from dataclasses import dataclass from typing import Literal @dataclass class Success: status: Literal["success"] = "success" data: str @dataclass class Failure: status: Literal["error"] = "error" error: Exception RequestState = Success | Failure def handle_state(state: RequestState) -> None: match state: case Success(data=data): render(data) case Failure(error=err): show_error(err) ``` **NewType for domain primitives:** ```python from typing import NewType UserId = NewType("UserId", str) OrderId = NewType("OrderId", str) def get_user(user_id: UserId) -> User: # Type checker prevents passing OrderId here ... ``` **Protocol for structural typing:** ```python from typing import Protocol class Readable(Protocol): def read(self, n: int = -1) -> bytes: ... def process_input(source: Readable) -> bytes: ...