@typespec/http-client-python 0.32.0 → 0.34.0

package/generator/pygen/codegen/models/model_type.py

@@ -77,11 +77,19 @@ class ModelType(BaseType):  # pylint: disable=too-many-instance-attributes, too-
         self.cross_language_definition_id: Optional[str] = self.yaml_data.get("crossLanguageDefinitionId")
         self.usage: int = self.yaml_data.get("usage", UsageFlags.Input.value | UsageFlags.Output.value)
         self.client_namespace: str = self.yaml_data.get("clientNamespace", code_model.namespace)
+        self.is_typed_dict_only: bool = (
+            self.yaml_data.get("typedDictOnly", False) or code_model.options["models-mode"] == "typeddict"
+        )
 
     @property
     def is_usage_output(self) -> bool:
         return bool(self.usage & UsageFlags.Output.value)
 
+    @property
+    def is_used_in_operations_via_types(self) -> bool:
+        """Whether this model would be imported from types.py (not models) in operations."""
+        return False
+
     @property
     def flattened_property(self) -> Optional[Property]:
         try:
@@ -275,12 +283,20 @@ class GeneratedModelType(ModelType):
     def type_annotation(self, **kwargs: Any) -> str:
         is_operation_file = kwargs.pop("is_operation_file", False)
         skip_quote = kwargs.get("skip_quote", False)
+        serialize_namespace_type = kwargs.get("serialize_namespace_type")
         module_name = ""
-        if kwargs.get("need_model_alias", True):
+        # In types.py, use bare name to avoid pyright "variable in type expression" errors
+        if serialize_namespace_type == NamespaceType.TYPES_FILE:
+            pass  # no module prefix, no internal file prefix
+        elif kwargs.get("need_model_alias", True):
             serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
             model_alias = self.code_model.get_unique_models_alias(serialize_namespace, self.client_namespace)
             module_name = f"{model_alias}."
-        file_name = f"{self.code_model.models_filename}." if self.internal else ""
+        file_name = (
+            f"{self.code_model.models_filename}."
+            if self.internal and serialize_namespace_type != NamespaceType.TYPES_FILE
+            else ""
+        )
         retval = module_name + file_name + self.name
         return retval if is_operation_file or skip_quote else f'"{retval}"'
 
@@ -305,7 +321,7 @@ class GeneratedModelType(ModelType):
         alias = self.code_model.get_unique_models_alias(serialize_namespace, self.client_namespace)
         serialize_namespace_type = kwargs.get("serialize_namespace_type")
         called_by_property = kwargs.get("called_by_property", False)
-        # add import for models in operations or _types file
+        # add import for models in operations, types, or unions file
         if serialize_namespace_type in [NamespaceType.OPERATION, NamespaceType.CLIENT]:
             file_import.add_submodule_import(
                 relative_path,
@@ -320,7 +336,33 @@ class GeneratedModelType(ModelType):
                     ImportType.LOCAL,
                     alias="_Model",
                 )
-        elif serialize_namespace_type == NamespaceType.TYPES_FILE or (
+        elif serialize_namespace_type == NamespaceType.TYPES_FILE:
+            # Don't import models that will be defined in this namespace's types.py —
+            # either as TypedDict classes (non-discriminated) or as Union aliases (discriminated bases).
+            # Only same-namespace non-json models are in the same types.py file.
+            same_namespace = relative_path == "."
+            will_be_in_types_file = self.base != "json" and same_namespace
+            if not will_be_in_types_file:
+                if same_namespace:
+                    # json models from same namespace — import from .models (or .models._models for internal)
+                    import_path = f".models.{self.code_model.models_filename}" if self.internal else ".models"
+                    file_import.add_submodule_import(
+                        import_path,
+                        self.name,
+                        ImportType.LOCAL,
+                        typing_section=TypingSection.TYPING,
+                    )
+                else:
+                    # Cross-namespace model — import from sibling namespace's types module
+                    file_import.add_submodule_import(
+                        self.code_model.get_relative_import_path(
+                            serialize_namespace, self.client_namespace, module_name="types"
+                        ),
+                        self.name,
+                        ImportType.LOCAL,
+                        typing_section=TypingSection.TYPING,
+                    )
+        elif serialize_namespace_type == NamespaceType.UNIONS_FILE or (
             serialize_namespace_type == NamespaceType.MODEL and called_by_property
         ):
             file_import.add_submodule_import(
@@ -352,6 +394,33 @@ class MsrestModelType(GeneratedModelType):
 class DPGModelType(GeneratedModelType):
     base = "dpg"
 
+    @property
+    def is_used_in_operations_via_types(self) -> bool:
+        return self.is_typed_dict_only
+
+    def type_annotation(self, **kwargs: Any) -> str:
+        if self.is_typed_dict_only:
+            is_operation_file = kwargs.pop("is_operation_file", False)
+            skip_quote = kwargs.get("skip_quote", False)
+            serialize_namespace_type = kwargs.get("serialize_namespace_type")
+            # Within types.py, use bare name (no module prefix)
+            if serialize_namespace_type == NamespaceType.TYPES_FILE:
+                retval = self.name
+            else:
+                serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
+                types_alias = self.code_model.get_unique_types_alias(serialize_namespace, self.client_namespace)
+                retval = f"{types_alias}.{self.name}"
+            return retval if is_operation_file or skip_quote else f'"{retval}"'
+        return super().type_annotation(**kwargs)
+
+    def docstring_type(self, **kwargs: Any) -> str:
+        if self.is_typed_dict_only:
+            client_namespace = self.client_namespace
+            if self.code_model.options.get("generation-subdir"):
+                client_namespace += f".{self.code_model.options['generation-subdir']}"
+            return f"~{client_namespace}.types.{self.name}"
+        return super().docstring_type(**kwargs)
+
     def serialization_type(self, **kwargs: Any) -> str:
         return (
             self.type_annotation(skip_quote=True, **kwargs)
@@ -364,7 +433,79 @@ class DPGModelType(GeneratedModelType):
         return "isinstance({}, " + f"_models.{self.name})"
 
     def imports(self, **kwargs: Any) -> FileImport:
+        if self.is_typed_dict_only:
+            file_import = FileImport(self.code_model)
+            serialize_namespace_type = kwargs.get("serialize_namespace_type")
+            serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
+            relative_path = self.code_model.get_relative_import_path(serialize_namespace, self.client_namespace)
+            alias = self.code_model.get_unique_types_alias(serialize_namespace, self.client_namespace)
+            same_namespace = relative_path == "."
+            if serialize_namespace_type in [NamespaceType.OPERATION, NamespaceType.CLIENT]:
+                file_import.add_submodule_import(
+                    relative_path,
+                    "types",
+                    ImportType.LOCAL,
+                    alias=alias,
+                )
+            elif serialize_namespace_type == NamespaceType.TYPES_FILE and same_namespace:
+                pass  # model is defined in this types.py — no import needed
+            elif serialize_namespace_type in [NamespaceType.TYPES_FILE, NamespaceType.UNIONS_FILE] or (
+                serialize_namespace_type == NamespaceType.MODEL and kwargs.get("called_by_property", False)
+            ):
+                file_import.add_submodule_import(
+                    relative_path,
+                    "types",
+                    ImportType.LOCAL,
+                    alias=alias,
+                    typing_section=TypingSection.TYPING,
+                )
+            return file_import
         file_import = super().imports(**kwargs)
         if self.flattened_property:
             file_import.add_submodule_import("typing", "Any", ImportType.STDLIB)
         return file_import
+
+
+class TypedDictModelType(DPGModelType):
+    base = "typeddict"
+
+    @property
+    def is_used_in_operations_via_types(self) -> bool:
+        return True
+
+    def type_annotation(self, **kwargs: Any) -> str:
+        is_operation_file = kwargs.pop("is_operation_file", False)
+        skip_quote = kwargs.get("skip_quote", False)
+        serialize_namespace_type = kwargs.get("serialize_namespace_type")
+        if serialize_namespace_type == NamespaceType.TYPES_FILE:
+            retval = self.name
+        else:
+            serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
+            types_alias = self.code_model.get_unique_types_alias(serialize_namespace, self.client_namespace)
+            retval = f"{types_alias}.{self.name}"
+        return retval if is_operation_file or skip_quote else f'"{retval}"'
+
+    def docstring_type(self, **kwargs: Any) -> str:
+        client_namespace = self.client_namespace
+        if self.code_model.options.get("generation-subdir"):
+            client_namespace += f".{self.code_model.options['generation-subdir']}"
+        return f"~{client_namespace}.types.{self.name}"
+
+    @property
+    def instance_check_template(self) -> str:
+        return "isinstance({}, MutableMapping)"
+
+    def imports(self, **kwargs: Any) -> FileImport:
+        file_import = FileImport(self.code_model)
+        serialize_namespace_type = kwargs.get("serialize_namespace_type")
+        serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
+        relative_path = self.code_model.get_relative_import_path(serialize_namespace, self.client_namespace)
+        alias = self.code_model.get_unique_types_alias(serialize_namespace, self.client_namespace)
+        if serialize_namespace_type in [NamespaceType.OPERATION, NamespaceType.CLIENT]:
+            file_import.add_submodule_import(
+                relative_path,
+                "types",
+                ImportType.LOCAL,
+                alias=alias,
+            )
+        return file_import

package/generator/pygen/codegen/models/operation.py

@@ -458,6 +458,7 @@ class OperationBase(  # pylint: disable=too-many-public-methods,too-many-instanc
                 r.type
                 and not isinstance(r.type, BinaryIteratorType)
                 and not xml_serializable(str(r.default_content_type))
+                and not (isinstance(r.type, ModelType) and r.type.is_typed_dict_only)
                 for r in self.responses
             ):
                 file_import.add_submodule_import(relative_path, "_deserialize", ImportType.LOCAL)

package/generator/pygen/codegen/models/paging_operation.py

@@ -186,7 +186,11 @@ class PagingOperationBase(OperationBase[PagingResponseType]):
                 serialize_namespace, module_name="_utils.model_base"
             )
             file_import.merge(self.item_type.imports(**kwargs))
-            if self.default_error_deserialization(serialize_namespace) or self.need_deserialize:
+            need_deserialize_import = self.default_error_deserialization(serialize_namespace) or (
+                self.need_deserialize
+                and not (isinstance(self.item_type, ModelType) and self.item_type.is_typed_dict_only)
+            )
+            if need_deserialize_import:
                 file_import.add_submodule_import(relative_path, "_deserialize", ImportType.LOCAL)
             if self.is_xml_paging:
                 file_import.add_submodule_import("xml.etree", "ElementTree", ImportType.STDLIB, alias="ET")

package/generator/pygen/codegen/models/parameter.py

@@ -180,7 +180,7 @@ class _ParameterBase(BaseModel, abc.ABC):  # pylint: disable=too-many-instance-a
         if isinstance(self.type, CombinedType) and self.type.name:
             file_import.add_submodule_import(
                 self.code_model.get_relative_import_path(serialize_namespace),
-                "_types",
+                "_unions",
                 ImportType.LOCAL,
                 TypingSection.TYPING,
             )
@@ -338,7 +338,7 @@ class Parameter(_ParameterBase):
     ) -> ParameterMethodLocation:
         if not self.in_method_signature:
             raise ValueError(f"Parameter '{self.client_name}' is not in the method.")
-        if self.code_model.options["models-mode"] == "dpg" and self.in_flattened_body:
+        if self.code_model.options["models-mode"] in ("dpg", "typeddict") and self.in_flattened_body:
             return ParameterMethodLocation.KEYWORD_ONLY
         if self.grouper:
             return ParameterMethodLocation.POSITIONAL

package/generator/pygen/codegen/models/primitive_types.py

@@ -9,6 +9,7 @@ from typing import Any, Optional, Union, TYPE_CHECKING
 
 from .base import BaseType
 from .imports import FileImport, ImportType, TypingSection
+from .utils import NamespaceType
 
 if TYPE_CHECKING:
     from .code_model import CodeModel
@@ -271,6 +272,8 @@ class DecimalType(NumberType):
         return "~" + self.type_annotation()
 
     def type_annotation(self, **kwargs: Any) -> str:
+        if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE:
+            return "float"
         return "decimal.Decimal"
 
     def docstring_text(self, **kwargs: Any) -> str:
@@ -281,7 +284,8 @@ class DecimalType(NumberType):
 
     def imports(self, **kwargs: Any) -> FileImport:
         file_import = FileImport(self.code_model)
-        file_import.add_import("decimal", ImportType.STDLIB)
+        if kwargs.get("serialize_namespace_type") != NamespaceType.TYPES_FILE:
+            file_import.add_import("decimal", ImportType.STDLIB)
         return file_import
 
     @property
@@ -357,6 +361,8 @@ class DatetimeType(PrimitiveType):
         return "~" + self.type_annotation()
 
     def type_annotation(self, **kwargs: Any) -> str:
+        if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE:
+            return "str"
         return "datetime.datetime"
 
     def docstring_text(self, **kwargs: Any) -> str:
@@ -370,7 +376,8 @@ class DatetimeType(PrimitiveType):
 
     def imports(self, **kwargs: Any) -> FileImport:
         file_import = FileImport(self.code_model)
-        file_import.add_import("datetime", ImportType.STDLIB)
+        if kwargs.get("serialize_namespace_type") != NamespaceType.TYPES_FILE:
+            file_import.add_import("datetime", ImportType.STDLIB)
         return file_import
 
     @property
@@ -399,6 +406,8 @@ class TimeType(PrimitiveType):
         return "~" + self.type_annotation()
 
     def type_annotation(self, **kwargs: Any) -> str:
+        if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE:
+            return "str"
         return "datetime.time"
 
     def docstring_text(self, **kwargs: Any) -> str:
@@ -412,7 +421,8 @@ class TimeType(PrimitiveType):
 
     def imports(self, **kwargs: Any) -> FileImport:
         file_import = FileImport(self.code_model)
-        file_import.add_import("datetime", ImportType.STDLIB)
+        if kwargs.get("serialize_namespace_type") != NamespaceType.TYPES_FILE:
+            file_import.add_import("datetime", ImportType.STDLIB)
         return file_import
 
     @property
@@ -445,6 +455,8 @@ class UnixTimeType(PrimitiveType):
         return "~" + self.type_annotation()
 
     def type_annotation(self, **kwargs: Any) -> str:
+        if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE:
+            return "int"
         return "datetime.datetime"
 
     def docstring_text(self, **kwargs: Any) -> str:
@@ -458,7 +470,8 @@ class UnixTimeType(PrimitiveType):
 
     def imports(self, **kwargs: Any) -> FileImport:
         file_import = FileImport(self.code_model)
-        file_import.add_import("datetime", ImportType.STDLIB)
+        if kwargs.get("serialize_namespace_type") != NamespaceType.TYPES_FILE:
+            file_import.add_import("datetime", ImportType.STDLIB)
         return file_import
 
     @property
@@ -487,6 +500,8 @@ class DateType(PrimitiveType):
         return "~" + self.type_annotation()
 
     def type_annotation(self, **kwargs: Any) -> str:
+        if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE:
+            return "str"
         return "datetime.date"
 
     def docstring_text(self, **kwargs: Any) -> str:
@@ -500,7 +515,8 @@ class DateType(PrimitiveType):
 
     def imports(self, **kwargs: Any) -> FileImport:
         file_import = FileImport(self.code_model)
-        file_import.add_import("datetime", ImportType.STDLIB)
+        if kwargs.get("serialize_namespace_type") != NamespaceType.TYPES_FILE:
+            file_import.add_import("datetime", ImportType.STDLIB)
         return file_import
 
     @property
@@ -543,6 +559,8 @@ class DurationType(PrimitiveType):
         return "~" + self.type_annotation()
 
     def type_annotation(self, **kwargs: Any) -> str:
+        if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE:
+            return "str"
         return "datetime.timedelta"
 
     def docstring_text(self, **kwargs: Any) -> str:
@@ -556,7 +574,8 @@ class DurationType(PrimitiveType):
 
     def imports(self, **kwargs: Any) -> FileImport:
         file_import = FileImport(self.code_model)
-        file_import.add_import("datetime", ImportType.STDLIB)
+        if kwargs.get("serialize_namespace_type") != NamespaceType.TYPES_FILE:
+            file_import.add_import("datetime", ImportType.STDLIB)
         return file_import
 
     @property
@@ -590,6 +609,11 @@ class ByteArraySchema(PrimitiveType):
     def docstring_type(self, **kwargs: Any) -> str:
         return "bytes"
 
+    def type_annotation(self, **kwargs: Any) -> str:
+        if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE:
+            return "str"
+        return "bytes"
+
     def get_declaration(self, value: str) -> str:
         return f'bytes("{value}", encoding="utf-8")'
 

package/generator/pygen/codegen/models/property.py

@@ -10,7 +10,7 @@ from .constant_type import ConstantType
 from .enum_type import EnumType
 from .base import BaseType
 from .imports import FileImport, ImportType
-from .utils import add_to_description, add_to_pylint_disable
+from .utils import add_to_description, add_to_pylint_disable, NamespaceType
 
 if TYPE_CHECKING:
     from .code_model import CodeModel
@@ -29,6 +29,7 @@ class Property(BaseModel):  # pylint: disable=too-many-instance-attributes
         self.client_name: str = self.yaml_data["clientName"]
         self.type = type
         self.optional: bool = self.yaml_data["optional"]
+        self.nullable: bool = self.yaml_data.get("nullable", False)
         self.readonly: bool = self.yaml_data.get("readonly", False)
         self.visibility: list[str] = self.yaml_data.get("visibility", [])
         self.is_polymorphic: bool = self.yaml_data.get("isPolymorphic", False)
@@ -110,6 +111,12 @@ class Property(BaseModel):  # pylint: disable=too-many-instance-attributes
         if self.is_base_discriminator:
             return "str"
         types_type_annotation = self.type.type_annotation(is_operation_file=is_operation_file, **kwargs)
+        serialize_namespace_type = kwargs.get("serialize_namespace_type")
+        # In TypedDict types.py, Optional means nullable (not "not required" — that's handled by Required/total=False)
+        if serialize_namespace_type == NamespaceType.TYPES_FILE:
+            if self.nullable:
+                return f"Optional[{types_type_annotation}]"
+            return types_type_annotation
         if (self.optional and self.client_default_value is None) or self.readonly:
             return f"Optional[{types_type_annotation}]"
         return types_type_annotation
@@ -152,15 +159,21 @@ class Property(BaseModel):  # pylint: disable=too-many-instance-attributes
         if self.is_discriminator and isinstance(self.type, EnumType):
             return file_import
         file_import.merge(self.type.imports(**kwargs))
-        if (self.optional and self.client_default_value is None) or self.readonly:
+        serialize_namespace_type = kwargs.get("serialize_namespace_type")
+        if serialize_namespace_type == NamespaceType.TYPES_FILE:
+            # In TypedDict types.py, Optional means nullable
+            if self.nullable:
+                file_import.add_submodule_import("typing", "Optional", ImportType.STDLIB)
+        elif (self.optional and self.client_default_value is None) or self.readonly:
             file_import.add_submodule_import("typing", "Optional", ImportType.STDLIB)
         if self.code_model.options["models-mode"] == "dpg":
-            serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
-            file_import.add_submodule_import(
-                self.code_model.get_relative_import_path(serialize_namespace, module_name="_utils.model_base"),
-                "rest_discriminator" if self.is_discriminator else "rest_field",
-                ImportType.LOCAL,
-            )
+            if serialize_namespace_type != NamespaceType.TYPES_FILE:
+                serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
+                file_import.add_submodule_import(
+                    self.code_model.get_relative_import_path(serialize_namespace, module_name="_utils.model_base"),
+                    "rest_discriminator" if self.is_discriminator else "rest_field",
+                    ImportType.LOCAL,
+                )
         return file_import
 
     @classmethod

package/generator/pygen/codegen/models/response.py

@@ -68,7 +68,12 @@ class Response(BaseModel):
 
     def get_polymorphic_subtypes(self, polymorphic_subtypes: list["ModelType"]) -> None:
         if self.type:
-            self.type.get_polymorphic_subtypes(polymorphic_subtypes)
+            if isinstance(self.type, CombinedType):
+                target = self.type.target_model_subtype((ModelType,))
+                if target:
+                    target.get_polymorphic_subtypes(polymorphic_subtypes)
+            else:
+                self.type.get_polymorphic_subtypes(polymorphic_subtypes)
 
     def get_json_template_representation(self) -> Any:
         if not self.type:
@@ -95,6 +100,7 @@ class Response(BaseModel):
     def type_annotation(self, **kwargs: Any) -> str:
         if self.type:
             kwargs["is_operation_file"] = True
+            kwargs["is_response"] = True
             type_annotation = self.type.type_annotation(**kwargs)
             if self.nullable:
                 return f"Optional[{type_annotation}]"
@@ -102,11 +108,13 @@ class Response(BaseModel):
         return "None"
 
     def docstring_text(self, **kwargs: Any) -> str:
+        kwargs["is_response"] = True
         if self.nullable and self.type:
             return f"{self.type.docstring_text(**kwargs)} or None"
         return self.type.docstring_text(**kwargs) if self.type else "None"
 
     def docstring_type(self, **kwargs: Any) -> str:
+        kwargs["is_response"] = True
         if self.nullable and self.type:
             return f"{self.type.docstring_type(**kwargs)} or None"
         return self.type.docstring_type(**kwargs) if self.type else "None"
@@ -121,7 +129,7 @@ class Response(BaseModel):
             serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
             file_import.add_submodule_import(
                 self.code_model.get_relative_import_path(serialize_namespace),
-                "_types",
+                "_unions",
                 ImportType.LOCAL,
                 TypingSection.TYPING,
             )
@@ -165,7 +173,12 @@ class PagingResponse(Response):
         )
 
     def get_polymorphic_subtypes(self, polymorphic_subtypes: list["ModelType"]) -> None:
-        return self.item_type.get_polymorphic_subtypes(polymorphic_subtypes)
+        if isinstance(self.item_type, CombinedType):
+            target = self.item_type.target_model_subtype((ModelType,))
+            if target:
+                target.get_polymorphic_subtypes(polymorphic_subtypes)
+        else:
+            self.item_type.get_polymorphic_subtypes(polymorphic_subtypes)
 
     def get_json_template_representation(self) -> Any:
         return self.item_type.get_json_template_representation()

package/generator/pygen/codegen/models/utils.py

@@ -7,23 +7,24 @@ from typing import TypeVar
 
 from enum import Enum
 
+from ...utils import description_ends_with_code_block
+
 T = TypeVar("T")
 OrderedSet = dict[T, None]
 
 
-CODE_BLOCK_MARKER = ".. code-block::"
-
-
 def add_to_description(description: str, entry: str) -> str:
     if not description:
         return entry
-    # When the description contains a code block, the entry (e.g. "Required.") must be
-    # inserted into the prose *before* the code block. Appending it after the code block
-    # (e.g. "]. Required.") leaves it dangling at the end of the rendered block and breaks
-    # Sphinx rendering.
-    if CODE_BLOCK_MARKER in description:
-        prose, _, code_block = description.partition(CODE_BLOCK_MARKER)
-        return f"{prose.rstrip()} {entry}\n\n{CODE_BLOCK_MARKER}{code_block}"
+    if not entry:
+        return description
+    # When the description ends with a code block, prepend the entry (e.g. "Required.") so
+    # it appears before the prose instead of after the block. Appending inline (e.g.
+    # "]. Required.") would land it inside the rendered literal block and break Sphinx, and a
+    # trailing paragraph reads awkwardly. The code block stays at the very end where it renders
+    # cleanly. (Code-block descriptions only ever carry a single annotation in practice.)
+    if description_ends_with_code_block(description):
+        return f"{entry} {description.lstrip()}"
     return f"{description} {entry}"
 
 
