fix(http-client-python): address review feedback on TypedDict opt-out

- Remove synthetic internal `models-mode: typeddict`; represent the
  deprecated value as `models-mode: none` + `generate-typeddict: true`,
  and drive TypedDict-only behavior via a `generate_typeddict_only`
  helper instead of a fake models-mode.
- Replace generic `**kwargs` in the `_plugin` test helper with an
  explicit `generate_typeddict: bool` parameter.
- Drop msrest from the models-mode ValueError help text (back-compat only).
- Reword the `generate-typeddict` description: it adds TypedDict typing
  for JSON dict input, not an extra request-body overload.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: c8b26a94-682b-4350-a424-97093fd1c183

Author: l0lawrence

packages/http-client-python/README.md

@@ -134,7 +134,7 @@ Whether to keep the existing `setup.py` when `generate-packaging-files` is `true
 
 **Type:** `boolean`
 
-Whether to generate `TypedDict` types for request bodies. Defaults to `true`. With `models-mode: dpg` this adds `TypedDict` request-body overloads alongside the model classes; with `models-mode: none` it generates `TypedDict`-only types. Set to `false` to opt out of `TypedDict` generation.
+Whether to add TypedDict typing for JSON dictionary input in `models-mode: dpg`, instead of accepting only generic JSON. This enriches the typing on the existing overloads rather than adding another request-body overload. Defaults to `true`.
 
 ### `keep-pyproject-fields`
 

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

@@ -116,7 +116,7 @@ export const PythonEmitterOptionsSchema: JSONSchemaType<PythonEmitterOptions> =
       type: "boolean",
       nullable: true,
       description:
-        "Whether to generate `TypedDict` types for request bodies. Defaults to `true`. With `models-mode: dpg` this adds `TypedDict` request-body overloads alongside the model classes; with `models-mode: none` it generates `TypedDict`-only types. Set to `false` to opt out of `TypedDict` generation.",
+        "Whether to add TypedDict typing for JSON dictionary input in `models-mode: dpg`, instead of accepting only generic JSON. This enriches the typing on the existing overloads rather than adding another request-body overload. Defaults to `true`.",
     },
     "keep-pyproject-fields": {
       type: "object",

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

@@ -12,7 +12,7 @@
 from typing import Any, Iterator, Optional, Union
 
 import yaml
-from .utils import TYPESPEC_PACKAGE_MODE, VALID_PACKAGE_MODE
+from .utils import TYPESPEC_PACKAGE_MODE, VALID_PACKAGE_MODE, is_typeddict_only
 
 from ._version import VERSION
 
@@ -46,11 +46,19 @@ class OptionsDict(MutableMapping):
 
     def __init__(self, options: Optional[dict[str, Any]] = None) -> None:
         self._data = options.copy() if options else {}
+        # 'models-mode: typeddict' is deprecated. Represent it internally as 'none' models-mode with
+        # TypedDict generation enabled, so the rest of the codebase only reasons about dpg/msrest/none.
+        if self._data.get("models-mode") == "typeddict":
+            self._data["generate-typeddict"] = True
         for key in list(self._data):
             self._data[key] = self._validate_and_transform(key, self._data[key])
-        self._normalize_models_mode()
         self._validate_combinations()
 
+    @property
+    def generate_typeddict_only(self) -> bool:
+        """Whether this is the deprecated TypedDict-only generation ('models-mode: none' + TypedDicts)."""
+        return is_typeddict_only(self)
+
     def __getitem__(self, key: str) -> Any:  # pylint: disable=too-many-return-statements
         if key == "head-as-boolean" and self.get("azure-arm"):
             # override to always true if azure-arm is set
@@ -133,38 +141,6 @@ def _get_default(self, key: str) -> Any:  # pylint: disable=too-many-return-stat
             return self.get("flavor") == "azure"
         return self.DEFAULTS[key]
 
-    def _normalize_models_mode(self) -> None:
-        """Reconcile ``models-mode`` with ``generate-typeddict`` for TypeSpec generation.
-
-        The user-facing ``models-mode`` values are ``dpg`` and ``none`` (``msrest``
-        is kept for back-compat). TypedDict output is controlled independently by
-        ``generate-typeddict`` (default ``True``):
-
-        * ``dpg``  + ``generate-typeddict``    -> DPG models and TypedDict overloads
-        * ``dpg``  + no ``generate-typeddict`` -> DPG models only
-        * ``none`` + ``generate-typeddict``    -> TypedDicts only
-        * ``none`` + no ``generate-typeddict`` -> nothing
-
-        ``models-mode: typeddict`` is deprecated; it is still accepted (with a
-        warning) and behaves as TypedDict-only. Internally, TypedDict-only
-        generation is represented by ``models-mode == "typeddict"``, so the
-        ``none`` + TypedDicts case is remapped to it here. This only applies to
-        TypeSpec input; swagger ``models-mode: none`` is left untouched.
-        """
-        if "models-mode" not in self._data:
-            return
-        models_mode = self._data["models-mode"]
-        if models_mode == "typeddict":
-            _LOGGER.warning(
-                "'models-mode: typeddict' is deprecated. Use 'models-mode: none' instead "
-                "(TypedDicts are generated by default; set 'generate-typeddict: false' to opt out)."
-            )
-            return
-        # 'none' is stored as falsy False. For TypeSpec, keep generating TypedDicts
-        # by default by remapping to the internal typeddict-only mode.
-        if bool(self._data.get("tsp_file")) and models_mode is False and self.get("generate-typeddict"):
-            self._data["models-mode"] = "typeddict"
-
     def _validate_combinations(self) -> None:
         if not self.get("show-operations") and self.get("builders-visibility") == "embedded":
             raise ValueError(
@@ -201,15 +177,22 @@ def _validate_and_transform(self, key: str, value: Any) -> Any:
         if key == "builders-visibility" and value not in ["public", "hidden", "embedded"]:
             raise ValueError("The value of --builders-visibility must be either 'public', 'hidden', or 'embedded'")
 
+        if key == "models-mode" and value == "typeddict":
+            # Deprecated: keep accepting it for back-compat but store it as 'none' (falsy) with
+            # TypedDict generation enabled (see OptionsDict.__init__ and generate_typeddict_only).
+            _LOGGER.warning(
+                "'models-mode: typeddict' is deprecated. Use 'models-mode: none' with "
+                "'generate-typeddict: true' (the default) instead."
+            )
+            value = False
+
         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", "typeddict", False]:
+        if key == "models-mode" and value not in ["msrest", "dpg", False]:
             raise ValueError(
-                "--models-mode can only be 'msrest', 'dpg', or 'none'. "
-                "Pass in 'msrest' if you want msrest models, 'dpg' for DPG models, or "
-                "'none' if you don't want any. TypedDicts are controlled by --generate-typeddict "
-                "(the deprecated 'typeddict' value is still accepted for back-compat)."
+                "--models-mode can only be 'dpg' or 'none'. "
+                "Pass in 'dpg' for DPG models, or 'none' if you don't want any."
             )
         if key == "package-mode":
             if (

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

@@ -169,7 +169,9 @@ def build_type(yaml_data: dict[str, Any], code_model: CodeModel) -> BaseType:
         # need to special case model to avoid recursion
         if yaml_data["base"] == "typeddict":
             model_type = TypedDictModelType  # type: ignore
-        elif yaml_data["base"] == "json" or not code_model.options["models-mode"]:
+        elif yaml_data["base"] == "json" or (
+            not code_model.options["models-mode"] and not code_model.generate_typeddict_only
+        ):
             model_type = JSONModelType
         elif yaml_data["base"] == "dpg":
             model_type = DPGModelType  # type: ignore

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

@@ -17,6 +17,7 @@
 from .utils import NamespaceType
 from .._utils import DEFAULT_HEADER_TEXT, DEFAULT_LICENSE_DESCRIPTION
 from ... import OptionsDict
+from ...utils import is_typeddict_only
 
 
 def _is_legacy(options) -> bool:
@@ -89,7 +90,7 @@ def __init__(
         self.clients: list[Client] = [
             Client.from_yaml(client_yaml_data, self) for client_yaml_data in yaml_data["clients"]
         ]
-        if self.options["models-mode"] and self.model_types:
+        if (self.options["models-mode"] or self.generate_typeddict_only) and self.model_types:
             self.sort_model_types()
         self.named_unions: list[CombinedType] = [
             t for t in self.types_map.values() if isinstance(t, CombinedType) and t.name
@@ -174,6 +175,11 @@ def get_unique_models_alias(self, serialize_namespace: str, imported_namespace:
     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 generate_typeddict_only(self) -> bool:
+        """Whether this is the deprecated TypedDict-only generation ('models-mode: none' + TypedDicts)."""
+        return is_typeddict_only(self.options)
+
     @property
     def client_namespace_types(self) -> dict[str, ClientNamespaceType]:
         if not self._client_namespace_types:

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

@@ -40,7 +40,7 @@ def description(self, *, is_operation_file: bool) -> str:
 
     def type_annotation(self, **kwargs: Any) -> str:
         """The python type used for type annotation"""
-        if self.code_model.options["models-mode"] == "typeddict":
+        if self.code_model.generate_typeddict_only:
             # A single constant enum value must be
             # annotated with its literal value directly (e.g. ``Literal["red"]``).
             return f"Literal[{self.value_type.get_declaration(self.value)}]"
@@ -83,7 +83,7 @@ def imports(self, **kwargs: Any) -> FileImport:
         file_import = FileImport(self.code_model)
         file_import.merge(self.value_type.imports(**kwargs))
         file_import.add_submodule_import("typing", "Literal", ImportType.STDLIB, TypingSection.REGULAR)
-        if self.code_model.options["models-mode"] == "typeddict":
+        if self.code_model.generate_typeddict_only:
             # In typeddict mode the enums module (``_enums.py``) is never generated
             return file_import
         serialize_namespace = kwargs.get("serialize_namespace", self.code_model.namespace)
@@ -176,15 +176,15 @@ def description(self, *, is_operation_file: bool) -> str:
 
     @property
     def is_typeddict_mode(self) -> bool:
-        return self.code_model.options["models-mode"] == "typeddict"
+        return self.code_model.generate_typeddict_only
 
     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.code_model.options["models-mode"] or self.code_model.generate_typeddict_only:
             if self.is_typeddict_mode:
                 # In typeddict mode, enums are Literal aliases defined in types.py
                 serialize_namespace_type = kwargs.get("serialize_namespace_type")
@@ -221,13 +221,13 @@ def get_declaration(self, value: Any) -> str:
         return self.value_type.get_declaration(value)
 
     def docstring_text(self, **kwargs: Any) -> str:
-        if self.code_model.options["models-mode"]:
+        if self.code_model.options["models-mode"] or self.code_model.generate_typeddict_only:
             return self.name
         return self.value_type.type_annotation(**kwargs)
 
     def docstring_type(self, **kwargs: Any) -> str:
         """The python type used for RST syntax input and type annotation."""
-        if self.code_model.options["models-mode"]:
+        if self.code_model.options["models-mode"] or self.code_model.generate_typeddict_only:
             type_annotation = self.value_type.type_annotation(**kwargs)
             enum_type_annotation = f"{self.client_namespace}.models.{self.name}"
             return f"{type_annotation} or ~{enum_type_annotation}"
@@ -261,7 +261,7 @@ def from_yaml(cls, yaml_data: dict[str, Any], code_model: "CodeModel") -> "EnumT
     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"]:
+        if self.code_model.options["models-mode"] or self.code_model.generate_typeddict_only:
             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")

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

@@ -38,6 +38,7 @@ def type_annotation(self, **kwargs: Any) -> str:
             self.code_model.options["version-tolerant"]
             and self.element_type.is_xml
             and not self.code_model.options["models-mode"]
+            and not self.code_model.generate_typeddict_only
         ):
             # this means we're version tolerant XML, we just return the XML element
             return self.element_type.type_annotation(**kwargs)

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

@@ -77,9 +77,7 @@ def __init__(
         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"
-        )
+        self.is_typed_dict_only: bool = self.yaml_data.get("typedDictOnly", False) or code_model.generate_typeddict_only
 
     @property
     def is_usage_output(self) -> bool:

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

@@ -334,7 +334,7 @@ def imports(  # pylint: disable=too-many-branches, disable=too-many-statements
             file_import.merge(
                 response.imports(async_mode=async_mode, need_import_iobase=self.need_import_iobase, **kwargs)
             )
-        if self.code_model.options["models-mode"]:
+        if self.code_model.options["models-mode"] or self.code_model.generate_typeddict_only:
             for exception in self.exceptions:
                 file_import.merge(exception.imports(async_mode=async_mode, **kwargs))
 
@@ -552,7 +552,12 @@ def imports(self, async_mode: bool, **kwargs: Any) -> FileImport:
                 "distributed_trace_async",
                 ImportType.SDKCORE,
             )
-        if self.has_response_body and not self.has_optional_return_type and not self.code_model.options["models-mode"]:
+        if (
+            self.has_response_body
+            and not self.has_optional_return_type
+            and not self.code_model.options["models-mode"]
+            and not self.code_model.generate_typeddict_only
+        ):
             file_import.add_submodule_import("typing", "cast", ImportType.STDLIB)
 
         return file_import

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

@@ -338,7 +338,9 @@ def method_location(  # pylint: disable=too-many-return-statements
     ) -> 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"] in ("dpg", "typeddict") and self.in_flattened_body:
+        if (
+            self.code_model.options["models-mode"] == "dpg" or self.code_model.generate_typeddict_only
+        ) and self.in_flattened_body:
             return ParameterMethodLocation.KEYWORD_ONLY
         if self.grouper:
             return ParameterMethodLocation.POSITIONAL