feat(http-client-python): deprecate models-mode typeddict in favor of models-mode none

Rework the DPG TypedDict opt-out so models-mode only toggles dpg/none
(msrest kept for back-compat) and TypedDict output is controlled by the
generate-typeddict option. models-mode: none now remaps internally to the
typeddict-only path, reusing all existing machinery; models-mode: typeddict
is deprecated (still accepted with a warning). Update option docs, changelog,
SKILL, and regen-common dogfooding, and clarify internal preprocess comments.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 511e3e1d-5321-4281-8d91-d5be7a28d81d

Author: l0lawrence

.chronus/changes/python-disable-typeddict-generation-2026-7-24-12-59-0.md

@@ -4,4 +4,4 @@ packages:
   - "@typespec/http-client-python"
 ---
 
-Add a `generate-typeddict` emitter option to opt out of generating `TypedDict` request-body overloads in `models-mode: dpg`. Defaults to `true`; set it to `false` to disable the DPG `TypedDict` overloads.
+Add a `generate-typeddict` emitter option (default `true`) that controls `TypedDict` generation independently of `models-mode`. `models-mode` now toggles just `dpg` and `none`; the `typeddict` value is deprecated. 

packages/http-client-python/.github/skills/generate-from-typespec/SKILL.md

@@ -28,7 +28,7 @@ The caller must provide:
    If not provided, ask the user.
 4. **Additional options** (optional) — any extra `key=value` emitter options the
    user wants applied on top of the tspconfig options. These override tspconfig
-   values if there's a conflict (e.g., `models-mode=typeddict`).
+   values if there's a conflict (e.g., `generate-typeddict=false`).
 
 ## Workflow
 
@@ -191,7 +191,7 @@ After successful compilation:
    find < output-dir > -type d | sort
    ```
 
-2. Verify the output matches expectations (e.g., TypedDict if `models-mode=typeddict`).
+2. Verify the output matches expectations (e.g., TypedDict-only if `models-mode=none`).
 
 3. If the generation overwrote files in an existing package, warn the user and
    offer to revert non-generated files:
@@ -222,6 +222,7 @@ and `--option` flags. The `flavor` option controls branded behavior:
 
 | User request   | Option to add                                                   |
 | -------------- | --------------------------------------------------------------- |
-| TypedDict only | `--option "@typespec/http-client-python.models-mode=typeddict"` |
+| TypedDict only | `--option "@typespec/http-client-python.models-mode=none"`      |
+| No TypedDicts  | `--option "@typespec/http-client-python.generate-typeddict=false"` |
 | No tests       | `--option "@typespec/http-client-python.generate-test=false"`   |
 | No samples     | `--option "@typespec/http-client-python.generate-sample=false"` |

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 request-body overloads in `models-mode: dpg`. Defaults to `true`.
+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.
 
 ### `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 request-body overloads in `models-mode: dpg`. Defaults to `true`.",
+        "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.",
     },
     "keep-pyproject-fields": {
       type: "object",

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

@@ -321,7 +321,7 @@ export const EMITTER_OPTIONS: Record<string, Record<string, string> | Record<str
     {
       "package-name": "typetest-model-usage-typeddictonly",
       namespace: "typetest.model.usage.typeddictonly",
-      "models-mode": "typeddict",
+      "models-mode": "none",
     },
   ],
   "type/model/visibility": [

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

@@ -48,6 +48,7 @@ def __init__(self, options: Optional[dict[str, Any]] = None) -> None:
         self._data = options.copy() if options else {}
         for key in list(self._data):
             self._data[key] = self._validate_and_transform(key, self._data[key])
+        self._normalize_models_mode()
         self._validate_combinations()
 
     def __getitem__(self, key: str) -> Any:  # pylint: disable=too-many-return-statements
@@ -132,6 +133,38 @@ 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(
@@ -173,9 +206,10 @@ def _validate_and_transform(self, key: str, value: Any) -> Any:
 
         if key == "models-mode" and value not in ["msrest", "dpg", "typeddict", False]:
             raise ValueError(
-                "--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."
+                "--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)."
             )
         if key == "package-mode":
             if (

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

@@ -87,10 +87,12 @@ def add_overloads_for_body_param(yaml_data: dict[str, Any], skip_single_body_jso
     ``skip_single_body_json`` is the authoritative signal, computed by
     ``add_body_param_type``, for whether a TypedDict-style overload was inserted
     to replace the single-body raw-JSON overload on the spread (``base: json``)
-    path. It is True for both models-mode: dpg (generate-typeddict on) and
-    models-mode: typeddict, and False when TypedDict generation is disabled (in
+    path. It is True whenever TypedDicts are generated -- i.e. for the internal
+    ``dpg`` mode (with ``generate-typeddict`` on) and the internal ``typeddict``
+    mode (which the user-facing ``models-mode: none`` remaps to). It is False
+    when TypedDict generation is disabled (``generate-typeddict: false``), in
     which case the single-body raw-JSON overload is kept, matching pre-TypedDict
-    behavior).
+    behavior.
     """
     body_parameter = yaml_data["bodyParameter"]
     if not (
@@ -473,6 +475,8 @@ def add_body_param_type(
             )
             is_dpg_model = model_type.get("base") == "dpg"
             is_json_model = model_type.get("base") == "json"
+            # ``typeddict`` is now an internal-only models-mode: the user-facing
+            # ``models-mode: none`` (with generate-typeddict on) remaps to it.
             is_typeddict_only = self.options["models-mode"] == "typeddict"
 
             body_parameter["type"] = {

packages/http-client-python/tests/unit/test_options_dict.py

@@ -37,6 +37,39 @@ def test_generate_typeddict_can_be_disabled():
     assert OptionsDict({"generate-typeddict": False})["generate-typeddict"] is False
 
 
+def test_models_mode_none_with_tsp_generates_typeddict_by_default():
+    # For TypeSpec input, models-mode=none keeps TypedDict generation on by
+    # default, represented internally as the typeddict-only mode.
+    options = OptionsDict({"models-mode": "none", "tsp_file": "main.tsp"})
+    assert options["models-mode"] == "typeddict"
+
+
+def test_models_mode_none_with_tsp_and_generate_typeddict_false_is_nothing():
+    # Opting out of TypedDicts on top of models-mode=none produces no models.
+    options = OptionsDict({"models-mode": "none", "tsp_file": "main.tsp", "generate-typeddict": False})
+    assert options["models-mode"] is False
+
+
+def test_models_mode_none_without_tsp_stays_false():
+    # Swagger input: models-mode=none must remain "no models", untouched by the
+    # generate-typeddict default.
+    assert OptionsDict({"models-mode": "none"})["models-mode"] is False
+
+
+def test_models_mode_dpg_with_tsp_is_unchanged():
+    options = OptionsDict({"models-mode": "dpg", "tsp_file": "main.tsp"})
+    assert options["models-mode"] == "dpg"
+
+
+def test_models_mode_typeddict_is_deprecated_but_accepted(caplog):
+    import logging
+
+    with caplog.at_level(logging.WARNING):
+        options = OptionsDict({"models-mode": "typeddict", "tsp_file": "main.tsp"})
+    assert options["models-mode"] == "typeddict"
+    assert any("deprecated" in record.getMessage() for record in caplog.records)
+
+
 def test_package_mode_validation_uses_from_typespec_from_constructor_any_order():
     with pytest.raises(ValueError):
         OptionsDict({"from-typespec": True, "package-mode": "dataplane", "package-version": "1.0.0"})

packages/http-client-python/tests/unit/test_typeddict_overloads.py

@@ -92,6 +92,26 @@ def test_typeddict_only_single_body_emits_no_overload():
     assert body_parameter["type"]["type"] == "model"
 
 
+def test_models_mode_none_maps_to_typeddict_only():
+    """User-facing ``models-mode: none`` (TypeSpec) behaves as typeddict-only.
+
+    ``generate-typeddict`` defaults to ``True``, so ``none`` is remapped to the
+    internal typeddict-only mode by ``OptionsDict``. A lone TypedDict body variant
+    must still NOT emit a single ``@overload``.
+    """
+    plugin = _plugin("none")
+    # OptionsDict normalizes none + generate-typeddict -> internal typeddict mode.
+    assert plugin.options["models-mode"] == "typeddict"
+    code_model, yaml_data, model_type = _json_model_operation()
+    body_parameter = yaml_data["bodyParameter"]
+
+    skip_single_body_json = plugin.add_body_param_type(code_model, body_parameter)
+    add_overloads_for_body_param(yaml_data, skip_single_body_json=skip_single_body_json)
+
+    assert len(yaml_data["overloads"]) == 0
+    assert body_parameter["type"] is model_type
+
+
 def test_dpg_mode_still_emits_multiple_overloads():
     """Regression guard: dpg mode keeps its binary + typeddict overloads."""
     plugin = _plugin("dpg")

website/src/content/docs/docs/emitters/clients/http-client-python/reference/emitter.md

@@ -128,7 +128,7 @@ Whether to keep the existing `setup.py` when `generate-packaging-files` is `true
 
 **Type:** `boolean`
 
-Whether to generate TypedDict request-body overloads in `models-mode: dpg`. Defaults to `true`.
+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.
 
 ### `keep-pyproject-fields`