@typespec/http-client-python 0.32.0 → 0.34.0

package/generator/build/lib/pygen/preprocess/__init__.py

@@ -22,6 +22,7 @@ from ..utils import (
     get_body_type_for_description,
     JSON_REGEXP,
     KNOWN_TYPES,
+    description_ends_with_code_block,
 )
 
 
@@ -93,6 +94,8 @@ def add_overloads_for_body_param(yaml_data: dict[str, Any]) -> None:
             continue
         if body_type.get("type") == "model" and body_type.get("base") == "json":
             yaml_data["overloads"].append(add_overload(yaml_data, body_type, for_flatten_params=True))
+            # Skip single-body JSON overload; the TypedDict overload replaces it
+            continue
         yaml_data["overloads"].append(add_overload(yaml_data, body_type))
     content_type_param = next(p for p in yaml_data["parameters"] if p["wireName"].lower() == "content-type")
     content_type_param["inOverload"] = False
@@ -108,7 +111,9 @@ def update_description(description: Optional[str], default_description: str = ""
     if not description:
         description = default_description
     description.rstrip(" ")
-    if description and description[-1] != ".":
+    # Don't append a trailing period when the description ends with a code block: the
+    # period would land inside the rendered literal block (e.g. "]." ) and break Sphinx.
+    if description and description[-1] != "." and not description_ends_with_code_block(description):
         description += "."
     return description
 
@@ -301,6 +306,44 @@ class PreProcessPlugin(YamlUpdatePlugin):
     def is_tsp(self) -> bool:
         return self.options.get("tsp_file", False)
 
+    @staticmethod
+    def _find_existing_typeddict(code_model: dict[str, Any], cross_lang_id: Optional[str]) -> Optional[dict[str, Any]]:
+        """Find an existing typeddict copy with the given crossLanguageDefinitionId."""
+        if not cross_lang_id:
+            return None
+        return next(
+            (
+                t
+                for t in code_model["types"]
+                if t.get("type") == "model"
+                and t.get("base") == "typeddict"
+                and t.get("crossLanguageDefinitionId") == cross_lang_id
+            ),
+            None,
+        )
+
+    @staticmethod
+    def _insert_typeddict_overload(
+        code_model: dict[str, Any],
+        body_parameter: dict[str, Any],
+        source: dict[str, Any],
+        origin_type: str,
+        existing_td: Optional[dict[str, Any]],
+    ) -> None:
+        """Insert a typeddict type into the body parameter's combined types."""
+        if origin_type == "model":
+            td_type = existing_td or {**source, "base": "typeddict"}
+            body_parameter["type"]["types"].insert(1, td_type)
+            if not existing_td:
+                code_model["types"].append(td_type)
+        else:
+            td_list_or_dict = copy.deepcopy(body_parameter["type"]["types"][0])
+            td_elem = existing_td or {**source, "base": "typeddict"}
+            td_list_or_dict["elementType"] = td_elem
+            body_parameter["type"]["types"].insert(1, td_list_or_dict)
+            if not existing_td:
+                code_model["types"].append(td_elem)
+
     def add_body_param_type(
         self,
         code_model: dict[str, Any],
@@ -319,25 +362,65 @@ class PreProcessPlugin(YamlUpdatePlugin):
                 body_parameter["type"] if origin_type == "model" else body_parameter["type"].get("elementType", {})
             )
             is_dpg_model = model_type.get("base") == "dpg"
+            is_json_model = model_type.get("base") == "json"
+            is_typeddict_only = self.options["models-mode"] == "typeddict"
+
             body_parameter["type"] = {
                 "type": "combined",
                 "types": [body_parameter["type"]],
             }
-            # don't add binary overload for multipart content type
-            if not (self.is_tsp and has_multi_part_content_type(body_parameter)):
+            # don't add binary overload for multipart content type or typeddict-only mode
+            if not (self.is_tsp and has_multi_part_content_type(body_parameter)) and not is_typeddict_only:
                 body_parameter["type"]["types"].append(KNOWN_TYPES["binary"])
 
+            # Add typeddict overload for non-spread dpg models
             if self.options["models-mode"] == "dpg" and is_dpg_model:
-                if origin_type == "model":
-                    body_parameter["type"]["types"].insert(1, KNOWN_TYPES["any-object"])
+                cross_lang_id = model_type.get("crossLanguageDefinitionId")
+                existing_td = self._find_existing_typeddict(code_model, cross_lang_id)
+                self._insert_typeddict_overload(code_model, body_parameter, model_type, origin_type, existing_td)
+
+            # For spread bodies (json base), add a typeddict overload that references
+            # the original model. This replaces the JSON single-body overload.
+            if is_json_model:
+                cross_lang_id = model_type.get("crossLanguageDefinitionId")
+                original = None
+                if cross_lang_id:
+                    original = next(
+                        (
+                            t
+                            for t in code_model["types"]
+                            if t.get("type") == "model"
+                            and t.get("crossLanguageDefinitionId") == cross_lang_id
+                            and t is not model_type
+                        ),
+                        None,
+                    )
+
+                if is_typeddict_only and original:
+                    # In typeddict-only mode, the original dpg model already renders
+                    # as a TypedDict — reference it directly, no copy needed.
+                    if origin_type == "model":
+                        body_parameter["type"]["types"].insert(1, original)
+                    else:
+                        td_list_or_dict = copy.deepcopy(body_parameter["type"]["types"][0])
+                        td_list_or_dict["elementType"] = original
+                        body_parameter["type"]["types"].insert(1, td_list_or_dict)
                 else:
-                    # dict or list
-                    # copy the original dict / list type
-                    any_obj_list_or_dict = copy.deepcopy(body_parameter["type"]["types"][0])
-                    any_obj_list_or_dict["elementType"] = KNOWN_TYPES["any-object"]
-                    body_parameter["type"]["types"].insert(1, any_obj_list_or_dict)
+                    source = original or model_type
+                    existing_td = self._find_existing_typeddict(code_model, cross_lang_id)
+                    self._insert_typeddict_overload(code_model, body_parameter, source, origin_type, existing_td)
+
+            if len(body_parameter["type"]["types"]) == 1:
+                # Only one body variant remains (e.g. typeddict-only mode where the
+                # binary and JSON overloads are omitted). Collapse the combined
+                # wrapper back to the single type so we don't emit a lone
+                # ``@overload`` (mypy rejects a single overload definition).
+                body_parameter["type"] = body_parameter["type"]["types"][0]
+                return
+
             code_model["types"].append(body_parameter["type"])
 
+
     def pad_reserved_words(self, name: str, pad_type: PadType, yaml_type: dict[str, Any]) -> str:
         # we want to pad hidden variables as well
         if not name:
@@ -485,7 +568,11 @@ class PreProcessPlugin(YamlUpdatePlugin):
             if yaml_data.get("isLroInitialOperation") is True:
                 yaml_data["name"] = (
                     "_"
-                    + self.pad_reserved_words(extract_original_name(yaml_data["name"]), PadType.METHOD, yaml_data)
+                    + self.pad_reserved_words(
+                        extract_original_name(yaml_data["name"]),
+                        PadType.METHOD,
+                        yaml_data,
+                    )
                     + "_initial"
                 )
             else:
@@ -576,7 +663,9 @@ class PreProcessPlugin(YamlUpdatePlugin):
         item_type = item_type or yaml_data["itemType"]["elementType"]
         if yaml_data.get("nextOperation"):
             yaml_data["nextOperation"]["groupName"] = self.pad_reserved_words(
-                yaml_data["nextOperation"]["groupName"], PadType.OPERATION_GROUP, yaml_data["nextOperation"]
+                yaml_data["nextOperation"]["groupName"],
+                PadType.OPERATION_GROUP,
+                yaml_data["nextOperation"],
             )
             yaml_data["nextOperation"]["groupName"] = to_snake_case(yaml_data["nextOperation"]["groupName"])
             for response in yaml_data["nextOperation"].get("responses", []):
@@ -598,7 +687,9 @@ class PreProcessPlugin(YamlUpdatePlugin):
             )
             operation_group["identifyName"] = to_snake_case(operation_group["identifyName"])
             operation_group["propertyName"] = self.pad_reserved_words(
-                operation_group["propertyName"], PadType.OPERATION_GROUP, operation_group
+                operation_group["propertyName"],
+                PadType.OPERATION_GROUP,
+                operation_group,
             )
             operation_group["propertyName"] = to_snake_case(operation_group["propertyName"])
             operation_group["className"] = update_operation_group_class_name(

package/generator/build/lib/pygen/utils.py

@@ -11,6 +11,22 @@ SWAGGER_PACKAGE_MODE = ["mgmtplane", "dataplane"]  # for backward compatibility
 TYPESPEC_PACKAGE_MODE = ["azure-mgmt", "azure-dataplane", "generic"]
 VALID_PACKAGE_MODE = SWAGGER_PACKAGE_MODE + TYPESPEC_PACKAGE_MODE
 
+CODE_BLOCK_MARKER = ".. code-block::"
+
+
+def description_ends_with_code_block(description: str) -> bool:
+    """Return True when the description's trailing content is an RST ``.. code-block::``.
+
+    True when the last ``.. code-block::`` directive (starting its own line, so inline
+    mentions are ignored) is followed only by blank or indented lines, i.e. the literal
+    block runs to the end of the description.
+    """
+    lines = description.rstrip().splitlines()
+    directives = [i for i, line in enumerate(lines) if line.lstrip().startswith(CODE_BLOCK_MARKER)]
+    if not directives:
+        return False
+    return all(not line.strip() or line.startswith((" ", "\t")) for line in lines[directives[-1] + 1 :])
+
 
 def update_enum_value(name: str, value: Any, description: str, enum_type: dict[str, Any]) -> dict[str, Any]:
     return {

package/generator/pygen/__init__.py

@@ -29,6 +29,7 @@ class OptionsDict(MutableMapping):
         "from-typespec": False,
         "generate-sample": False,
         "keep-setup-py": False,
+        "keep-pyproject-fields": "",
         "generate-test": False,
         "head-as-boolean": True,
         "keep-version-file": False,
@@ -167,10 +168,10 @@ class OptionsDict(MutableMapping):
         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":

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

@@ -9,7 +9,7 @@ from .base import BaseModel
 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

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

@@ -152,16 +152,28 @@ class CodeModel:  # pylint: disable=too-many-public-methods, disable=too-many-in
             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 @@ class CodeModel:  # pylint: disable=too-many-public-methods, disable=too-many-in
                 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 @@ class CodeModel:  # pylint: disable=too-many-public-methods, disable=too-many-in
         """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 @@ class CodeModel:  # pylint: disable=too-many-public-methods, disable=too-many-in
 
     @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]:

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

@@ -66,7 +66,7 @@ class CombinedType(BaseType):
 
     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 @@ class CombinedType(BaseType):
         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,
             )

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

@@ -167,6 +167,10 @@ class EnumType(BaseType):
         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
 
@@ -174,9 +178,20 @@ class EnumType(BaseType):
         :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 @@ class EnumType(BaseType):
         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

package/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 @@ class ListType(BaseType):
             # 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: