feat: add PEP 695 type alias support and improve type handling (#711)

Author: Rub1kCube

polyfactory/factories/base.py

@@ -65,7 +65,14 @@
     unwrap_optional,
 )
 from polyfactory.utils.model_coverage import CoverageContainer, CoverageContainerCallable, resolve_kwargs_coverage
-from polyfactory.utils.predicates import get_type_origin, is_literal, is_optional, is_safe_subclass, is_union
+from polyfactory.utils.predicates import (
+    get_type_origin,
+    is_literal,
+    is_optional,
+    is_safe_subclass,
+    is_type_var,
+    is_union,
+)
 from polyfactory.utils.types import NoneType
 from polyfactory.value_generators.complex_types import handle_collection_type, handle_collection_type_coverage
 from polyfactory.value_generators.constrained_collections import (
@@ -280,7 +287,7 @@ class Foo(ModelFactory[MyModel]):  # <<< MyModel
             b for b in get_original_bases(cls) if get_origin(b) and issubclass(get_origin(b), BaseFactory)
         )
         generic_args: Sequence[type[T]] = [
-            arg for factory_base in factory_bases for arg in get_args(factory_base) if not isinstance(arg, TypeVar)
+            arg for factory_base in factory_bases for arg in get_args(factory_base) if not is_type_var(arg)
         ]
         if len(generic_args) != 1:
             return None
@@ -851,7 +858,7 @@ def get_field_value(  # noqa: C901, PLR0911, PLR0912
         if provider := (provider_map.get(field_meta.annotation) or provider_map.get(unwrapped_annotation)):
             return provider()
 
-        if isinstance(unwrapped_annotation, TypeVar):
+        if is_type_var(unwrapped_annotation):
             return create_random_string(cls.__random__, min_length=1, max_length=10)
 
         if callable(unwrapped_annotation):
@@ -933,7 +940,7 @@ def get_field_value_coverage(  # noqa: C901,PLR0912
             ):
                 yield CoverageContainerCallable(provider)
 
-            elif isinstance(unwrapped_annotation, TypeVar):
+            elif is_type_var(unwrapped_annotation):
                 yield create_random_string(cls.__random__, min_length=1, max_length=10)
 
             elif callable(unwrapped_annotation):

polyfactory/factories/pydantic_factory.py

@@ -16,6 +16,7 @@
 from polyfactory.field_meta import Constraints, FieldMeta, Null
 from polyfactory.utils.deprecation import check_for_deprecated_parameters
 from polyfactory.utils.helpers import unwrap_new_type, unwrap_optional
+from polyfactory.utils.normalize_type import normalize_type
 from polyfactory.utils.predicates import is_annotated, is_optional, is_safe_subclass, is_union
 from polyfactory.utils.types import NoneType
 from polyfactory.value_generators.primitives import create_random_bytes
@@ -167,6 +168,10 @@ def from_field_info(
                 ("random", random),
             ),
         )
+        field_info = FieldInfo.merge_field_infos(
+            field_info, FieldInfo.from_annotation(normalize_type(field_info.annotation))
+        )
+
         if callable(field_info.default_factory):
             default_value = field_info.default_factory
         else:
