Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 38 ยท Performance and Patterns

TypeAdapter and validate_call

Validate any Python type without a model using TypeAdapter, and check function arguments and return values with @validate_call. Includes JSON, schemas and reuse.

Not every piece of data deserves a model class. Sometimes you have a plain list[int], a dict[str, float], a union of types, a TypedDict or a dataclass, and you just want Pydantic to validate and convert it. Other times you want the arguments of an ordinary function to be checked. Pydantic has one tool for each: TypeAdapter for types, @validate_call for functions. Both use exactly the same engine as BaseModel.

TypeAdapter: validation for any type

Create a TypeAdapter with a type, then call validate_python, validate_json, dump_python, dump_json and json_schema. It is the "model for a type that is not a model".

Python Validating lists, dicts and unions

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.

Notice that conversion follows the same lax rules as models: "1" becomes 1, 3.0 becomes 3. The error location (1,) is the list index.

Typed dictionaries, dataclasses and more

TypeAdapter handles TypedDict (a dictionary with a fixed key set), standard library dataclass classes, NamedTuple, enums, Literal and any combination. This is perfect when the data shape is already defined by someone else, such as a library that returns TypedDict objects.

Python TypedDict and dataclass without BaseModel

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.

JSON in, JSON out, schema

validate_json parses bytes or text and validates in one step in Rust, which is faster than json.loads followed by validate_python. dump_json returns bytes. And json_schema() describes any type for documentation.

Python validate_json, dump_json, 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.

validate_call: checked functions

Decorate a function with @validate_call and each call is validated against the type hints: arguments are converted, bad ones raise ValidationError, and defaults and keyword handling work as normal. Add validate_return=True to check the result too.

Python @validate_call on a function

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.

Constraints from Field or Annotated work on parameters. Because the check runs at call time, it is best at the boundary of a system, where untrusted values arrive (a command line handler, a plugin entry point, an RPC method), not on a function called a million times in a tight loop.

Reusing the adapter

Creating a TypeAdapter builds a validation engine, which takes time. Create it once at module level and reuse it. Creating one inside a function that runs for every request throws that work away each time. The chapter on performance returns to this point with an example.

Python Create once, reuse often

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.

When to choose what

You have Use
A record with named fields you own BaseModel
list[...], dict[...], unions, Literal TypeAdapter
TypedDict or dataclass from elsewhere TypeAdapter (or a Pydantic dataclass)
A function whose inputs need checking @validate_call

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is TypeAdapter for?

    It exposes the same validate and dump methods as a model for arbitrary types.
  2. 2. Why is validate_json usually faster than json.loads followed by validate_python?

    Pydantic's core parses the JSON text directly while validating, avoiding an intermediate Python object graph.
  3. 3. What does @validate_call(validate_return=True) add?

    By default only arguments are validated; validate_return=True also validates what the function returns.
  4. 4. Where should a TypeAdapter be created?

    Building the validator is the expensive part. Reusing the adapter avoids that cost on each call.

Summary

  • TypeAdapter(T) validates (validate_python, validate_json), serializes (dump_python, dump_json) and describes (json_schema) any type.
  • It handles TypedDict, dataclasses, unions, Literal and containers.
  • @validate_call checks function arguments (and the return with validate_return=True).
  • Build adapters once and reuse them.

Next: Performance Tips