From 11d04f3602a38e32bca70577e41d05d257f86c45 Mon Sep 17 00:00:00 2001
From: Sydney Runkle <54324534+sydney-runkle@users.noreply.github.com>
Date: Fri, 15 Nov 2024 10:22:19 -0500
Subject: [PATCH] Docs updates: type adapter rebuild instructions (#10849)

---
 docs/concepts/type_adapter.md | 31 ++++++++++++++++++++++++++++++-
 pydantic/config.py            |  2 ++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/docs/concepts/type_adapter.md b/docs/concepts/type_adapter.md
index a6d54b6a1a..cb9b6c17d6 100644
--- a/docs/concepts/type_adapter.md
+++ b/docs/concepts/type_adapter.md
@@ -91,6 +91,35 @@ print(items)
 handle as fields of a [`BaseModel`][pydantic.main.BaseModel].
 
 !!! info "Performance considerations"
-    When creating an instance of `TypeAdapter`, the provided type must be analyzed and converted into a pydantic-core
+    When creating an instance of [`TypeAdapter`][pydantic.type_adapter.TypeAdapter], the provided type must be analyzed and converted into a pydantic-core
     schema. This comes with some non-trivial overhead, so it is recommended to create a `TypeAdapter` for a given type
     just once and reuse it in loops or other performance-critical code.
+
+
+### Rebuilding a `TypeAdapter`'s schema
+
+In v2.10+, [`TypeAdapter`][pydantic.type_adapter.TypeAdapter]'s support deferred schema building and manual rebuilds. This is helpful for the case of:
+* Types with forward references
+* Types for which core schema builds are expensive
+
+When you initialize a [`TypeAdapter`][pydantic.type_adapter.TypeAdapter] with a type, Pydantic analyzes the type and creates a core schema for it.
+This core schema contains the information needed to validate and serialize data for that type.
+See the [architecture documentation](../internals/architecture.md) for more information on core schemas.
+
+If you set [`defer_build`][pydantic.config.ConfigDict.defer_build] to `True` when initializing a `TypeAdapter`,
+Pydantic will defer building the core schema until the first time it is needed (for validation or serialization).
+
+In order to manually trigger the building of the core schema, you can call the
+[`rebuild`][pydantic.type_adapter.TypeAdapter.rebuild] method on the [`TypeAdapter`][pydantic.type_adapter.TypeAdapter] instance:
+
+```py
+from pydantic import ConfigDict, TypeAdapter
+
+ta = TypeAdapter('MyInt', config=ConfigDict(defer_build=True))
+
+# some time later, the forward reference is defined
+MyInt = int
+
+ta.rebuild()
+assert ta.validate_python(1) == 1
+```
diff --git a/pydantic/config.py b/pydantic/config.py
index ee7a14c342..064ef778f2 100644
--- a/pydantic/config.py
+++ b/pydantic/config.py
@@ -756,6 +756,8 @@ class Model(BaseModel):
     This can be useful to avoid the overhead of building models which are only
     used nested within other models, or when you want to manually define type namespace via
     [`Model.model_rebuild(_types_namespace=...)`][pydantic.BaseModel.model_rebuild].
+
+    Since v2.10, this setting also applies to pydantic dataclasses and TypeAdapter instances.
     """
 
     plugin_settings: dict[str, object] | None