Repository: pydantic/pydantic
Pull request: Add `TypeAdapter` section to `concepts` page of docs
## Change Summary

Moving more conceptual overview of `TypeAdapter` to `concepts` section of the docs

## Related issue number

Fix #8051

## Checklist

* [x] The pull request title is a good summary of the changes - it will be used in the changelog
* [ ] Unit tests for the changes exist
* [x] Tests pass on CI
* [x] Documentation reflects the changes where applicable
* [x] My PR is ready to review, **please add a comment including the phrase "please review" to assign reviewers**


Problem statement:
Add `TypeAdapter` section to concepts docs
There used to be a `TypeAdapter` section in the `Usage` docs, but we moved all of that content to the `API Documentation` section.

Let's add a section to the `Concepts` docs explaining how to use a `TypeAdapter`.

Hints from issue discussion:

Commit message: moving more conceptual content to concepts page

Patch to review:
diff --git a/docs/api/type_adapter.md b/docs/api/type_adapter.md
index 7a569758532..95c582d5a0f 100644
--- a/docs/api/type_adapter.md
+++ b/docs/api/type_adapter.md
@@ -1 +1 @@
-::: pydantic.type_adapter
+::: pydantic.type_adapter.TypeAdapter
diff --git a/docs/concepts/type_adapter.md b/docs/concepts/type_adapter.md
new file mode 100644
index 00000000000..8a7a9ad3a06
--- /dev/null
+++ b/docs/concepts/type_adapter.md
@@ -0,0 +1,77 @@
+You may have types that are not `BaseModel`s that you want to validate data against.
+Or you may want to validate a `List[SomeModel]`, or dump it to JSON.
+
+??? api "API Documentation"
+    [`pydantic.type_adapter.TypeAdapter`][pydantic.type_adapter.TypeAdapter]<br>
+
+For use cases like this, Pydantic provides [`TypeAdapter`][pydantic.type_adapter.TypeAdapter],
+which can be used for type validation, serialization, and JSON schema generation without creating a
+[`BaseModel`][pydantic.main.BaseModel].
+
+A [`TypeAdapter`][pydantic.type_adapter.TypeAdapter] instance exposes some of the functionality from
+[`BaseModel`][pydantic.main.BaseModel] instance methods for types that do not have such methods
+(such as dataclasses, primitive types, and more):
+
+```py
+from typing import List
+
+from typing_extensions import TypedDict
+
+from pydantic import TypeAdapter, ValidationError
+
+class User(TypedDict):
+    name: str
+    id: int
+
+UserListValidator = TypeAdapter(List[User])
+print(repr(UserListValidator.validate_python([{'name': 'Fred', 'id': '3'}])))
+#> [{'name': 'Fred', 'id': 3}]
+
+try:
+    UserListValidator.validate_python(
+        [{'name': 'Fred', 'id': 'wrong', 'other': 'no'}]
+    )
+except ValidationError as e:
+    print(e)
+    '''
+    1 validation error for list[typed-dict]
+    0.id
+      Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='wrong', input_type=str]
+    '''
+```
+
+Note:
+    Despite some overlap in use cases with [`RootModel`][pydantic.root_model.RootModel],
+    [`TypeAdapter`][pydantic.type_adapter.TypeAdapter] should not be used as a type annotation for
+    specifying fields of a `BaseModel`, etc.
+
+## Parsing data into a specified type
+
+[`TypeAdapter`][pydantic.type_adapter.TypeAdapter] can be used to apply the parsing logic to populate Pydantic models
+in a more ad-hoc way. This function behaves similarly to
+[`BaseModel.model_validate`][pydantic.main.BaseModel.model_validate],
+but works with arbitrary Pydantic-compatible types.
+
+This is especially useful when you want to parse results into a type that is not a direct subclass of
+[`BaseModel`][pydantic.main.BaseModel]. For example:
+
+```py
+from typing import List
+
+from pydantic import BaseModel, TypeAdapter
+
+class Item(BaseModel):
+    id: int
+    name: str
+
+# `item_data` could come from an API call, eg., via something like:
+# item_data = requests.get('https://my-api.com/items').json()
+item_data = [{'id': 1, 'name': 'My Item'}]
+
+items = TypeAdapter(List[Item]).validate_python(item_data)
+print(items)
+#> [Item(id=1, name='My Item')]
+```
+
+[`TypeAdapter`][pydantic.type_adapter.TypeAdapter] is capable of parsing data into any of the types Pydantic can
+handle as fields of a [`BaseModel`][pydantic.main.BaseModel].
diff --git a/mkdocs.yml b/mkdocs.yml
index 65ebf36d13e..9dcd1c8e6e1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -67,6 +67,7 @@ nav:
   - Dataclasses: concepts/dataclasses.md
   - Postponed Annotations: concepts/postponed_annotations.md
   - Strict Mode: concepts/strict_mode.md
+  - TypeAdapter: concepts/type_adapter.md
   - Validation Decorator: concepts/validation_decorator.md
   - Conversion Table: concepts/conversion_table.md
   - Settings Management: concepts/pydantic_settings.md
@@ -224,7 +225,7 @@ plugins:
       'usage/pydantic_settings.md': 'concepts/pydantic_settings.md'
       'usage/serialization.md': 'concepts/serialization.md'
       'usage/strict_mode.md': 'concepts/strict_mode.md'
