feat: Issue 678 use pydantic field examples (#679)

stardust85 · Michel Samia · web-flow · commit 36395d94a3a3 · 2025-04-14T20:46:05.000+01:00
Co-authored-by: Michel Samia &lt;secret@example.com&gt;
diff --git a/docs/examples/configuration/test_example_10.py b/docs/examples/configuration/test_example_10.py
@@ -0,0 +1,17 @@
+from pydantic import BaseModel, Field
+
+from polyfactory.factories.pydantic_factory import ModelFactory
+
+
+class Payment(BaseModel):
+    amount: int = Field(0)
+    currency: str = Field(examples=["USD", "EUR", "INR"])
+
+
+class PaymentFactory(ModelFactory[Payment]):
+    __use_examples__ = True
+
+
+def test_use_examples() -> None:
+    instance = PaymentFactory.build()
+    assert instance.currency in ["USD", "EUR", "INR"]
diff --git a/docs/usage/configuration.rst b/docs/usage/configuration.rst
@@ -130,3 +130,16 @@ By default, ``__use_defaults__`` is set to ``False.`` If you need more fine grai
 .. literalinclude:: /examples/configuration/test_example_9.py
     :caption: Use Default Values
     :language: python
+
+
+Use Example Values (Pydantic >= V2)
+-----------------------------------
+
+If ``__use_examples__`` is set to ``True``, then a random value from examples attribute will be used for a given field,
+provided there's a non-empty list of examples defined for that field.
+
+By default, ``__use_examples__`` is set to ``False.``
+
+.. literalinclude:: /examples/configuration/test_example_10.py
+    :caption: Use Examples Values
+    :language: python
diff --git a/polyfactory/factories/pydantic_factory.py b/polyfactory/factories/pydantic_factory.py
@@ -124,6 +124,7 @@ def __init__(
         default: Any = ...,
         children: list[FieldMeta] | None = None,
         constraints: PydanticConstraints | None = None,
+        examples: list[Any] | None = None,
     ) -> None:
         super().__init__(
             name=name,
@@ -133,6 +134,7 @@ def __init__(
             children=children,
             constraints=constraints,
         )
+        self.examples = examples
 
     @classmethod
     def from_field_info(
@@ -212,13 +214,15 @@ def from_field_info(
             if is_json:
                 constraints["json"] = True
 
-        return PydanticFieldMeta.from_type(
+        result = PydanticFieldMeta.from_type(
             annotation=annotation,
             children=children,
             constraints=cast("Constraints", {k: v for k, v in constraints.items() if v is not None}) or None,
             default=default_value,
             name=name,
         )
+        result.examples = field_info.examples
+        return result
 
     @classmethod
     def from_model_field(  # pragma: no cover
@@ -336,12 +340,15 @@ def from_model_field(  # pragma: no cover
                 for arg in fields_to_iterate
             )
 
+        examples = None
+
         return PydanticFieldMeta(
             name=name,
             annotation=annotation,  # pyright: ignore[reportArgumentType]
             children=children or None,
             default=default_value,
             constraints=cast("PydanticConstraints", {k: v for k, v in constraints.items() if v is not None}) or None,
+            examples=examples,
         )
 
     if not _IS_PYDANTIC_V1:
@@ -363,6 +370,28 @@ class ModelFactory(Generic[T], BaseFactory[T]):
 
     __forward_ref_resolution_type_mapping__: ClassVar[Mapping[str, type]] = {}
     __is_base_factory__ = True
+    __use_examples__: ClassVar[bool] = False  # for backwards compatibility
+    """
+    Flag indicating whether to use a random example, if provided (Pydantic >=V2)
+
+    Example code::
+
+        class Payment(BaseModel):
+            amount: int = Field(0)
+            currency: str = Field(examples=['USD', 'EUR', 'INR'])
+
+        class PaymentFactory(ModelFactory[Payment]):
+            __use_examples__ = True
+
+    >>> payment = PaymentFactory.build()
+    >>> payment
+    Payment(amount=120, currency="EUR")
+    """
+
+    __config_keys__ = (
+        *BaseFactory.__config_keys__,
+        "__use_examples__",
+    )
 
     def __init_subclass__(cls, *args: Any, **kwargs: Any) -> None:
         super().__init_subclass__(*args, **kwargs)
@@ -425,6 +454,7 @@ def get_constrained_field_value(
         build_context: BuildContext | None = None,
     ) -> Any:
         constraints = cast("PydanticConstraints", field_meta.constraints)
+
         if constraints.pop("json", None):
             value = cls.get_field_value(
                 field_meta, field_build_parameters=field_build_parameters, build_context=build_context
@@ -435,6 +465,34 @@ def get_constrained_field_value(
             annotation, field_meta, field_build_parameters=field_build_parameters, build_context=build_context
         )
 
+    @classmethod
+    def get_field_value(
+        cls,
+        field_meta: FieldMeta,
+        field_build_parameters: Any | None = None,
+        build_context: BuildContext | None = None,
+    ) -> Any:
+        """Return a value from examples if exists, else random value.
+
+        :param field_meta: FieldMeta instance.
+        :param field_build_parameters: Any build parameters passed to the factory as kwarg values.
+        :param build_context: BuildContext data for current build.
+
+        :returns: An arbitrary value.
+
+        """
+        result: Any
+
+        field_meta = cast("PydanticFieldMeta", field_meta)
+
+        if cls.__use_examples__ and field_meta.examples:
+            result = cls.__random__.choice(field_meta.examples)
+        else:
+            result = super().get_field_value(
+                field_meta=field_meta, field_build_parameters=field_build_parameters, build_context=build_context
+            )
+        return result
+
     @classmethod
     def build(
         cls,
diff --git a/tests/constraints/test_decimal_constraints.py b/tests/constraints/test_decimal_constraints.py
@@ -392,7 +392,7 @@ def test_handle_decimal_length() -> None:
 
     # here decimal places should determine max length
     max_digits = 10
-    decimal_places = 5
+    decimal_places: int | None = 5
 
     result = handle_decimal_length(decimal, decimal_places, max_digits)
     assert isinstance(result, Decimal)
diff --git a/tests/constraints/test_frozen_set_constraints.py b/tests/constraints/test_frozen_set_constraints.py
@@ -6,8 +6,7 @@
 from hypothesis.strategies import integers
 
 from polyfactory.exceptions import ParameterException
-from polyfactory.factories.pydantic_factory import ModelFactory
-from polyfactory.field_meta import FieldMeta
+from polyfactory.factories.pydantic_factory import ModelFactory, PydanticFieldMeta
 from polyfactory.value_generators.constrained_collections import (
     handle_constrained_collection,
 )
@@ -22,7 +21,7 @@ def test_handle_constrained_set_with_min_items_and_max_items(min_items: int, max
         result = handle_constrained_collection(
             collection_type=frozenset,
             factory=ModelFactory,
-            field_meta=FieldMeta(name="test", annotation=frozenset),
+            field_meta=PydanticFieldMeta(name="test", annotation=frozenset),
             item_type=str,
             max_items=max_items,
             min_items=min_items,
@@ -34,7 +33,7 @@ def test_handle_constrained_set_with_min_items_and_max_items(min_items: int, max
             handle_constrained_collection(
                 collection_type=frozenset,
                 factory=ModelFactory,
-                field_meta=FieldMeta(name="test", annotation=frozenset),
+                field_meta=PydanticFieldMeta(name="test", annotation=frozenset),
                 item_type=str,
                 max_items=max_items,
                 min_items=min_items,
@@ -50,7 +49,7 @@ def test_handle_constrained_set_with_max_items(
     result = handle_constrained_collection(
         collection_type=frozenset,
         factory=ModelFactory,
-        field_meta=FieldMeta(name="test", annotation=frozenset),
+        field_meta=PydanticFieldMeta(name="test", annotation=frozenset),
         item_type=str,
         max_items=max_items,
     )
@@ -66,7 +65,7 @@ def test_handle_constrained_set_with_min_items(
     result = handle_constrained_collection(
         collection_type=frozenset,
         factory=ModelFactory,
-        field_meta=FieldMeta(name="test", annotation=frozenset),
+        field_meta=PydanticFieldMeta(name="test", annotation=frozenset),
         item_type=str,
         min_items=min_items,
     )
@@ -79,7 +78,7 @@ def test_handle_constrained_set_with_different_types(t_type: Any) -> None:
         result = handle_constrained_collection(
             collection_type=frozenset,
             factory=ModelFactory,
-            field_meta=FieldMeta(name="test", annotation=frozenset),
+            field_meta=PydanticFieldMeta(name="test", annotation=frozenset),
             item_type=t_type,
         )
         assert len(result) >= 0
diff --git a/tests/constraints/test_list_constraints.py b/tests/constraints/test_list_constraints.py
@@ -8,8 +8,7 @@
 from pydantic import VERSION
 
 from polyfactory.exceptions import ParameterException
-from polyfactory.factories.pydantic_factory import ModelFactory
-from polyfactory.field_meta import FieldMeta
+from polyfactory.factories.pydantic_factory import ModelFactory, PydanticFieldMeta
 from polyfactory.value_generators.constrained_collections import (
     handle_constrained_collection,
 )
@@ -24,7 +23,7 @@ def test_handle_constrained_list_with_min_items_and_max_items(min_items: int, ma
         result = handle_constrained_collection(
             collection_type=list,
             factory=ModelFactory,
-            field_meta=FieldMeta(name="test", annotation=list),
+            field_meta=PydanticFieldMeta(name="test", annotation=list),
             item_type=str,
             max_items=max_items,
             min_items=min_items,
@@ -36,7 +35,7 @@ def test_handle_constrained_list_with_min_items_and_max_items(min_items: int, ma
             handle_constrained_collection(
                 collection_type=list,
                 factory=ModelFactory,
-                field_meta=FieldMeta(name="test", annotation=list),
+                field_meta=PydanticFieldMeta(name="test", annotation=list),
                 item_type=str,
                 max_items=max_items,
                 min_items=min_items,
@@ -52,7 +51,7 @@ def test_handle_constrained_list_with_max_items(
     result = handle_constrained_collection(
         collection_type=list,
         factory=ModelFactory,
-        field_meta=FieldMeta(name="test", annotation=list),
+        field_meta=PydanticFieldMeta(name="test", annotation=list),
         item_type=str,
         max_items=max_items,
     )
@@ -68,7 +67,7 @@ def test_handle_constrained_list_with_min_items(
     result = handle_constrained_collection(
         collection_type=list,
         factory=ModelFactory,
-        field_meta=FieldMeta.from_type(List[str], name="test"),
+        field_meta=PydanticFieldMeta.from_type(List[str], name="test"),
         item_type=str,
         min_items=min_items,
     )
@@ -81,7 +80,7 @@ def test_handle_constrained_list_with_min_items(
 )
 @pytest.mark.parametrize("t_type", tuple(ModelFactory.get_provider_map()))
 def test_handle_constrained_list_with_different_types(t_type: Any) -> None:
-    field_meta = FieldMeta.from_type(List[t_type], name="test")
+    field_meta = PydanticFieldMeta.from_type(List[t_type], name="test")
     result = handle_constrained_collection(
         collection_type=list,
         factory=ModelFactory,
@@ -92,7 +91,7 @@ def test_handle_constrained_list_with_different_types(t_type: Any) -> None:
 
 
 def test_handle_unique_items() -> None:
-    field_meta = FieldMeta.from_type(List[str], name="test", constraints={"unique_items": True})
+    field_meta = PydanticFieldMeta.from_type(List[str], name="test", constraints={"unique_items": True})
     result = handle_constrained_collection(
         collection_type=list,
         factory=ModelFactory,
diff --git a/tests/constraints/test_mapping_constraints.py b/tests/constraints/test_mapping_constraints.py
@@ -3,8 +3,7 @@
 from hypothesis.strategies import integers
 
 from polyfactory.exceptions import ParameterException
-from polyfactory.factories.pydantic_factory import ModelFactory
-from polyfactory.field_meta import FieldMeta
+from polyfactory.factories.pydantic_factory import ModelFactory, PydanticFieldMeta
 from polyfactory.value_generators.constrained_collections import (
     handle_constrained_mapping,
 )
@@ -15,9 +14,9 @@
     integers(min_value=0, max_value=10),
 )
 def test_handle_constrained_mapping_with_min_items_and_max_items(min_items: int, max_items: int) -> None:
-    key_field = FieldMeta(name="key", annotation=str)
-    value_field = FieldMeta(name="value", annotation=int)
-    field_meta = FieldMeta(name="test", annotation=dict, children=[key_field, value_field])
+    key_field = PydanticFieldMeta(name="key", annotation=str)
+    value_field = PydanticFieldMeta(name="value", annotation=int)
+    field_meta = PydanticFieldMeta(name="test", annotation=dict, children=[key_field, value_field])
 
     if max_items >= min_items:
         result = handle_constrained_mapping(
@@ -47,9 +46,9 @@ def test_handle_constrained_mapping_with_constrained_key_and_value() -> None:
     min_length = 5
     max_length = 10
 
-    key_field = FieldMeta(name="key", annotation=str, constraints={"min_length": key_min_length})
-    value_field = FieldMeta(name="value", annotation=int, constraints={"gt": value_gt})
-    field_meta = FieldMeta(name="test", annotation=dict, children=[key_field, value_field])
+    key_field = PydanticFieldMeta(name="key", annotation=str, constraints={"min_length": key_min_length})
+    value_field = PydanticFieldMeta(name="value", annotation=int, constraints={"gt": value_gt})
+    field_meta = PydanticFieldMeta(name="test", annotation=dict, children=[key_field, value_field])
 
     result = handle_constrained_mapping(
         factory=ModelFactory,
diff --git a/tests/constraints/test_set_constraints.py b/tests/constraints/test_set_constraints.py
@@ -6,8 +6,7 @@
 from hypothesis.strategies import integers
 
 from polyfactory.exceptions import ParameterException
-from polyfactory.factories.pydantic_factory import ModelFactory
-from polyfactory.field_meta import FieldMeta
+from polyfactory.factories.pydantic_factory import ModelFactory, PydanticFieldMeta
 from polyfactory.value_generators.constrained_collections import (
     handle_constrained_collection,
 )
@@ -22,7 +21,7 @@ def test_handle_constrained_set_with_min_items_and_max_items(min_items: int, max
         result = handle_constrained_collection(
             collection_type=list,
             factory=ModelFactory,
-            field_meta=FieldMeta(name="test", annotation=set),
+            field_meta=PydanticFieldMeta(name="test", annotation=set),
             item_type=str,
             max_items=max_items,
             min_items=min_items,
@@ -34,7 +33,7 @@ def test_handle_constrained_set_with_min_items_and_max_items(min_items: int, max
             handle_constrained_collection(
                 collection_type=list,
                 factory=ModelFactory,
-                field_meta=FieldMeta(name="test", annotation=set),
+                field_meta=PydanticFieldMeta(name="test", annotation=set),
                 item_type=str,
                 max_items=max_items,
                 min_items=min_items,
@@ -50,7 +49,7 @@ def test_handle_constrained_set_with_max_items(
     result = handle_constrained_collection(
         collection_type=list,
         factory=ModelFactory,
-        field_meta=FieldMeta(name="test", annotation=set),
+        field_meta=PydanticFieldMeta(name="test", annotation=set),
         item_type=str,
         max_items=max_items,
     )
@@ -66,7 +65,7 @@ def test_handle_constrained_set_with_min_items(
     result = handle_constrained_collection(
         collection_type=list,
         factory=ModelFactory,
-        field_meta=FieldMeta(name="test", annotation=set),
+        field_meta=PydanticFieldMeta(name="test", annotation=set),
         item_type=str,
         min_items=min_items,
     )
@@ -79,7 +78,7 @@ def test_handle_constrained_set_with_different_types(t_type: Any) -> None:
         result = handle_constrained_collection(
             collection_type=list,
             factory=ModelFactory,
-            field_meta=FieldMeta(name="test", annotation=set),
+            field_meta=PydanticFieldMeta(name="test", annotation=set),
             item_type=t_type,
         )
         assert len(result) >= 0
diff --git a/tests/test_pydantic_factory.py b/tests/test_pydantic_factory.py
