python-best-practices

name	python_best_practices
description	Broad Python architectural and coding best practices focusing on typing, error handling, caching, and object-oriented delegation.

Python Development Best Practices

When writing or refactoring Python code in this repository, follow these general guidelines to ensure the codebase remains maintainable, performant, and type-safe.

1. Type Hinting and Annotations

• Modern Typing (Python 3.10+): Use modern typing features natively available in newer Python versions (such as unquoted forward references where applicable). Do NOT use from __future__ import annotations, as the repository targets a newer version of Python.
• Return Self: Use typing.Self instead of string literals when a method returns an instance of its own class.

2. Exception Handling and Boundaries

• Narrow Exception Scopes: Never use bare except Exception: unless explicitly logging and re-raising. Catch only narrow, specific exceptions (e.g., ValueError, KeyError) to prevent accidentally swallowing unrelated programming errors.
• Encapsulate Internal Errors: When writing parsers, SDK wrappers, or low-level utilities, do not leak internal system exceptions (like IndexError or KeyError) to the caller. Wrap them and raise a single, domain-specific exception (e.g., ParseError, ApiError).

3. Performance and Caching

• Property Caching: Use @cached_property from the standard functools module for lazy evaluation of expensive properties or to cache state (e.g., converting a list to a dictionary for O(1) lookups), but only when relevant for long-lived objects (such as keysets that are kept in memory across multiple requests).
• Deterministic Caching: Use @cache (or @lru_cache) for pure functions with deterministic outputs (like reflection or metadata extraction) to eliminate repeated execution overhead.

4. Object-Oriented Delegation

• Avoid Monolithic Functions: Break down large functions that handle parsing, transformation, and business logic into smaller, delegated responsibilities.
• Direct Domain Object Construction: Deserialization methods should parse raw inputs and directly return the final usable domain object (e.g., a standard cryptographic key) rather than an intermediate Data Transfer Object (DTO) that the caller must manually convert.
• Encapsulate Validation: Delegate validation and verification logic to the specific domain objects that own the data, rather than having container classes manage the internals of their children.

5. Modern Python Syntax

• Walrus Operator: Utilize the walrus operator (:=) to flatten conditional logic, such as checking dictionary membership and assigning the result in a single step (if (match := mapping.get(key)) is None:).