How Static Type Checkers Understand Dynamic Python
Rebecca Chen
Python frameworks often create code that developers never write. A few annotated fields can become a class constructor, validated attributes, and other behavior that appears only at runtime. Yet we expect type checkers and IDEs to understand these generated APIs before the program runs.
This talk explores how type checkers make sense of dynamic Python, using examples from real-world libraries like Pydantic and Django. We'll see where annotations and stubs are sufficient, why standards such as typing.dataclass_transform exist, and what happens when a framework's behavior cannot be expressed by the standard type system.
By understanding what static analysis can - and cannot - see, we'll learn how to design library APIs that work well across type checkers and editors.
Description
Consider a dataclass with a few annotated fields. No one writes its __init__ method, but editors should autocomplete its parameters and type checkers should reject invalid arguments. How can a static tool understand code that does not exist until runtime?
Using Pyrefly as an implementation case study, this talk follows the process from a dynamic class definition to the interface presented by a type checker and language server. It examines the techniques available to library and tooling authors, as well as the limits of each approach.
The talk will cover:
- Type annotations and stubs: what they can describe, and why generated APIs present a challenge.
- Standardized transformations: how
typing.dataclass_transformcommunicates common field and constructor behavior. - Plugins and built-in support: how type checkers model behavior that the standard type system cannot express.
- Type-checker-friendly API design: predictable generated behavior, testing type information, and typed fallbacks.
No knowledge of Pyrefly is required. Attendees should be familiar with Python classes, decorators, and basic type annotations.