[python] add typeddict models-mode for Python HTTP client emitter

.chronus/changes/fix-typeddict-single-overload-2026-6-26-12-56-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/http-client-python"
+---
+
+Fix invalid lone `@overload` generated for body parameters in `models-mode: typeddict`. When the binary and JSON overloads are omitted, the single remaining body variant is now emitted as a plain parameter instead of a single `@overload`, which mypy rejects with "Single overload definition, multiple required".

.chronus/changes/python-addTypedDict-2026-3-21-17-47-3.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/http-client-python"
+---
+
+[python] Always generate `TypedDict` typing hints for input models in the `types.py` file, and named union aliases in the `_unions.py` file

cspell.yaml

@@ -43,6 +43,7 @@ words:
   - canonicalizer
   - Cblack
   - Cbrown
+  - clid
   - clsx
   - cobertura
   - codehaus

packages/http-client-python/emitter/src/types.ts

@@ -233,6 +233,7 @@ function emitProperty(
     // Python convert all the type of file part to FileType so clear these models' usage so that they won't be generated
     addDisableGenerationMap(context, property.type);
   }
+  const isNullable = !isMultipartFileInput && sourceType.kind === "nullable";
   return {
     clientName: getClientName(property),
     isExactName: property.isExactName,
@@ -242,6 +243,7 @@ function emitProperty(
         : property.serializationOptions?.json?.name) ?? property.name,
     type: getType(context, sourceType),
     optional: property.optional,
+    nullable: isNullable,
     description: property.summary ? property.summary : property.doc,
     addedOn: getAddedOn(context, property),
     apiVersions: property.apiVersions,

packages/http-client-python/eng/scripts/ci/regenerate-common.ts

@@ -172,9 +172,15 @@ export const AZURE_EMITTER_OPTIONS: Record<
     "package-name": "client-structure-twooperationgroup",
     namespace: "client.structure.twooperationgroup",
   },
-  "client/naming": {
-    namespace: "client.naming.main",
-  },
+  "client/naming": [
+    {
+      namespace: "client.naming.main",
+    },
+    {
+      "package-name": "client-naming-typeddict",
+      namespace: "client.naming.typeddict",
+    },
+  ],
   "client/overload": {
     namespace: "client.overload",
   },
@@ -271,14 +277,26 @@ export const EMITTER_OPTIONS: Record<string, Record<string, string> | Record<str
     "package-name": "typetest-model-nesteddiscriminator",
     namespace: "typetest.model.nesteddiscriminator",
   },
-  "type/model/inheritance/not-discriminated": {
-    "package-name": "typetest-model-notdiscriminated",
-    namespace: "typetest.model.notdiscriminated",
-  },
-  "type/model/inheritance/single-discriminator": {
-    "package-name": "typetest-model-singlediscriminator",
-    namespace: "typetest.model.singlediscriminator",
-  },
+  "type/model/inheritance/not-discriminated": [
+    {
+      "package-name": "typetest-model-notdiscriminated",
+      namespace: "typetest.model.notdiscriminated",
+    },
+    {
+      "package-name": "typetest-model-notdiscriminated-typeddict",
+      namespace: "typetest.model.notdiscriminated.typeddict",
+    },
+  ],
+  "type/model/inheritance/single-discriminator": [
+    {
+      "package-name": "typetest-model-singlediscriminator",
+      namespace: "typetest.model.singlediscriminator",
+    },
+    {
+      "package-name": "typetest-model-singlediscriminator-typeddict",
+      namespace: "typetest.model.singlediscriminator.typeddict",
+    },
+  ],
   "type/model/inheritance/recursive": [
     {
       "package-name": "typetest-model-recursive",
@@ -292,10 +310,17 @@ export const EMITTER_OPTIONS: Record<string, Record<string, string> | Record<str
       "clear-output-folder": "true",
     },
   ],