@@ -40,6 +41,7 @@ class NamespaceType(str, Enum):
     OPERATION = "operation"
     CLIENT = "client"
     TYPES_FILE = "types_file"
+    UNIONS_FILE = "unions_file"
 
 
 LOCALS_LENGTH_LIMIT = 25

package/generator/pygen/codegen/serializers/__init__.py

@@ -33,6 +33,7 @@ from .patch_serializer import PatchSerializer
 from .sample_serializer import SampleSerializer
 from .test_serializer import TestSerializer, TestGeneralSerializer
 from .types_serializer import TypesSerializer
+from .unions_serializer import UnionsSerializer
 from ...utils import to_snake_case, VALID_PACKAGE_MODE
 from .utils import extract_sample_name, get_namespace_from_package_name, get_namespace_config, hash_file_import
 
@@ -120,7 +121,7 @@ class JinjaSerializer(ReaderAndWriter):
             # If parsing the version fails, we assume the version file is not valid and overwrite.
             return False
 
-    # pylint: disable=too-many-branches
+    # pylint: disable=too-many-branches,too-many-statements
     def serialize(self) -> None:
         # remove existing folders when generate from tsp
         if self.code_model.is_tsp and self.code_model.options.get("clear-output-folder"):
@@ -200,12 +201,13 @@ class JinjaSerializer(ReaderAndWriter):
                     general_serializer.serialize_pkgutil_init_file(),
                 )
 
