Glossary

Definitions of key terms used throughout the typing-graph documentation. Terms appear in alphabetical order. Each term links to its primary explanation page and relevant API reference.

Annotated type

A type constructed with typing.Annotated that attaches metadata to a base type. Example: Annotated[int, Gt(0)] attaches a "greater than zero" constraint to an integer type.

Learn more: Metadata and Annotated types | API: AnnotatedNode

Depth-first traversal

A graph traversal strategy that visits each node before its children, exploring as deep as possible along each branch before backtracking. The walk() function uses this approach.

Guide: Walking the type graph | API: walk()

Edge

A semantic relationship between a parent type node and a child node in a type graph. Edges describe how nodes relate (for example, KEY for dict key types, FIELD for class fields, ELEMENT for tuple elements).

API: TypeEdge, TypeEdgeKind, TypeEdgeConnection

EvalMode

An enumeration controlling forward reference evaluation during inspection. Values: EAGER (resolve immediately, fail on error), DEFERRED (wrap in ForwardRef for lazy resolution), STRINGIFIED (keep as string).

Learn more: Forward references | API: EvalMode

Forward reference

A type annotation referencing a class not yet defined at the point of annotation. Python represents forward references as strings (for example, "Node" or Optional["Node"]).

Learn more: Forward references | API: ForwardRefNode, EvalMode

GroupedMetadata

A protocol from the annotated-types library for metadata containing other metadata items. Example: Interval(ge=0, le=100) groups Ge(0) and Le(100).

Learn more: GroupedMetadata flattening | API: MetadataCollection

InspectConfig

A frozen dataclass containing configuration options for type inspection. Controls forward reference evaluation mode, recursion depth, member inclusion, metadata hoisting, and source location tracking.

Learn more: Configuration options | API: InspectConfig

Inspection

The process of analyzing a type annotation to produce a type node representation. The inspect_type() function performs inspection, returning an appropriate node subclass based on the input type.

Learn more: Architecture overview | Tutorial: Your first type inspection

Metadata hoisting

The process of propagating metadata from an annotated type wrapper to its base type node. Example: inspecting Annotated[list[int], SomeMetadata] hoists SomeMetadata to the resulting node.

Learn more: Metadata and Annotated types | API: InspectConfig.hoist_metadata

MetadataCollection

An immutable, type-safe container for metadata extracted from Annotated type annotations. Every type node has a metadata attribute containing a MetadataCollection.

Learn more: Metadata and Annotated types | Tutorial: Working with metadata | API: MetadataCollection

Structured type

A type defining named fields with associated types. Includes dataclasses, TypedDict, NamedTuple, and Protocol.

Tutorial: Inspecting structured types | API: DataclassNode, TypedDictNode, NamedTupleNode, ProtocolNode

Type alias

A named reference to another type, using either TypeAlias annotation or PEP 695 type statement syntax.

Learn more: Type aliases | API: TypeAliasNode, inspect_type_alias()

Type graph

The tree structure produced when inspecting a type annotation. The root node represents the top-level type; child nodes represent nested types (element types, field types).

Learn more: Architecture overview | Guide: Walking the type graph | API: TypeNode.children()

Type node

An immutable object representing an inspected type annotation. Node classes correspond to type categories: ConcreteNode for simple types, SubscriptedGenericNode for parameterized generics, UnionNode for unions. All inherit from TypeNode.

Learn more: Architecture overview | Tutorial: Your first type inspection

Type qualifier

A wrapper type modifying how another type behaves in a specific context. Includes ClassVar, Final, Required, NotRequired, ReadOnly, and InitVar.

Learn more: Qualifiers

Type variable

A placeholder for a type filled in when a generic type is parameterized. Example: in list[T], T is a type variable.

Learn more: Generics and variance | API: TypeVarNode, ParamSpecNode, TypeVarTupleNode

Walk

An iterator-based traversal of a type graph using depth-first traversal. The walk() function yields unique nodes, supports predicate filtering with type narrowing, and allows depth limiting.

Guide: Walking the type graph | API: walk()