python-best-practices

Language-specific Python idioms for writing type-first, functional, and safely error-handled code, complementing broader project conventions. Its central theme is making illegal states unrepresentable through the type system. It shows frozen dataclasses for immutable domain models so values cannot be accidentally mutated; discriminated unions built from dataclasses with Literal status fields, consumed with structural pattern matching (match/case) to handle each variant exhaustively; NewType for domain primitives such as UserId and OrderId, so a type checker prevents passing one where another is expected; and Protocol for structural typing, accepting any object that satisfies a shape (for example an object with a read() method) without requiring inheritance. For error handling it demonstrates exception chaining with raise ... from err to preserve the original traceback when wrapping a lower-level error such as a json.JSONDecodeError into a domain-level ValueError. For observability it recommends a module-level logger using %s-style deferred string interpolation rather than eager formatting in log calls. It also covers type-checking tooling, introducing ty from Astral (the makers of ruff and uv) as a fast, Rust-based checker runnable via uvx with no install, and offering guidance on when to choose ty (fastest, good for CI and large codebases, still early stage), pyright (most complete type inference and VS Code integration), or mypy (mature, extensive plugin ecosystem). The material applies when reading or writing Python source, pyproject.toml, or requirements.txt, and gives concrete, copyable snippets for each pattern so teams can adopt consistent, type-safe idioms across a codebase.