-            # _utils/py.typed/_types.py/_validation.py
+            # _utils/py.typed/_unions.py/types.py/_validation.py
             # is always put in top level namespace
             if self.code_model.is_top_namespace(client_namespace):
                 self._serialize_and_write_top_level_folder(env=env, namespace=client_namespace)
 
             # add models folder if there are models in this namespace
+            is_typeddict_mode = self.code_model.options["models-mode"] == "typeddict"
             if (
                 self.code_model.has_non_json_models(client_namespace_type.models) or client_namespace_type.enums
             ) and self.code_model.options["models-mode"]:
@@ -213,7 +215,27 @@ class JinjaSerializer(ReaderAndWriter):
                     env=env,
                     namespace=client_namespace,
                     models=client_namespace_type.models,
-                    enums=client_namespace_type.enums,
+                    enums=[] if is_typeddict_mode else client_namespace_type.enums,
+                )
+
+            # write types.py per namespace (alongside models/)
+            # Only generate types.py if at least one model/enum would be imported via types
+            # in operations (the model itself volunteers this via is_used_in_operations_via_types)
+            has_types_models = any(
+                m.is_used_in_operations_via_types for m in client_namespace_type.models if m.base != "json"
+            )
+            has_types_enums = any(e.is_typeddict_mode for e in client_namespace_type.enums)
+            if has_types_models or has_types_enums:
+                generation_dir = self.code_model.get_generation_dir(client_namespace)
+                self.write_file(
+                    generation_dir / Path("types.py"),
+                    TypesSerializer(
+                        code_model=self.code_model,
+                        env=env,
+                        client_namespace=client_namespace,
+                        models=client_namespace_type.models,
+                        enums=client_namespace_type.enums if is_typeddict_mode else None,
+                    ).serialize(),
                 )
 
             if not self.code_model.options["models-mode"]:
