Python annotationlib Module

Python 3.14 adds the annotationlib module for inspecting annotations reliably. This matters because annotations are now lazily evaluated and may contain names that are not yet available when the annotation is inspected.

Get Annotations

Example:

import annotationlib

def greet(name: str) -> str:
    return f"Hello {name}"

annotations = annotationlib.get_annotations(greet)

print(annotations)

The result is a dictionary that maps parameter and return names to annotation values.

Choose an Annotation Format

annotationlib supports multiple formats through annotationlib.Format.

Avoid Failure on an Unknown Name

Example:

import annotationlib

def load(user: User) -> None:
    pass

annotations = annotationlib.get_annotations(
    load,
    format=annotationlib.Format.FORWARDREF
)

print(annotations)

Here User is intentionally undefined. Python 3.14 defers annotation evaluation, so defining the function succeeds. The user entry becomes a ForwardRef when requested in this format. Quoting "User" instead would leave a string annotation in this example.

Why Not Read __annotations__ Directly?

Direct access can be too low-level when annotations are lazily evaluated or include forward references. annotationlib.get_annotations() gives tools a documented way to choose how evaluation should happen.

Common Uses

• Frameworks that inspect function signatures
• Serialization and validation libraries
• Documentation generators
• Runtime type-inspection tools

All annotation formats can execute code while retrieving annotations, including STRING and FORWARDREF. They are not a sandbox for untrusted objects. VALUE can also fail when referenced names are undefined.

Conclusion

annotationlib is the Python 3.14 standard interface for advanced annotation introspection. It lets libraries retrieve annotations as values, forward references, or strings depending on how much evaluation is appropriate.