Powering Up Your Types with Annotated

Python’s type system isn't just for static analysis anymore. With Annotated, our types can carry their own documentation, validation logic, and runtime instructions—effectively breaking the boundary between "checking code" and "executing it." This talk explores how Annotated acts as a universal metadata engine, allowing us to define semantic and branded types that attach rich instructions to our data without cluttering the core code.

The real magic of Annotated lies in its ability to handle composition and layering in application design. We’ll look at how to build from the inside out, starting with core business logic in pure Python and then layering on metadata to bridge the gap to higher-level application layers. By enriching primitive types with the annotated-types standard, we can enable (almost) zero-config test data generation and property-based testing using Polyfactory and Hypothesis. From there, we can layer on SQLAlchemy metadata to handle persistence without letting the database schema influence our data model, or use Pydantic to provide specialized data validation and serialization metadata—all within the same type definition.

We will also see how Annotated serves as a single source of truth for documentation. We’ll explore annotated-doc as an alternative approach to documentation compared to traditional Sphinx or NumPy/Google-style docstrings, showing how to leverage type hints to keep our descriptions directly attached to the data they define.

The goal is to show how composition and layering allow your core logic to stay stable while your infrastructure evolves independently. You’ll get a whirlwind tour of how the modern Python stack—including Pydantic, SQLAlchemy, and FastAPI—has converged on Annotated as a primary or at least first-class configuration interface. You'll walk away with a practical framework for using these integrations to keep your software design clean, decoupled, and easy to maintain in everyday development.

This talk is for anyone interested in modern Python typing and effective application design. We’ll focus on how to use Annotated to bind your favorite libraries together and apply these patterns to your daily work. If you're familiar with basic type hints, you're ready to go—we'll build the rest from the ground up!