@@ -298,11 +320,19 @@ class JinjaSerializer(ReaderAndWriter):
     ) -> None:
         # Write the models folder
         models_path = self.code_model.get_generation_dir(namespace) / "models"
-        serializer = DpgModelSerializer if self.code_model.options["models-mode"] == "dpg" else MsrestModelSerializer
-        if self.code_model.has_non_json_models(models):
+        models_mode = self.code_model.options["models-mode"]
+        if models_mode in ("dpg", "typeddict"):
+            serializer = DpgModelSerializer
+        else:
+            serializer = MsrestModelSerializer
+        # Filter out typed-dict-only models and typeddict copies — they only appear in types.py, not as model classes
+        class_models = [m for m in models if not m.is_typed_dict_only and m.base != "typeddict"]
+        if self.code_model.has_non_json_models(class_models):
             self.write_file(
                 models_path / Path(f"{self.code_model.models_filename}.py"),
-                serializer(code_model=self.code_model, env=env, client_namespace=namespace, models=models).serialize(),
+                serializer(
+                    code_model=self.code_model, env=env, client_namespace=namespace, models=class_models
+                ).serialize(),
             )
         if enums:
             self.write_file(
@@ -313,7 +343,7 @@ class JinjaSerializer(ReaderAndWriter):
             )
         self.write_file(
             models_path / Path("__init__.py"),
-            ModelInitSerializer(code_model=self.code_model, env=env, models=models, enums=enums).serialize(),
+            ModelInitSerializer(code_model=self.code_model, env=env, models=class_models, enums=enums).serialize(),
         )
 
         self._keep_patch_file(models_path / Path("_patch.py"), env)
@@ -442,7 +472,9 @@ class JinjaSerializer(ReaderAndWriter):
             # when there is client.py, there must be __init__.py
             self.write_file(
                 generation_path / Path(f"{async_path}__init__.py"),
-                general_serializer.serialize_init_file([c for c in clients if c.has_operations]),
+                general_serializer.serialize_init_file(
+                    [c for c in clients if c.has_operations],
+                ),
             )
 
             # if there was a patch file before, we keep it
@@ -519,11 +551,14 @@ class JinjaSerializer(ReaderAndWriter):
                 general_serializer.serialize_validation_file(),
             )
 
-        # write _types.py
+        # write _unions.py
         if self.code_model.named_unions:
             self.write_file(
-                generation_dir / Path("_types.py"),
-                TypesSerializer(code_model=self.code_model, env=env).serialize(),
+                generation_dir / Path("_unions.py"),
+                UnionsSerializer(
+                    code_model=self.code_model,
+                    env=env,
+                ).serialize(),
             )
 
     # pylint: disable=line-too-long