@@ -220,7 +225,7 @@ def from_field_info(
             if is_json:
                 constraints["json"] = True
 
-        result = PydanticFieldMeta.from_type(
+        result = super().from_type(
             annotation=annotation,
             children=children,
             constraints=cast("Constraints", {k: v for k, v in constraints.items() if v is not None}) or None,

polyfactory/field_meta.py

@@ -9,6 +9,7 @@
 from polyfactory.constants import DEFAULT_RANDOM, TYPE_MAPPING
 from polyfactory.utils.deprecation import check_for_deprecated_parameters
 from polyfactory.utils.helpers import get_annotation_metadata, is_dataclass_instance, unwrap_annotated, unwrap_new_type
+from polyfactory.utils.normalize_type import normalize_type
 from polyfactory.utils.predicates import is_annotated
 from polyfactory.utils.types import NoneType
 
@@ -139,6 +140,7 @@ def from_type(
             ),
         )
 
+        annotation = normalize_type(annotation)
         annotated = is_annotated(annotation)
         if not constraints and annotated:
             metadata = cls.get_constraints_metadata(annotation)

polyfactory/utils/normalize_type.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Any, Mapping, Union
+
+from typing_extensions import Annotated, get_args, get_origin
+
+from polyfactory.utils.predicates import (
+    is_generic_alias,
+    is_type_alias,
+    is_type_var,
+    is_union,
+)
+
+
+def normalize_type(type_annotation: Any) -> Any:
+    """Convert modern Python 3.12+ type syntax to standard annotations.
+
+    Handles TypeAliasType and GenericAlias types introduced in Python 3.12+,
+    converting them to standard type annotations when needed.
+
+    Args:
+        type_annotation: Type to normalize (convert if needed or pass through).
+
+    Returns:
+        Normalized type annotation with resolved type aliases and substituted parameters.
+
+    Example:
+        ```python
+        # Python 3.12+
+        >> from typing import Annotated
+        >> import annotated_types as at
+
+        >> type NegativeInt = Annotated[int, at.Lt(0)]
+        >> type NonEmptyList[T] = Annotated[list[T], at.Len(1)]
+
+        >> normalize_type(NonEmptyList[NegativeInt])
+        # typing.Annotated[list[typing.Annotated[int, Lt(lt=0)]], Len(min_length=1, max_length=None)]
+        ```
+    """
+
+    if is_type_alias(type_annotation):
+        return type_annotation.__value__
+
+    if not is_generic_alias(type_annotation):
+        return type_annotation
+
+    origin = get_origin(type_annotation)
+    args = get_args(type_annotation)
+
+    if is_type_alias(origin):
+        return __handle_generic_type_alias(origin, args)
+
+    if args:
+        normalized_args = tuple(normalize_type(arg) for arg in args)
+        if normalized_args != args:
+            return origin[normalized_args[0] if len(normalized_args) == 1 else normalized_args]
+
+    return type_annotation
+
+
+def __handle_generic_type_alias(origin: Any, args: tuple) -> Any:
+    """Handle generic type alias with parameters."""
+    template = origin.__value__
+    type_params = origin.__type_params__
+
+    if not (type_params and args):
+        return template
+
+    normalized_args = tuple(normalize_type(arg) for arg in args)
+    substitutions = dict(zip(type_params, normalized_args))
+
+    if get_origin(template) is Annotated:
+        base_type, *metadata = get_args(template)
+        template_result = Annotated[tuple([__apply_substitutions(base_type, substitutions)] + metadata)]  # type: ignore[valid-type]
+    else:
+        template_result = __apply_substitutions(template, substitutions)
+
+    return template_result
+
+
+def __apply_substitutions(target: Any, subs: Mapping[Any, Any]) -> Any:
+    if is_type_var(target):
+        return subs.get(target, target)
+
+    if is_union(target):
+        args = tuple(__apply_substitutions(arg, subs) for arg in get_args(target))
+        return Union[args]
+
+    origin = get_origin(target)
+    args = get_args(target)
+
+    if is_type_alias(origin):
+        sub_args = tuple(__apply_substitutions(arg, subs) for arg in args) if args else ()
+        return normalize_type(origin[sub_args] if sub_args else origin)
+
+    if origin and args:
+        sub_args = tuple(__apply_substitutions(arg, subs) for arg in args)
+        return origin[sub_args[0] if len(sub_args) == 1 else sub_args]
+
+    return target

polyfactory/utils/predicates.py

@@ -147,6 +147,28 @@ def is_type_alias(annotation: Any) -> TypeGuard[TypeAliasType]:
     return isinstance(annotation, AllTypeAliasTypes)
 
 
+def is_generic_alias(annotation: Any) -> bool:
+    """Determine if the given type annotation is a generic alias.
+
+    :param annotation: A type annotation.
+
+    :returns: A boolean
+    """
+    return hasattr(annotation, "__origin__") and hasattr(annotation, "__args__")
+
+
+def is_type_var(annotation: Any) -> TypeGuard[TypeVar]:
+    """Determine if the given type annotation is a TypeVar.
+
+    Args:
+        annotation: A type annotation.
+
+    Returns:
+        A boolean.
+    """
+    return isinstance(annotation, TypeVar)
+
+
 def get_type_origin(annotation: Any) -> Any:
     """Get the type origin of an annotation - safely.
 

tests/test_dataclass_factory.py

@@ -1,4 +1,6 @@
 import dataclasses
+import sys
+import textwrap
 from dataclasses import dataclass as vanilla_dataclass
 from dataclasses import field
 from types import ModuleType
@@ -351,3 +353,23 @@ class AFactory(DataclassFactory[A]):
 
         if isinstance(a.c, list):
             assert all(isinstance(value, int) for value in a.c)
+
+
+@pytest.mark.skipif(sys.version_info < (3, 12), reason="PEP 695 requires Python 3.12+")
+def test_pep695_dict_union_types(create_module: Callable[[str], ModuleType]) -> None:
+    """Test type aliases with dict unions."""
+    module = create_module(
+        textwrap.dedent("""
+            from dataclasses import dataclass
+
+            type IntDict = dict[str, int]
+            type StrDict = dict[str, str]
+            type MixedDict = IntDict | StrDict
+
+            @dataclass
+            class Foo:
+                data: MixedDict
+                nested: dict[str, MixedDict]
+        """)
+    )
+    DataclassFactory.create_factory(module.Foo).build()