typing-inspection

typing-inspection is a focused utility library from the Pydantic team for inspecting Python type annotations at runtime. Python’s typing system has accumulated many overlapping ways to express the same concept across versions — Union[int, str] vs int | str, Optional[X], Annotated[X, ...], Literal, TypeAliasType, and version-gated qualifiers like Required/NotRequired/ReadOnly — and code that needs to introspect annotations correctly has to handle all these forms consistently across Python 3.9 through 3.14+. typing-inspection centralizes that logic so libraries like Pydantic (and any other validation, serialization, or ORM library) don’t each reimplement brittle, version-sensitive typing checks.

The library exposes two modules: typing_objects, which provides safe is_* predicate functions for identifying typing constructs (is_union, is_literal, is_typealiastype, etc.) that work correctly across Python versions where the underlying implementation of these constructs changed, and introspection, which provides higher-level utilities like inspect_annotation() to unwrap an annotation into its underlying type plus a normalized set of qualifiers (Required, NotRequired, ReadOnly, ClassVar, InitVar) and get_literal_values() to recursively extract values from (possibly nested) Literal types.

What You Get

• typing_objects module with is_union, is_literal, is_typealiastype, is_newtype, and similar version-safe predicate functions
• introspection.inspect_annotation() to unwrap an annotation into its base type plus normalized qualifiers (Required/NotRequired/ReadOnly/ClassVar/InitVar)
• introspection.get_literal_values() to recursively flatten nested Literal type values
• A .pyi stub file (typing_objects.pyi) shipped alongside the implementation for precise static-typing support
• Zero required runtime dependencies beyond typing_extensions, keeping it safe to add to any library’s dependency tree

Common Use Cases

• Validation libraries (Pydantic itself, and others) that need to correctly detect Union/Literal/Annotated forms across Python 3.9-3.14 without duplicating version-branch logic
• Serialization or ORM libraries introspecting dataclass or TypedDict field annotations to determine optionality and qualifiers
• Static-analysis or code-generation tools that need to walk type annotations and handle both Union[X, Y] and X | Y syntax uniformly
• Any library author who wants to support Annotated, Literal, and TypeAliasType without special-casing typing-module internals per Python version

Under The Hood

Architecture - The package is deliberately split into two small, focused modules under src/typing_inspection/: typing_objects.py (~600 lines) exposes low-level, version-branching predicate functions that detect typing constructs by inspecting sys.version_info and choosing the correct underlying check per Python release, shipped alongside a .pyi stub for type-checker precision; introspection.py (~590 lines) builds higher-level utilities like inspect_annotation() and get_literal_values() on top of those predicates, using an AnnotationSource enum and InspectedAnnotation/Qualifier types to represent the normalized result. There is no runtime state or classes to instantiate — every entry point is a pure function operating on a passed-in annotation object. Tech Stack - Pure Python with typing_extensions as the only runtime dependency, a py.typed marker for full type-checker support, ruff for linting (badge in the README), and a Makefile-driven dev workflow with CI configured via GitHub Actions. Code Quality - Tests are organized to mirror the source layout (tests/introspection/, tests/typing_objects/) with dedicated files for literal-value extraction, union-origin detection, and annotation inspection; the project reports CI status and a coverage badge in its README, indicating deliberate test-coverage tracking despite the small contributor pool (3 contributors as of this analysis). Docstrings throughout use runnable pycon-style doctests, which double as both documentation and quality guardrails. API Design - The API surface is minimal and function-based rather than class-based, matching the library’s narrow scope: predicates return plain booleans, and inspect_annotation() returns a small typed result object rather than requiring configuration objects or subclassing. This keeps integration into a host library (as Pydantic itself does) to a handful of direct function calls with no setup ceremony.