pydantic · sydney-runkle · Jun 6, 2024 · May 20, 2024 · May 20, 2024 · May 20, 2024
diff --git a/docs/api/experimental.md b/docs/api/experimental.md
@@ -0,0 +1 @@
+::: pydantic.experimental
diff --git a/docs/concepts/experimental.md b/docs/concepts/experimental.md
@@ -0,0 +1,76 @@
+# Experimental Features
+
+In this section you will find documentation for new, experimental features in Pydantic. These features are subject to change or removal, and we are looking for feedback and suggestions before making them a permanent part of Pydantic.
+
+<!-- TODO: (@sydney-runkle) add link to versioning policy for experimental features -->
+
+## Pipeline API
+
+Pydantic v2.8.0 introduced an experimental "pipeline" API that allows composing parsing, constraints and transformations in a more type-safe manner than existing APIs. This API is subject to change or removal, we are looking for feedback and suggestions before making it a permanent part of Pydantic.
+
+```python
+from __future__ import annotations
+
+from datetime import datetime
+
+from typing_extensions import Annotated
+
+from pydantic import BaseModel
+from pydantic.experimental.pipeline import parse, parse_defer
+
+
+class User(BaseModel):
+    name: Annotated[str, parse(str).str.lower()]  # (1)!
+    age: Annotated[int, parse(int).gt(0)]  # (2)!
+    username: Annotated[str, parse(str).str.pattern(r'[a-z]+')]  # (3)!
+    password: Annotated[
+        str,
+        parse(str)
+        .transform(str.lower)
+        .predicate(lambda x: x != 'password'),  # (4)!
+    ]
+    favorite_number: Annotated[  # (5)!
+        int,
+        (parse(int) | parse(str).str.strip().parse(int)).gt(0),
+    ]
+    friends: Annotated[list[User], parse().len(0, 100)]  # (6)!
+    family: Annotated[  # (7)!
+        list[User],
+        parse_defer(lambda: list[User]).transform(lambda x: x[1:]),
+    ]
+    bio: Annotated[
+        datetime, parse(int).transform(lambda x: x / 1_000_000).parse()  # (8)!
+    ]
+```
+
+1. Lowercase a string.
+2. Constrain an integer to be greater than zero.
+3. Constrain a string to match a regex pattern.
+4. You can also use the lower level transform, constrain and predicate methods.
+5. Use the `|` or `&` operators to combine steps (like a logical OR or AND).
+6. Calling `parse()` with no arguments implies `parse(<field type>)`. Use `parse(Any)` to accept any type.
+7. For recursive types you can use `parse_defer` to reference the type itself before it's defined.
+8. You can call `parse()` before or after other steps to do pre or post processing.
+
+### Mapping from `BeforeValidator`, `AfterValidator` and `WrapValidator`
+
+The `parse` method is a more type-safe way to define `BeforeValidator`, `AfterValidator` and `WrapValidator`:
+
+```python
+from typing_extensions import Annotated
+
+from pydantic.experimental.pipeline import parse, transform
+
 # BeforeValidator
+Annotated[int, parse(str).str.strip().parse()]  # (1)!
+# AfterValidator
+Annotated[int, transform(lambda x: x * 2)]  # (2)!
+# WrapValidator
+Annotated[
+    int, parse(str).str.strip().parse().transform(lambda x: x * 2)  # (3)!
+]
+```
+
+1. Strip whitespace from a string before parsing it as an integer.
+2. Multiply an integer by 2 after parsing it.
+3. Strip whitespace from a string, parse it as an integer, then multiply it by 2.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -104,6 +104,7 @@ nav:
   - Settings Management: concepts/pydantic_settings.md
   - Performance: concepts/performance.md
   - Pydantic Plugins: concepts/plugins.md
+  - Experimental: concepts/experimental.md
 - API Documentation:
   - Pydantic:
     - BaseModel: api/base_model.md
@@ -124,6 +125,7 @@ nav:
     - Version Information: api/version.md
     - Pydantic Plugins: api/plugin.md
     - Annotated Handlers: api/annotated_handlers.md
+    - Experimental: api/experimental.md
   - Pydantic Core:
     - pydantic_core: api/pydantic_core.md
     - pydantic_core.core_schema: api/pydantic_core_schema.md

diff --git a/pydantic/__init__.py b/pydantic/__init__.py
@@ -45,7 +45,12 @@
     from .type_adapter import TypeAdapter
     from .types import *
     from .validate_call_decorator import validate_call
-    from .warnings import PydanticDeprecatedSince20, PydanticDeprecatedSince26, PydanticDeprecationWarning
+    from .warnings import (
+        PydanticDeprecatedSince20,
+        PydanticDeprecatedSince26,
+        PydanticDeprecationWarning,
+        PydanticExperimentalWarning,
+    )
 
     # this encourages pycharm to import `ValidationError` from here, not pydantic_core
     ValidationError = pydantic_core.ValidationError
@@ -203,6 +208,7 @@
     'PydanticDeprecatedSince20',
     'PydanticDeprecatedSince26',
     'PydanticDeprecationWarning',
+    'PydanticExperimentalWarning',
     # annotated handlers
     'GetCoreSchemaHandler',
     'GetJsonSchemaHandler',
@@ -354,6 +360,7 @@
     'PydanticDeprecatedSince20': (__spec__.parent, '.warnings'),
     'PydanticDeprecatedSince26': (__spec__.parent, '.warnings'),
     'PydanticDeprecationWarning': (__spec__.parent, '.warnings'),
+    'PydanticExperimentalWarning': (__spec__.parent, '.warnings'),
     # annotated handlers
     'GetCoreSchemaHandler': (__spec__.parent, '.annotated_handlers'),
     'GetJsonSchemaHandler': (__spec__.parent, '.annotated_handlers'),

diff --git a/pydantic/_internal/_generate_schema.py b/pydantic/_internal/_generate_schema.py
@@ -1805,7 +1805,7 @@ def _apply_annotations(
         pydantic_js_annotation_functions: list[GetJsonSchemaFunction] = []
 
         def inner_handler(obj: Any) -> CoreSchema:
-            from_property = self._generate_schema_from_property(obj, obj)
+            from_property = self._generate_schema_from_property(obj, source_type)
             if from_property is None:
                 schema = self._generate_schema_inner(obj)
             else:

diff --git a/pydantic/_internal/_internal_dataclass.py b/pydantic/_internal/_internal_dataclass.py
@@ -1,7 +1,4 @@
 import sys
-from typing import Any, Dict
-
-dataclass_kwargs: Dict[str, Any]
 
 # `slots` is available on Python >= 3.10
 if sys.version_info >= (3, 10):

diff --git a/pydantic/experimental/__init__.py b/pydantic/experimental/__init__.py
@@ -0,0 +1,10 @@
+"""The "experimental" module of pydantic contains potential new features that are subject to change."""
+
+import warnings
+
+from pydantic.warnings import PydanticExperimentalWarning
+
+warnings.warn(
+    'This module is experimental, its contents are subject to change and deprecation.',
+    category=PydanticExperimentalWarning,
+)