Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 38 ยท Performance and Patterns

Generic and Recursive Models

Write reusable Pydantic models with Generic and TypeVar, such as paged responses, and model trees with self-referencing and forward references, plus how to handle depth limits.

Two shapes of data appear again and again. First, a wrapper around something else: a page of results, an API envelope with data and error, a response holding a list of whatever type. Writing a new class for each content type would be repetitive; generic models let you write the wrapper once. Second, trees: a comment with replies, a folder containing folders, a category with sub-categories. Here a model contains itself, which needs recursive models. This lesson covers both.

Generic models

A generic model is a BaseModel that also inherits from Generic[T], where T is a TypeVar. You then parametrize it: Page[User], Page[int]. Pydantic builds a real validating class for each parametrization.

Python A generic Page model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The items were validated as User objects in the first case and as integers in the second, using one class definition. Notice the error location ('items', 0, 'id').

Since Python 3.12 you can write the shorter syntax class Page[T](BaseModel): and skip the TypeVar; Pydantic supports it. The older Generic[T] form works on every supported Python version, which is why this lesson uses it.

Bounded and defaulted type variables

Limit what a type variable accepts with bound=. The restriction is checked by your type checker, which gives you early feedback; Pydantic itself validates the data against the concrete type you choose.

Python Bound TypeVar

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The bound tells type checkers (and readers) that E must be an Entity, so repo.add can safely use item.id. A checker such as mypy or pyright reports Repository[int]; at run time Pydantic simply validates the items as the type you gave. The last lines show the dictionary keys and values being converted into int and Book.

A generic API envelope

Generic models shine in APIs. One Envelope[T] gives every endpoint the same outer shape, and the FastAPI docs show the right data type per route, because each parametrization has its own JSON schema.

Python Envelope with its JSON schema

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The parametrized class has its own name, Envelope[Product], which also appears in OpenAPI documents.

Recursive models

A model that refers to itself needs a forward reference: put the class name in quotes (or use from __future__ import annotations). Pydantic resolves it once the class exists.

Python A comment tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

flowchart TB
    A["Comment: ada"] --> B["Comment: bob"]
    A --> C["Comment: cy"]
    B --> D["Comment: eve"]

Each Comment holds a list of Comment objects, so the model describes a tree of any depth.

Trees with a tag: file system example

Recursion works with unions too. A folder contains files and other folders, and a discriminator keeps validation fast and errors clear.

Python A file system tree

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Node is defined after Folder, so Folder is incomplete until model_rebuild() runs. Pydantic often rebuilds automatically on first use, but calling model_rebuild() yourself makes the order explicit and fixes the "class not fully defined" error you get when a forward reference cannot be resolved.

Cycles and depth

A cyclic object (a comment that is its own reply) cannot be validated from data by a recursive model, because JSON has no cycles. If a Python object contains a cycle, model_dump raises an error about recursion. Pydantic handles deep but finite nesting, but extremely deep input can reach Python's recursion limit or use lots of memory. For input from the outside world, do both of these:

  1. Limit the size of the request before parsing (web servers and proxies can enforce a maximum body size).
  2. Add a check of maximum depth in a validator if your data model allows unbounded nesting. A tree of limited depth is easy to check by passing the depth through validation context, as the previous lesson showed.
Python Limiting depth

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Page[User] do?

    Parametrizing a generic model creates a validating class where the type variable is replaced by User.
  2. 2. Why does a recursive model write the type as a string or use from __future__ import annotations?

    A forward reference is resolved after the class exists.
  3. 3. What is model_rebuild() for?

    After the missing names exist, model_rebuild() finishes building the validator.
  4. 4. How can you protect against extremely deep nested input?

    Unbounded recursion on untrusted input can hit recursion or memory limits, so limit size and depth.

Summary

  • A generic model inherits BaseModel and Generic[T]; Page[User] validates items as users and has its own JSON schema.
  • Use bound= to restrict type variables and generic envelopes for consistent API shapes.
  • Recursive models use forward references; call model_rebuild() when names are defined later.
  • Discriminated unions keep recursive trees fast; limit depth and size for untrusted input.

Next: Testing and Design Patterns