Accessing Python Type Annotations Safely

Why it exists

Python needed a standard way for tools to read the type hints and other metadata developers attach to code. Frameworks like FastAPI, Pydantic, and Typer rely on this introspection to automate validation and serialization. However, the initial implementation had subtle issues, necessitating a standardized, safer access method.

The mental model

Think of annotations as a raw dictionary attached to an object, but with tricky inheritance rules in older Python versions. Instead of accessing this raw data directly, use a dedicated "getter" function like inspect.get_annotations() as your official, safe API. This function acts as a compatibility layer, shielding you from version-specific implementation details.

How it works

The recommended approach varies by Python version. In Python 3.10 and newer, the best practice is to call inspect.get_annotations(obj). This function correctly handles different object types and can "un-stringize" forward references. If you must access the dictionary directly, obj.annotations is now guaranteed to work correctly for functions, classes, and modules. For other callables, use getattr(obj, 'annotations', None). In Python 3.9 and older, the logic is more complex. For non-class objects, getattr is safe. For classes, you must check the class's dict directly (MyClass.dict.get('annotations')) to avoid accidentally inheriting annotations from a parent class.

When to use it

Use programmatic access to annotations when building tools that need to understand code structure at runtime. This is common in dependency injection systems (FastAPI), data validation libraries (Pydantic), and CLI tools (Typer). These frameworks inspect function and class annotations to automate their core logic.

When not to use it

Avoid manually accessing the annotations dunder attribute directly, especially in code supporting multiple Python versions. Always prefer the highest-level abstraction available: inspect.get_annotations() in Python 3.10+ and annotationlib.get_annotations() in 3.14+. Direct access is a low-level operation prone to breaking.

One canonical example

The classic footgun in Python 3.9 and earlier involves class inheritance. Given class Base: a: int and class Derived(Base): pass, running print(Derived.annotations) in Python 3.9 would output {'a': <class 'int'>}, the parent's dictionary. In Python 3.10+, the same code correctly prints an empty dictionary, {}, because Derived has no annotations of its own, making introspection more predictable.