@typespec/http-client-python 0.33.0 → 0.34.0

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

@@ -41,14 +41,11 @@ class NamespaceType(str, Enum):
     OPERATION = "operation"
     CLIENT = "client"
     TYPES_FILE = "types_file"
+    UNIONS_FILE = "unions_file"
 
 
 LOCALS_LENGTH_LIMIT = 25
 
-REQUEST_BUILDER_BODY_VARIABLES_LENGTH = (
-    6  # how many body variables are present in a request builder
-)
+REQUEST_BUILDER_BODY_VARIABLES_LENGTH = 6  # how many body variables are present in a request builder
 
-OPERATION_BODY_VARIABLES_LENGTH = (
-    14  # how many body variables are present in an operation
-)
+OPERATION_BODY_VARIABLES_LENGTH = 14  # how many body variables are present in an operation

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

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

@@ -196,6 +196,16 @@ def is_json_model_type(parameters: ParameterListType) -> bool:
     )
 
 
+def _is_dpg_or_typeddict_body(body_param: BodyParameter) -> bool:
+    """Check if a body parameter is a DPG model or a CombinedType wrapping one."""
+    body_type = body_param.type
+    if isinstance(body_type, DPGModelType):
+        return True
+    if isinstance(body_type, CombinedType):
+        return body_type.target_model_subtype((DPGModelType,)) is not None
+    return False
+
+
 class _BuilderBaseSerializer(Generic[BuilderType]):
     def __init__(self, code_model: CodeModel, async_mode: bool, client_namespace: str) -> None:
         self.code_model = code_model
@@ -712,8 +722,20 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
                 f"_{body_kwarg_name} = self._serialize.body({body_param.client_name}, "
                 f"'{serialization_type}'{is_xml_cmd}{serialization_ctxt_cmd})"
             )
+        elif self.code_model.options["models-mode"] == "typeddict":
+            # TypedDict-only models are plain dicts — no serialization needed
+            create_body_call = f"_{body_kwarg_name} = {body_param.client_name}"
         elif self.code_model.options["models-mode"] == "dpg":
-            if json_serializable(body_param.default_content_type):
+            # Check if this is a typeddict-only model within dpg mode — skip serialization
+            body_model_type = body_param.type
+            if isinstance(body_model_type, CombinedType):
+                body_model_type = body_model_type.target_model_subtype((DPGModelType,))
+            is_typeddict_only_body = isinstance(body_model_type, DPGModelType) and getattr(
+                body_model_type, "is_typed_dict_only", False
+            )
+            if is_typeddict_only_body:
+                create_body_call = f"_{body_kwarg_name} = {body_param.client_name}"
+            elif json_serializable(body_param.default_content_type):
                 if hasattr(body_param.type, "encode") and body_param.type.encode:  # type: ignore
                     create_body_call = (
                         f"_{body_kwarg_name} = json.dumps({body_param.client_name}, "
@@ -791,9 +813,9 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
             overload.request_builder.parameters.body_parameter.client_name for overload in builder.overloads
         ]
         all_dpg_model_overloads = False
-        if self.code_model.options["models-mode"] == "dpg" and builder.overloads:
+        if self.code_model.options["models-mode"] in ("dpg", "typeddict") and builder.overloads:
             all_dpg_model_overloads = all(
-                isinstance(o.parameters.body_parameter.type, DPGModelType) for o in builder.overloads
+                _is_dpg_or_typeddict_body(o.parameters.body_parameter) for o in builder.overloads
             )
         if not all_dpg_model_overloads:
             for v in sorted(set(client_names), key=client_names.index):
@@ -1002,6 +1024,12 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
             elif self.code_model.options["models-mode"] == "dpg":
                 if builder.has_stream_response:
                     deserialize_code.append("deserialized = response.content")
+                elif isinstance(response.type, ModelType) and response.type.is_typed_dict_only:
+                    # Typed-dict-only models skip deserialization — return raw JSON
+                    deserialize_code.append("if response.content:")
+                    deserialize_code.append("    deserialized = response.json()")
+                    deserialize_code.append("else:")
+                    deserialize_code.append("    deserialized = None")
                 else:
                     format_filed = (
                         f', format="{response.type.encode}"'
@@ -1437,18 +1465,23 @@ class _PagingOperationSerializer(_OperationSerializer[PagingOperationType]):
             )
         pylint_disable = ""
         if self.code_model.options["models-mode"] == "dpg":
