move things around for expeirmental pattern

pydantic · sydney-runkle · Jun 6, 2024 · May 20, 2024 · May 20, 2024 · May 20, 2024
commit f55b6e1263c91c0045ae038343b119ba90a0bb88
diff --git a/docs/concepts/experimental.md b/docs/concepts/experimental.md
@@ -0,0 +1,65 @@
+# 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
+# BeforeValidator
+Annotated[int, parse(str).str.strip().parse()]  # (1)!
+# AfterValidator
+Annotated[int, parse().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/docs/concepts/types.md b/docs/concepts/types.md
@@ -122,66 +122,6 @@ except ValidationError as exc:
     """
 ```
 
-#### Experimental 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.transform_experimental 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
-# BeforeValidator
-Annotated[int, parse(str).str.strip().parse()]  # (1)!
-# AfterValidator
-Annotated[int, parse().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.
-
 #### Adding validation and serialization
 
 You can add or override validation, serialization, and JSON schemas to an arbitrary type using the markers that

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/experimental/__init__.py b/pydantic/experimental/__init__.py
@@ -0,0 +1 @@
+"""__init__.py for the experimental submodule of pydantic."""
diff --git a/pydantic/transform_experimental.py → pydantic/experimental/pipeline.py b/pydantic/transform_experimental.py → pydantic/experimental/pipeline.py
@@ -10,9 +10,10 @@
 from dataclasses import dataclass
 from decimal import Decimal
 from functools import cached_property, partial
-from typing import TYPE_CHECKING, Annotated, Any, Callable, Generic, Protocol, TypeVar, Union, overload
+from typing import TYPE_CHECKING, Any, Callable, Generic, Protocol, TypeVar, Union, overload
 
 import annotated_types
+from typing_extensions import Annotated
 
 if TYPE_CHECKING:
     from pydantic_core import core_schema as cs

diff --git a/tests/test_transform.py → tests/test_pipeline.py b/tests/test_transform.py → tests/test_pipeline.py
@@ -7,7 +7,7 @@
 from typing_extensions import Annotated
 
 from pydantic import TypeAdapter, ValidationError
-from pydantic.transform_experimental import parse
+from pydantic.experimental.pipeline import parse
 
 
 @pytest.mark.parametrize('potato_variation', ['potato', ' potato ', ' potato', 'potato ', ' POTATO ', ' PoTatO '])

diff --git a/text.txt b/text.txt
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		"""__init__.py for the experimental submodule of pydantic."""
sydney-runkle marked this conversation as resolved. Outdated Show resolved Hide resolved