-      'usage/type_adapter.md': 'api/type_adapter.md'
+      'usage/type_adapter.md': 'concepts/type_adapter.md'
       'usage/validation_decorator.md': 'concepts/validation_decorator.md'
       'usage/validators.md': 'concepts/validators.md'
       'usage/types/bytesize.md': 'api/types.md#pydantic.types.ByteSize'
diff --git a/pydantic/type_adapter.py b/pydantic/type_adapter.py
index 72d8b918f48..a0cd0caae3c 100644
--- a/pydantic/type_adapter.py
+++ b/pydantic/type_adapter.py
@@ -1,79 +1,4 @@
-"""
-You may have types that are not `BaseModel`s that you want to validate data against.
-Or you may want to validate a `List[SomeModel]`, or dump it to JSON.
-
-For use cases like this, Pydantic provides [`TypeAdapter`][pydantic.type_adapter.TypeAdapter],
-which can be used for type validation, serialization, and JSON schema generation without creating a
-[`BaseModel`][pydantic.main.BaseModel].
-
-A [`TypeAdapter`][pydantic.type_adapter.TypeAdapter] instance exposes some of the functionality from
-[`BaseModel`][pydantic.main.BaseModel] instance methods for types that do not have such methods
-(such as dataclasses, primitive types, and more):
-
-```py
-from typing import List
-
-from typing_extensions import TypedDict
-
-from pydantic import TypeAdapter, ValidationError
-
-class User(TypedDict):
-    name: str
-    id: int
-
-UserListValidator = TypeAdapter(List[User])
-print(repr(UserListValidator.validate_python([{'name': 'Fred', 'id': '3'}])))
-#> [{'name': 'Fred', 'id': 3}]
-
-try:
-    UserListValidator.validate_python(
-        [{'name': 'Fred', 'id': 'wrong', 'other': 'no'}]
-    )
-except ValidationError as e:
-    print(e)
-    '''
-    1 validation error for list[typed-dict]
-    0.id
-      Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='wrong', input_type=str]
-    '''
-```
-
-Note:
-    Despite some overlap in use cases with [`RootModel`][pydantic.root_model.RootModel],
-    [`TypeAdapter`][pydantic.type_adapter.TypeAdapter] should not be used as a type annotation for
-    specifying fields of a `BaseModel`, etc.
-
-## Parsing data into a specified type
-
-[`TypeAdapter`][pydantic.type_adapter.TypeAdapter] can be used to apply the parsing logic to populate Pydantic models
-in a more ad-hoc way. This function behaves similarly to
-[`BaseModel.model_validate`][pydantic.main.BaseModel.model_validate],
-but works with arbitrary Pydantic-compatible types.
-
-This is especially useful when you want to parse results into a type that is not a direct subclass of
-[`BaseModel`][pydantic.main.BaseModel]. For example:
-
-```py
-from typing import List
-
-from pydantic import BaseModel, TypeAdapter
-
-class Item(BaseModel):
-    id: int
-    name: str
-
-# `item_data` could come from an API call, eg., via something like:
-# item_data = requests.get('https://my-api.com/items').json()
-item_data = [{'id': 1, 'name': 'My Item'}]
-
-items = TypeAdapter(List[Item]).validate_python(item_data)
-print(items)
-#> [Item(id=1, name='My Item')]
-```
-
-[`TypeAdapter`][pydantic.type_adapter.TypeAdapter] is capable of parsing data into any of the types Pydantic can
-handle as fields of a [`BaseModel`][pydantic.main.BaseModel].
-"""  # noqa: D212
+"""Type adapter specification."""
 from __future__ import annotations as _annotations
 
 import sys


Code review comments:
diff_hunk: @@ -0,0 +1,77 @@
+You may have types that are not `BaseModel`s that you want to validate data against.
+Or you may want to validate a `List[SomeModel]`, or dump it to JSON.
+
+??? api "API Documentation"
+    [`pydantic.type_adapter.TypeAdapter`][pydantic.type_adapter.TypeAdapter]<br>
+
+For use cases like this, Pydantic provides [`TypeAdapter`][pydantic.type_adapter.TypeAdapter],
+which can be used for type validation, serialization, and JSON schema generation without creating a
+[`BaseModel`][pydantic.main.BaseModel].
+
+A [`TypeAdapter`][pydantic.type_adapter.TypeAdapter] instance exposes some of the functionality from
+[`BaseModel`][pydantic.main.BaseModel] instance methods for types that do not have such methods
+(such as dataclasses, primitive types, and more):
+
+```py
+from typing import List
+
+from typing_extensions import TypedDict
+
+from pydantic import TypeAdapter, ValidationError
+
+class User(TypedDict):
+    name: str
+    id: int
+
+UserListValidator = TypeAdapter(List[User])
path: docs/concepts/type_adapter.md
text: @user1:
```suggestion
UserListAdapter = TypeAdapter(List[User])
```
(and below).

I think better to use `Adapter` than `Validator` to help people realize it's able to do more than validation, also I just think it's a better naming convention and would want to push people toward using it as they read the docs, even if they are only doing validation with the value.

@author:
Agreed, thanks for the tip.

diff_hunk: @@ -67,6 +67,7 @@ nav:
   - Dataclasses: concepts/dataclasses.md
   - Postponed Annotations: concepts/postponed_annotations.md
   - Strict Mode: concepts/strict_mode.md
+  - TypeAdapter: concepts/type_adapter.md
path: mkdocs.yml
text: @user1:
Maybe?
```suggestion
  - Type Adapter: concepts/type_adapter.md
```