-            item_type = builder.item_type.type_annotation(
-                is_operation_file=True, serialize_namespace=self.serialize_namespace
-            )
-            pylint_disable = (
-                "  # pylint: disable=protected-access" if getattr(builder.item_type, "internal", False) else ""
-            )
-            list_of_elem_deserialized = [
-                "_deserialize(",
-                f"{item_type},{pylint_disable}",
-                f"deserialized{access},",
-                ")",
-            ]
+            is_item_typed_dict_only = isinstance(builder.item_type, ModelType) and builder.item_type.is_typed_dict_only
+            if is_item_typed_dict_only:
+                # Typed-dict-only models skip deserialization — return raw JSON items
+                list_of_elem_deserialized = [f"deserialized{access}"]
+            else:
+                item_type = builder.item_type.type_annotation(
+                    is_operation_file=True, serialize_namespace=self.serialize_namespace
+                )
+                pylint_disable = (
+                    "  # pylint: disable=protected-access" if getattr(builder.item_type, "internal", False) else ""
+                )
+                list_of_elem_deserialized = [
+                    "_deserialize(",
+                    f"{item_type},{pylint_disable}",
+                    f"deserialized{access},",
+                    ")",
+                ]
         else:
             list_of_elem_deserialized = [f"deserialized{access}"]
         list_of_elem_deserialized_str = "\n    ".join(list_of_elem_deserialized)

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

@@ -32,7 +32,7 @@ class ModelInitSerializer:
                         ", ".join(model_enum_name_intersection)
                     )
                 )
