python-best-practices

Type-first Python development using dataclasses, discriminated unions, NewType, and Protocol to make illegal states unrepresentable. Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers language-specific idioms only. Use Python's type system to prevent invalid states at type-check time. Frozen dataclasses for immutable domain models: Discriminated unions with Literal: NewType for domain primitives: Protocol for structural typing: Chain exceptions with from err to preserve the original traceback: Use a module-level logger with %s formatting (deferred string interpolation): For fast type checking, consider ty from Astral (creators of ruff and uv). Written in Rust, significantly faster than mypy or pyright. When to choose: - Define data models and function signatures before implementation; use frozen dataclasses, Literal-based discriminated unions, and NewType for domain primitives to prevent invalid states at type-check time - Leverage Protocol for structural typing, TypedDict for external data shapes, and exhaustive pattern matching with match statements to catch incomplete logic - Enforce boundary validation, descriptive exception propagation with context, and explicit error handling; avoid swallowed exceptions and silent failures - Organize code into focused modules under 300 lines, use immutable data structures, and prefer pure...