Python Types and Contracts

Overview

Treat type hints as interface design, not decoration. Focus on explicit contracts, stable public APIs, and boundary-safe modeling.

These are preferred defaults for common cases, not universal rules. When a default conflicts with project constraints, suggest a better-fit alternative and explain tradeoffs and compensating controls.

When to Use

• Public API signatures lack type annotations or use overly broad types.
• Pydantic models are scattered throughout internal logic instead of at trust boundaries.
• Contract changes risk breaking downstream consumers without migration paths.
• Interfaces accept Any, object, or untyped dicts where narrower types apply.
• Schema boundaries between layers (API, DB, domain) are implicit or inconsistent.
• Adding or evolving protocols, abstract base classes, or structural subtyping.