-  "type/model/usage": {
-    "package-name": "typetest-model-usage",
-    namespace: "typetest.model.usage",
-  },
+  "type/model/usage": [
+    {
+      "package-name": "typetest-model-usage",
+      namespace: "typetest.model.usage",
+    },
+    {
+      "package-name": "typetest-model-usage-typeddictonly",
+      namespace: "typetest.model.usage.typeddictonly",
+      "models-mode": "typeddict",
+    },
+  ],
   "type/model/visibility": [
     {
       "package-name": "typetest-model-visibility",

packages/http-client-python/generator/pygen/__init__.py

@@ -168,10 +168,10 @@ def _validate_and_transform(self, key: str, value: Any) -> Any:
         if key == "models-mode" and value == "none":
             value = False  # switch to falsy value for easier code writing
 
-        if key == "models-mode" and value not in ["msrest", "dpg", False]:
+        if key == "models-mode" and value not in ["msrest", "dpg", "typeddict", False]:
             raise ValueError(
-                "--models-mode can only be 'msrest', 'dpg' or 'none'. "
-                "Pass in 'msrest' if you want msrest models, or "
+                "--models-mode can only be 'msrest', 'dpg', 'typeddict', or 'none'. "
+                "Pass in 'msrest' if you want msrest models, 'typeddict' for TypedDict models, or "
                 "'none' if you don't want any."
             )
         if key == "package-mode":

packages/http-client-python/generator/pygen/codegen/models/__init__.py

@@ -9,7 +9,7 @@
 from .base_builder import BaseBuilder, ParameterListType
 from .code_model import CodeModel
 from .client import Client
-from .model_type import ModelType, JSONModelType, DPGModelType, MsrestModelType
+from .model_type import ModelType, JSONModelType, DPGModelType, MsrestModelType, TypedDictModelType
 from .dictionary_type import DictionaryType
 from .list_type import ListType
 from .combined_type import CombinedType
@@ -167,7 +167,9 @@ def build_type(yaml_data: dict[str, Any], code_model: CodeModel) -> BaseType:
     response: Optional[BaseType] = None
     if yaml_data["type"] == "model":
         # need to special case model to avoid recursion
-        if yaml_data["base"] == "json" or not code_model.options["models-mode"]:
+        if yaml_data["base"] == "typeddict":
+            model_type = TypedDictModelType  # type: ignore
+        elif yaml_data["base"] == "json" or not code_model.options["models-mode"]:
             model_type = JSONModelType
         elif yaml_data["base"] == "dpg":
             model_type = DPGModelType  # type: ignore

packages/http-client-python/generator/pygen/codegen/models/code_model.py

@@ -152,16 +152,28 @@ def get_relative_import_path(
             return result
         return f"{result}{module_name}" if result.endswith(".") else f"{result}.{module_name}"
 
-    def get_unique_models_alias(self, serialize_namespace: str, imported_namespace: str) -> str:
+    def _get_unique_import_alias(self, serialize_namespace: str, imported_namespace: str, module_name: str) -> str:
         if not self.has_subnamespace:
-            return "_models"
+            return f"_{module_name}"
         relative_path = self.get_relative_import_path(
             serialize_namespace, self.get_imported_namespace_for_model(imported_namespace)
         )
         dot_num = max(relative_path.count(".") - 1, 0)
-        parts = [""] + ([p for p in relative_path.split(".") if p] or ["models"])
+        path_parts = [p for p in relative_path.split(".") if p]
+        # For "models", keep existing format: _<path_parts><dot_num> (e.g. _models1, _firstnamespace_models2)
+        # For other modules like "types", prefix with module name: _types_<path_parts><dot_num>
+        if module_name == "models":
+            parts = [""] + (path_parts or [module_name])
+        else:
+            parts = [f"_{module_name}"] + (path_parts or [])
         return "_".join(parts) + (str(dot_num) if dot_num > 0 else "")
 
+    def get_unique_models_alias(self, serialize_namespace: str, imported_namespace: str) -> str:
+        return self._get_unique_import_alias(serialize_namespace, imported_namespace, "models")
+
+    def get_unique_types_alias(self, serialize_namespace: str, imported_namespace: str) -> str:
+        return self._get_unique_import_alias(serialize_namespace, imported_namespace, "types")
+
     @property
     def client_namespace_types(self) -> dict[str, ClientNamespaceType]:
         if not self._client_namespace_types:
@@ -174,6 +186,14 @@ def client_namespace_types(self) -> dict[str, ClientNamespaceType]:
                 if model.client_namespace not in self._client_namespace_types:
                     self._client_namespace_types[model.client_namespace] = ClientNamespaceType()
                 self._client_namespace_types[model.client_namespace].models.append(model)
+            # TypedDict copies (base="typeddict") are excluded from model_types to keep
+            # them out of _models.py, but they need to be in the namespace model list
+            # so the TypesSerializer can render them in types.py.
+            for t in self.types_map.values():
+                if isinstance(t, ModelType) and t.base == "typeddict" and t.usage != UsageFlags.Default.value:
+                    if t.client_namespace not in self._client_namespace_types:
+                        self._client_namespace_types[t.client_namespace] = ClientNamespaceType()
+                    self._client_namespace_types[t.client_namespace].models.append(t)
             for enum in self.enums:
                 if enum.client_namespace not in self._client_namespace_types:
                     self._client_namespace_types[enum.client_namespace] = ClientNamespaceType()
@@ -339,7 +359,9 @@ def model_types(self) -> list[ModelType]:
         """All of the model types in this class"""
         if not self._model_types:
             self._model_types = [
-                t for t in self.types_map.values() if isinstance(t, ModelType) and t.usage != UsageFlags.Default.value
+                t
+                for t in self.types_map.values()
+                if isinstance(t, ModelType) and t.usage != UsageFlags.Default.value and t.base != "typeddict"
             ]
         return self._model_types
 
@@ -349,7 +371,7 @@ def model_types(self, val: list[ModelType]) -> None:
 
     @staticmethod
     def get_public_model_types(models: list[ModelType]) -> list[ModelType]:
-        return [m for m in models if not m.internal and not m.base == "json"]
+        return [m for m in models if not m.internal and not m.base == "json" and not m.is_typed_dict_only]
 
     @property
     def public_model_types(self) -> list[ModelType]:

packages/http-client-python/generator/pygen/codegen/models/combined_type.py

@@ -66,7 +66,7 @@ def docstring_type(self, **kwargs: Any) -> str:
 
     def type_annotation(self, **kwargs: Any) -> str:
         if self.name:
-            return f'"_types.{self.name}"'
+            return f'"_unions.{self.name}"'
         return self.type_definition(**kwargs)
 
     def type_definition(self, **kwargs: Any) -> str:
@@ -116,10 +116,10 @@ def imports(self, **kwargs: Any) -> FileImport:
         file_import = FileImport(self.code_model)
         serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
         serialize_namespace_type = kwargs.get("serialize_namespace_type")
-        if self.name and serialize_namespace_type != NamespaceType.TYPES_FILE:
+        if self.name and serialize_namespace_type != NamespaceType.UNIONS_FILE:
             file_import.add_submodule_import(
                 self.code_model.get_relative_import_path(serialize_namespace),
-                "_types",
+                "_unions",
                 ImportType.LOCAL,
                 TypingSection.TYPING,
             )

packages/http-client-python/generator/pygen/codegen/models/enum_type.py

@@ -167,16 +167,31 @@ def description(self, *, is_operation_file: bool) -> str:
         enum_description = f"Known values are: {possible_values_str}."
         return enum_description
 
+    @property
+    def is_typeddict_mode(self) -> bool:
+        return self.code_model.options["models-mode"] == "typeddict"
+
     def type_annotation(self, **kwargs: Any) -> str:
         """The python type used for type annotation
 
         :return: The type annotation for this schema
         :rtype: str
         """
         if self.code_model.options["models-mode"]:
+            if self.is_typeddict_mode:
+                # In typeddict mode, enums are Literal aliases defined in types.py
+                serialize_namespace_type = kwargs.get("serialize_namespace_type")
+                if serialize_namespace_type == NamespaceType.TYPES_FILE:
+                    # Same file — just the name, no module prefix
+                    return self.name
+                # From operation/client files, use types.EnumName (matching model pattern)
+                return f"types.{self.name}"
 
             module_name = ""
-            if kwargs.get("need_model_alias", True):
+            serialize_namespace_type = kwargs.get("serialize_namespace_type")
+            if serialize_namespace_type == NamespaceType.TYPES_FILE:
+                pass  # no module prefix for types.py
+            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}."
@@ -240,31 +255,66 @@ def imports(self, **kwargs: Any) -> FileImport:
         file_import = FileImport(self.code_model)
         file_import.merge(self.value_type.imports(**kwargs))
         if self.code_model.options["models-mode"]:
-            file_import.add_submodule_import("typing", "Union", ImportType.STDLIB, TypingSection.REGULAR)
+            if self.is_typeddict_mode:
+                # In typeddict mode, enums are Literal aliases in types.py — no Union needed
+                serialize_namespace_type = kwargs.get("serialize_namespace_type")
+                if serialize_namespace_type == NamespaceType.TYPES_FILE:
+                    # Same file — no import needed for same-namespace enums
+                    serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
+                    if self.client_namespace != serialize_namespace:
+                        # Cross-namespace: import from sibling types module
+                        relative_path = self.code_model.get_relative_import_path(
+                            serialize_namespace, self.client_namespace
+                        )
+                        file_import.add_submodule_import(
+                            f"{relative_path}types" if relative_path != "." else ".types",
+                            self.name,
+                            ImportType.LOCAL,
+                            typing_section=TypingSection.REGULAR,
+                        )
+                elif serialize_namespace_type in [NamespaceType.OPERATION, NamespaceType.CLIENT]:
+                    # Import types module directly (matching model pattern)
+                    serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
+                    relative_path = self.code_model.get_relative_import_path(serialize_namespace, self.client_namespace)
+                    file_import.add_submodule_import(
+                        relative_path,
+                        "types",
+                        ImportType.LOCAL,
+                    )
+            else:
+                file_import.add_submodule_import("typing", "Union", ImportType.STDLIB, TypingSection.REGULAR)
 
-            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_models_alias(serialize_namespace, self.client_namespace)
-            serialize_namespace_type = kwargs.get("serialize_namespace_type")
-            called_by_property = kwargs.get("called_by_property", False)
-            if serialize_namespace_type in [NamespaceType.OPERATION, NamespaceType.CLIENT]:
-                file_import.add_submodule_import(
-                    relative_path,
-                    "models",
-                    ImportType.LOCAL,
-                    alias=alias,
-                    typing_section=TypingSection.REGULAR,
-                )
-            elif serialize_namespace_type == NamespaceType.TYPES_FILE or (
-                serialize_namespace_type == NamespaceType.MODEL and called_by_property
-            ):
-                file_import.add_submodule_import(
-                    relative_path,
-                    "models",
-                    ImportType.LOCAL,
-                    alias=alias,
-                    typing_section=TypingSection.TYPING,
-                )
+                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_models_alias(serialize_namespace, self.client_namespace)
+                serialize_namespace_type = kwargs.get("serialize_namespace_type")
+                called_by_property = kwargs.get("called_by_property", False)
+                if serialize_namespace_type in [NamespaceType.OPERATION, NamespaceType.CLIENT]:
+                    file_import.add_submodule_import(
+                        relative_path,
+                        "models",
+                        ImportType.LOCAL,
+                        alias=alias,
+                        typing_section=TypingSection.REGULAR,
+                    )
+                elif serialize_namespace_type == NamespaceType.TYPES_FILE:
+                    # Import enum name directly to avoid dotted forward refs in TypedDict annotations
+                    file_import.add_submodule_import(
+                        f"{relative_path}models" if relative_path != "." else ".models",
+                        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(
+                        relative_path,
+                        "models",
+                        ImportType.LOCAL,
+                        alias=alias,
+                        typing_section=TypingSection.TYPING,
+                    )
 
         file_import.merge(self.value_type.imports(**kwargs))
         return file_import

packages/http-client-python/generator/pygen/codegen/models/list_type.py

@@ -6,6 +6,7 @@
 from typing import Any, Optional, Union, TYPE_CHECKING
 from .base import BaseType
 from .imports import FileImport
+from .utils import NamespaceType
 
 if TYPE_CHECKING:
     from .code_model import CodeModel
@@ -41,12 +42,17 @@ def type_annotation(self, **kwargs: Any) -> str:
             # this means we're version tolerant XML, we just return the XML element
             return self.element_type.type_annotation(**kwargs)
 
-        # if there is a function/property named `list` we have to make sure there's no conflict with the built-in `list`
+        # if there is a function named `list` we have to make sure there's no conflict with the built-in `list`
+        # in operation files. The operation_groups_serializer defines `List = list` alias for this case.
+        serialize_namespace_type = kwargs.get("serialize_namespace_type")
         is_operation_file = kwargs.get("is_operation_file", False)
-        use_list_import = (self.code_model.has_operation_named_list and is_operation_file) or (
-            self.code_model.has_property_named_list and not is_operation_file
+        in_operation_context = (
+            serialize_namespace_type in (NamespaceType.OPERATION, NamespaceType.CLIENT) or is_operation_file
         )
-        list_type = "List" if use_list_import else "list"
+        if in_operation_context and self.code_model.has_operation_named_list:
+            list_type = "List"
+        else:
+            list_type = "list"
         return f"{list_type}[{self.element_type.type_annotation(**kwargs)}]"
 
     def description(self, *, is_operation_file: bool) -> str: