Fix JSON decoding for parameterized PEP 695 type aliases (#780)

hramezani · claude · web-flow · commit acf8c14f5ec3 · 2026-02-18T08:22:42.000Z
Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/pydantic_settings/sources/base.py b/pydantic_settings/sources/base.py
@@ -15,7 +15,6 @@
 )
 from pydantic._internal._utils import deep_update, is_model_class
 from pydantic.fields import FieldInfo
-from typing_inspection import typing_objects
 from typing_inspection.introspection import is_union_origin
 
 from ..exceptions import SettingsError
@@ -26,6 +25,7 @@
     _get_alias_names,
     _get_field_metadata,
     _get_model_fields,
+    _resolve_type_alias,
     _strip_annotated,
     _union_is_complex,
 )
@@ -402,10 +402,8 @@ def _extract_field_info(self, field: FieldInfo, field_name: str) -> list[tuple[s
                 field_info.append((v_alias, self._apply_case_sensitive(env_prefix + v_alias), False))
 
         if not v_alias or self.config.get('populate_by_name', False) or self.config.get('validate_by_name', False):
-            annotation = field.annotation
+            annotation = _strip_annotated(_resolve_type_alias(field.annotation))
             env_prefix = self.env_prefix if self.env_prefix_target in ('variable', 'all') else ''
-            if typing_objects.is_typealiastype(annotation) or typing_objects.is_typealiastype(get_origin(annotation)):
-                annotation = _strip_annotated(annotation.__value__)  # type: ignore[union-attr]
             if is_union_origin(get_origin(annotation)) and _union_is_complex(annotation, field.metadata):
                 field_info.append((field_name, self._apply_case_sensitive(env_prefix + field_name), True))
             else:
diff --git a/pydantic_settings/sources/utils.py b/pydantic_settings/sources/utils.py
@@ -6,7 +6,7 @@
 from collections.abc import Mapping, Sequence
 from dataclasses import is_dataclass
 from enum import Enum
-from typing import Any, cast, get_args, get_origin
+from typing import Any, TypeVar, cast, get_args, get_origin
 
 from pydantic import BaseModel, Json, RootModel, Secret
 from pydantic._internal._utils import is_model_class
@@ -40,11 +40,49 @@ def parse_env_vars(
     }
 
 
+def _substitute_typevars(tp: Any, param_map: dict[Any, Any]) -> Any:
+    """Substitute TypeVars in a type annotation with concrete types from param_map."""
+    if isinstance(tp, TypeVar) and tp in param_map:
+        return param_map[tp]
+    args = get_args(tp)
+    if not args:
+        return tp
+    new_args = tuple(_substitute_typevars(arg, param_map) for arg in args)
+    if new_args == args:
+        return tp
+    origin = get_origin(tp)
+    if origin is not None:
+        try:
+            return origin[new_args]
+        except TypeError:
+            # types.UnionType and similar are not directly subscriptable,
+            # reconstruct using | operator
+            import functools
+            import operator
+
+            return functools.reduce(operator.or_, new_args)
+    return tp
+
+
+def _resolve_type_alias(annotation: Any) -> Any:
+    """Resolve a TypeAliasType to its underlying value, substituting type params if parameterized."""
+    if typing_objects.is_typealiastype(annotation):
+        return annotation.__value__
+    origin = get_origin(annotation)
+    if typing_objects.is_typealiastype(origin):
+        type_params = getattr(origin, '__type_params__', ())
+        type_args = get_args(annotation)
+        value = origin.__value__
+        if type_params and type_args:
+            return _substitute_typevars(value, dict(zip(type_params, type_args)))
+        return value
+    return annotation
+
+
 def _annotation_is_complex(annotation: Any, metadata: list[Any]) -> bool:
     # If the model is a root model, the root annotation should be used to
     # evaluate the complexity.
-    if typing_objects.is_typealiastype(annotation) or typing_objects.is_typealiastype(get_origin(annotation)):
-        annotation = annotation.__value__
+    annotation = _resolve_type_alias(annotation)
     if annotation is not None and _lenient_issubclass(annotation, RootModel) and annotation is not RootModel:
         annotation = cast('type[RootModel[Any]]', annotation)
         root_annotation = annotation.model_fields['root'].annotation
@@ -74,10 +112,8 @@ def _annotation_is_complex(annotation: Any, metadata: list[Any]) -> bool:
 
 
 def _get_field_metadata(field: FieldInfo) -> list[Any]:
-    annotation = field.annotation
+    annotation = _resolve_type_alias(field.annotation)
     metadata = field.metadata
-    if typing_objects.is_typealiastype(annotation) or typing_objects.is_typealiastype(get_origin(annotation)):
-        annotation = annotation.__value__  # type: ignore[union-attr]
     origin = get_origin(annotation)
     if typing_objects.is_annotated(origin):
         _, *meta = get_args(annotation)
@@ -240,6 +276,7 @@ def _is_function(obj: Any) -> bool:
     '_get_model_fields',
     '_is_function',
     '_parse_env_none_str',
+    '_resolve_type_alias',
     '_strip_annotated',
     '_union_is_complex',
     'parse_env_vars',
diff --git a/tests/test_settings.py b/tests/test_settings.py
@@ -499,6 +499,44 @@ class AnnotatedComplexSettings(BaseSettings):
     assert s.apples == ['russet', 'granny smith']
 
 
+def test_annotated_with_parameterized_type_alias(env):
+    """https://github.com/pydantic/pydantic-settings/issues/778.
+
+    Parameterized PEP 695 type aliases should correctly substitute type params
+    when determining if a field is complex.
+    """
+    from annotated_types import Len
+
+    T = TypeVar('T')
+
+    MaxLenA = Annotated[T, Len(max_length=4)]
+    MaxLenB = TypeAliasType('MaxLenB', Annotated[T, Len(max_length=4)], type_params=(T,))
+    MaxLenC = TypeAliasType('MaxLenC', Annotated[T, Len(max_length=4), ForceDecode], type_params=(T,))
+
+    class MySettingsA(BaseSettings):
+        SIMPLE_LIST: MaxLenA[list[str]]
+
+    class MySettingsB(BaseSettings):
+        SIMPLE_LIST: MaxLenB[list[str]]
+
+    class MySettingsC(BaseSettings):
+        SIMPLE_LIST: MaxLenC[list[str]]
+
+    env.set('SIMPLE_LIST', '["a", "b", "c"]')
+    assert MySettingsA().SIMPLE_LIST == ['a', 'b', 'c']
+    assert MySettingsB().SIMPLE_LIST == ['a', 'b', 'c']
+    assert MySettingsC().SIMPLE_LIST == ['a', 'b', 'c']
+
+    # NoDecode should prevent automatic JSON decoding
+    MaxLenD = TypeAliasType('MaxLenD', Annotated[T, Len(max_length=4), NoDecode], type_params=(T,))
+
+    class MySettingsD(BaseSettings):
+        SIMPLE_LIST: MaxLenD[list[str]]
+
+    with pytest.raises(ValidationError):
+        MySettingsD()
+
+
 def test_annotated_with_type_no_decode(env):
     A = TypeAliasType('A', Annotated[list[str], NoDecode])
 
