typing-graph

typing-graph is a building block for Python libraries and frameworks that derive runtime behavior from type annotations. If you're building validation frameworks, CLI tools, serializers, ORMs, or similar tools that inspect types to generate code or configure behavior, typing-graph provides the structured type introspection layer so you can focus on your domain logic.

Pass any type (generics, Annotated, dataclasses, TypedDict, PEP 695 aliases) and get back a graph of nodes representing the type structure and its metadata. The library handles metadata hoisting (extracting annotations from Annotated wrappers), qualifier detection (ClassVar, Final, Required), forward reference resolution, and caching. Each node exposes a children() method for recursive traversal.

Alpha software

This project is in early development. APIs may change without notice. Not yet recommended for production use.

Installation

pip install typing-graph

Requires Python 3.10 or later. See Installation for package manager options and optional dependencies.

Quick example

>>> from typing import Annotated
>>> from dataclasses import dataclass
>>> from typing_graph import inspect_type

>>> # Define constraint metadata (like you might in a validation framework)
>>> @dataclass
... class Pattern:
...     regex: str

>>> @dataclass
... class MinLen:
...     value: int

>>> # Define a reusable annotated type alias
>>> URL = Annotated[str, Pattern(r"^https?://")]

>>> # Build a complex nested type
>>> Urls = Annotated[list[URL], MinLen(1)]

>>> # Inspect the type graph
>>> node = inspect_type(Urls)
>>> node  # doctest: +SKIP
SubscriptedGenericNode(metadata=(MinLen(value=1),), origin=GenericTypeNode(cls=list), args=(ConcreteNode(metadata=(Pattern(regex='^https?://'),), cls=str),))

>>> # The outer node is a SubscriptedGenericNode (list) with container-level metadata
>>> node.origin.cls
<class 'list'>
>>> node.metadata
(MinLen(value=1),)

>>> # Traverse to the element type - it carries its own metadata
>>> element = node.args[0]
>>> element.cls
<class 'str'>
>>> element.metadata
(Pattern(regex='^https?://'),)

Each node in the graph carries its own metadata, enabling frameworks to apply different validation or transformation logic at each level of the type structure.

Use cases

typing-graph provides the foundation for frameworks that derive behavior from type annotations:

Validation frameworks

Build validators that extract constraints from Annotated metadata and generate validation logic based on type structure. typing-graph provides inspection; your framework provides the validation.

Type conversion

Convert values between types by inspecting source and target type structures, handling nested generics and union types.

Command-line interfaces

Parse command-line arguments by inspecting function signatures and generating appropriate parsers for each parameter type.

ORM mapping

Map Python classes to database schemas by analyzing field types, extracting column metadata from annotations.

Feature flags

Extract feature flag definitions from type metadata to configure runtime behavior based on annotated types.

Code generation

Generate serializers, API clients, or documentation by traversing the type graph and emitting code for each node type.

What typing-graph is not

typing-graph is not a runtime type checker or validation library. It provides the introspection layer that such tools can build on.

If you want to	Use instead
Check types at runtime	beartype, typeguard
Validate data	pydantic, attrs
Static type checking	basedpyright, mypy, pyrefly, ty

typing-graph helps you build validation frameworks by inspecting type structures; it doesn't validate data itself.

Next steps

Ready to start using typing-graph? Choose your path based on how you learn best.

• Tutorials

  ---

  Learn typing-graph step by step with hands-on lessons that teach the fundamentals.

  Get started

• How-to guides

  ---

  Follow practical recipes that show how to achieve specific goals with typing-graph.

  Find a guide

• Reference

  ---

  Look up technical details about the API, including classes, functions, and configuration.

  Browse the API

• Explanation

  ---

  Understand the concepts, architecture, and design decisions behind typing-graph.

  Learn more