-        has_models = self.models
+        has_models = self.code_model.has_non_json_models(self.models)
         has_enums = self.enums
         template = self.env.get_template("model_init.py.jinja2")
         return template.render(

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

@@ -3,7 +3,7 @@
 # Licensed under the MIT License. See License.txt in the project root for
 # license information.
 # --------------------------------------------------------------------------
-from typing import Optional
+from typing import Any, Optional
 from abc import ABC, abstractmethod
 
 from ..models import ModelType, Property, ConstantType, EnumValue, EnumType
@@ -73,12 +73,19 @@ def _get_xml_deserializer_enum_type(prop: Property) -> Optional[EnumType]:
     return prop_type if isinstance(prop_type, EnumType) else None
 
 
-def _documentation_string(prop: Property, description_keyword: str, docstring_type_keyword: str) -> list[str]:
+def _documentation_string(
+    prop: Property, description_keyword: str, docstring_type_keyword: str, **kwargs: Any
+) -> list[str]:
     retval: list[str] = []
     sphinx_prefix = f":{description_keyword} {prop.client_name}:"
     description = prop.description(is_operation_file=False).replace("\\", "\\\\")
     retval.append(f"{sphinx_prefix} {description}" if description else sphinx_prefix)
-    retval.append(f":{docstring_type_keyword} {prop.client_name}: {prop.type.docstring_type()}")
+    # In the types file, use type_annotation (the serialized form) for docstrings
+    if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE:
+        doc_type = prop.type.type_annotation(**kwargs)
+    else:
+        doc_type = prop.type.docstring_type(**kwargs)
+    retval.append(f":{docstring_type_keyword} {prop.client_name}: {doc_type}")
     return retval
 
 
@@ -494,3 +501,120 @@ class DpgModelSerializer(_ModelSerializer):
         if final_result:
             return "# pylint: disable=" + ", ".join(final_result)
         return ""
+
+
+class TypedDictModelSerializer(_ModelSerializer):
+    def _is_parent_discriminated_base(self, model: ModelType) -> bool:
+        """Check if any parent of this model is a discriminated base (has discriminated_subtypes)."""
+        return any(p.discriminated_subtypes for p in model.parents)
+
+    def _reorder_models(self, models: list[ModelType]) -> list[ModelType]:
+        """Reorder so discriminated base Union aliases come after all their subtypes."""
+        bases = [m for m in models if m.discriminated_subtypes]
+        non_bases = [m for m in models if not m.discriminated_subtypes]
+        return non_bases + bases
+
+    def serialize(self) -> str:
+        template = self.env.get_template("model_container.py.jinja2")
+        return template.render(
+            code_model=self.code_model,
+            imports=FileImportSerializer(self.imports()),
+            str=str,
+            serializer=self,
+            models=self._reorder_models(self.models),
+        )
+
+    def imports(self) -> FileImport:
+        file_import = FileImport(self.code_model)
+        has_required = False
+        has_discriminated_union = False
+        for model in self.models:
+            if model.base == "json":
+                continue
+            if model.discriminated_subtypes:
+                has_discriminated_union = True
+            file_import.merge(
+                model.imports(
+                    is_operation_file=False,
+                    serialize_namespace=self.serialize_namespace,
+                    serialize_namespace_type=NamespaceType.MODEL,
+                )
+            )
+            for prop in model.properties:
+                file_import.merge(
+                    prop.imports(
+                        serialize_namespace=self.serialize_namespace,
+                        serialize_namespace_type=NamespaceType.MODEL,
+                        called_by_property=True,
+                    )
+                )
+                if not (prop.optional or prop.client_default_value is not None):
+                    has_required = True
+            for parent in model.parents:
+                if parent.client_namespace != model.client_namespace and not parent.discriminated_subtypes:
+                    file_import.add_submodule_import(
+                        self.code_model.get_relative_import_path(
+                            self.serialize_namespace,
+                            self.code_model.get_imported_namespace_for_model(parent.client_namespace),
+                        ),
+                        parent.name,
+                        ImportType.LOCAL,
+                    )
+        file_import.add_submodule_import("typing_extensions", "TypedDict", ImportType.STDLIB)
+        if has_required:
+            file_import.add_submodule_import("typing_extensions", "Required", ImportType.STDLIB)
+        if has_discriminated_union:
+            file_import.add_submodule_import("typing", "Union", ImportType.STDLIB)
+        return file_import
+
+    def declare_model(self, model: ModelType) -> str:
+        # If the model's parent is a discriminated base, don't inherit from it
+        non_discriminated_parents = [p for p in model.parents if not p.discriminated_subtypes]
+        if non_discriminated_parents:
+            basename = ", ".join([m.name for m in non_discriminated_parents])
+            return f"class {model.name}({basename}):{model.pylint_disable()}"
+        return f"class {model.name}(TypedDict, total=False):{model.pylint_disable()}"
+
+    @staticmethod
+    def get_properties_to_declare(model: ModelType) -> list[Property]:
+        # Only exclude inherited properties from non-discriminated parents
+        non_discriminated_parents = [p for p in model.parents if not p.discriminated_subtypes]
+        if non_discriminated_parents:
+            parent_properties = [p for bm in non_discriminated_parents for p in bm.properties]
+            properties_to_declare = [
+                p
+                for p in model.properties
+                if not any(
+                    p.client_name == pp.client_name
+                    and p.type_annotation() == pp.type_annotation()
+                    and not p.is_base_discriminator
+                    for pp in parent_properties
+                )
+            ]
+        else:
+            properties_to_declare = model.properties
+        return properties_to_declare
+
+    def declare_property(self, prop: Property) -> str:
+        type_annotation = prop.type_annotation(serialize_namespace=self.serialize_namespace)
+        is_optional = prop.optional or prop.client_default_value is not None
+        if is_optional:
+            return f"{prop.wire_name}: {type_annotation}"
+        return f"{prop.wire_name}: Required[{type_annotation}]"
+
+    def initialize_properties(self, model: ModelType) -> list[str]:
+        return []
+
+    def need_init(self, model: ModelType) -> bool:
+        return False
+
+    def discriminated_subtypes_union(self, model: ModelType) -> str:
+        subtypes = list(model.discriminated_subtypes.values())
+        subtype_names = [s.name for s in subtypes]
+        return f"{model.name} = Union[{', '.join(subtype_names)}]"
+
+    def is_discriminated_base(self, model: ModelType) -> bool:
+        return bool(model.discriminated_subtypes)
+
+    def global_pylint_disables(self) -> str:
+        return ""