@typespec/http-client-python 0.35.1 → 0.36.0

package/emitter/test/browser-pyodide.test.ts

@@ -0,0 +1,25 @@
+import { strictEqual } from "assert";
+import { afterEach, describe, it, vi } from "vitest";
+
+const loadPyodide = vi.hoisted(() => vi.fn());
+
+vi.mock("../src/pyodide-loader.js", () => ({ loadPyodide }));
+
+describe("typespec-python: browser pyodide bootstrap", () => {
+  afterEach(() => {
+    delete (globalThis as any).window;
+    loadPyodide.mockReset();
+    vi.resetModules();
+  });
+
+  // Hosts like the TypeSpec playground import every available emitter up front. Booting Pyodide at
+  // module scope downloaded a full CPython WebAssembly runtime on every page load, which pushed the
+  // page past the per-tab memory budget on mobile browsers and prevented it from loading.
+  it("does not boot pyodide when the emitter is imported in a browser", async () => {
+    (globalThis as any).window = globalThis;
+
+    await import("../src/emitter.js");
+
+    strictEqual(loadPyodide.mock.calls.length, 0);
+  });
+});

package/emitter/test/types.test.ts

@@ -0,0 +1,72 @@
+import type { SdkBuiltInType } from "@azure-tools/typespec-client-generator-core";
+import { deepStrictEqual } from "assert";
+import { describe, it } from "vitest";
+import type { PythonSdkContext } from "../src/lib.js";
+import { getType } from "../src/types.js";
+
+function createBuiltInType(
+  kind: SdkBuiltInType["kind"],
+  encode?: string,
+  wireType?: SdkBuiltInType,
+): SdkBuiltInType {
+  return {
+    kind,
+    name: kind,
+    crossLanguageDefinitionId: `TypeSpec.${kind}`,
+    decorators: [],
+    encode,
+    wireType,
+  };
+}
+
+function emitBuiltInType(type: SdkBuiltInType): Record<string, any> {
+  const context = {
+    __simpleTypesMap: new Map(),
+  } as PythonSdkContext;
+  return getType(context, type);
+}
+
+describe("typespec-python: built-in types", () => {
+  it("preserves boolean encoded as string", () => {
+    deepStrictEqual(
+      emitBuiltInType(createBuiltInType("boolean", "string", createBuiltInType("string"))),
+      {
+        type: "boolean",
+        encode: "string",
+      },
+    );
+  });
+
+  it.each(["safeint", "uint32", "uint8"] as const)(
+    "preserves %s encoded as string as an integer",
+    (kind) => {
+      deepStrictEqual(
+        emitBuiltInType(createBuiltInType(kind, "string", createBuiltInType("string"))),
+        {
+          type: "integer",
+          encode: "string",
+        },
+      );
+    },
+  );
+
+  it.each(["base64", "base64url"] as const)("preserves bytes encoded as %s", (encode) => {
+    deepStrictEqual(
+      emitBuiltInType(createBuiltInType("bytes", encode, createBuiltInType("string"))),
+      {
+        type: "bytes",
+        encode,
+      },
+    );
+  });
+
+  it("falls back to the wire type for a custom encoding", () => {
+    deepStrictEqual(
+      emitBuiltInType(createBuiltInType("string", "abc", createBuiltInType("int32"))),
+      {
+        type: "integer",
+        encode: "abc",
+      },
+    );
+  });
+});

package/eng/scripts/ci/dev_requirements.txt

@@ -7,6 +7,6 @@ colorama==0.4.6
 debugpy==1.8.2
 pytest==9.0.3
 coverage==7.6.1
-black==24.4.0
+black==26.3.1
 ptvsd==4.3.2
 types-PyYAML==6.0.12.8

package/eng/scripts/ci/regenerate-common.ts

@@ -69,7 +69,11 @@ export interface BuildTaskGroupsOptions {
 
 // ---- Public constants ----
 
-export const SKIP_SPECS: string[] = ["type/file"];
+export const SKIP_SPECS: string[] = [
+  "type/file",
+  // LroPaging.postPagingLroWithBody generates begin_post_paging_lro_with_body with pylint R0915 (52/50).
+  "azure/resource-manager/operation-templates",
+];
 
 export const SpecialFlags: Record<string, Record<string, any>> = {
   azure: {
@@ -320,7 +324,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": [

package/eng/scripts/ci/regenerate.ts

@@ -20,13 +20,12 @@ import pc from "picocolors";
 import { fileURLToPath } from "url";
 import { parseArgs } from "util";
 
+import type { RegenerateContext, RegenerateFlags } from "./regenerate-common.js";
 import {
   buildTaskGroups,
   cleanGeneratedCode,
   getSubdirectories,
   preprocess,
-  RegenerateContext,
-  RegenerateFlags,
   runParallel,
 } from "./regenerate-common.js";
 

package/eng/scripts/ci/run-tests.ts

@@ -1,5 +1,6 @@
 /* eslint-disable no-console */
-import { ChildProcess, spawn } from "child_process";
+import type { ChildProcess } from "child_process";
+import { spawn } from "child_process";
 import fs from "fs";
 import { cpus } from "os";
 import { dirname, join } from "path";

package/eng/scripts/setup/system-requirements.ts

@@ -1,4 +1,5 @@
-import { ChildProcess, spawn, SpawnOptions } from "child_process";
+import type { ChildProcess, SpawnOptions } from "child_process";
+import { spawn } from "child_process";
 
 /*
  * Copied from @autorest/system-requirements

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

@@ -12,7 +12,7 @@ from abc import ABC, abstractmethod
 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
 
@@ -36,6 +36,7 @@ class OptionsDict(MutableMapping):
         "low-level-client": False,
         "no-async": False,
         "no-namespace-folders": False,
+        "generate-typeddict": True,
         "polymorphic-examples": 5,
         "validate-versioning": True,
         "version-tolerant": True,
@@ -45,10 +46,20 @@ 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 reasons in terms of models-mode
+        # plus the generate-typeddict flag.
+        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._validate_combinations()
 
+    @property
+    def generate_typeddict_only(self) -> bool:
+        """Whether this is 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
@@ -167,14 +178,22 @@ class OptionsDict(MutableMapping):
         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', '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 'dpg' or 'none'. "
+                "Pass in 'dpg' for DPG models, or 'none' if you don't want any."
             )
         if key == "package-mode":
             if (

package/generator/build/lib/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

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

@@ -17,6 +17,7 @@ from .operation_group import OperationGroup
 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 @@ class CodeModel:  # pylint: disable=too-many-public-methods, disable=too-many-in
         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 @@ class CodeModel:  # pylint: disable=too-many-public-methods, disable=too-many-in
     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 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:

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

@@ -40,7 +40,7 @@ class EnumValue(BaseType):
 
     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 @@ class EnumValue(BaseType):
         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,7 +176,7 @@ class EnumType(BaseType):
 
     @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
@@ -184,7 +184,7 @@ class EnumType(BaseType):
         :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 @@ class EnumType(BaseType):
         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 @@ class EnumType(BaseType):
     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")

package/generator/build/lib/pygen/codegen/models/list_type.py

@@ -38,6 +38,7 @@ class ListType(BaseType):
             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)

package/generator/build/lib/pygen/codegen/models/model_type.py

@@ -77,9 +77,7 @@ class ModelType(BaseType):  # pylint: disable=too-many-instance-attributes, too-
         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:

package/generator/build/lib/pygen/codegen/models/operation.py

@@ -334,7 +334,7 @@ class OperationBase(  # pylint: disable=too-many-public-methods,too-many-instanc
             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 @@ class Operation(OperationBase[Response]):
                 "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

package/generator/build/lib/pygen/codegen/models/parameter.py

@@ -338,7 +338,9 @@ class Parameter(_ParameterBase):
     ) -> 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

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

@@ -34,6 +34,20 @@ def add_to_pylint_disable(curr_str: str, entry: str) -> str:
     return f"  # pylint: disable={entry}"
 
 
+def escape_sphinx_field_name(name: str) -> str:
+    """Escape a name used as the target of a Sphinx info field (``:ivar``, ``:vartype``,
+    ``:keyword``, ``:paramtype``, ``:param``, ``:type``).
+
+    A name containing ``@`` (e.g. a wire name such as ``@search.facets``) is wrapped in
+    double backticks so it is treated as an inline literal. This renders cleanly in Sphinx
+    without a leading ``@`` being misinterpreted, and — unlike a ``\\@`` escape — introduces
+    no invalid escape sequence into the generated Python docstring.
+    """
+    if "@" in name:
+        return f"``{name}``"
+    return name
+
+
 class NamespaceType(str, Enum):
     """Special signal for impports"""
 

package/generator/build/lib/pygen/codegen/serializers/__init__.py

@@ -207,10 +207,10 @@ class JinjaSerializer(ReaderAndWriter):
                 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"]:
+            is_typeddict_mode = self.code_model.generate_typeddict_only
+            if (self.code_model.has_non_json_models(client_namespace_type.models) or client_namespace_type.enums) and (
+                self.code_model.options["models-mode"] or self.code_model.generate_typeddict_only
+            ):
                 self._serialize_and_write_models_folder(
                     env=env,
                     namespace=client_namespace,
@@ -238,7 +238,7 @@ class JinjaSerializer(ReaderAndWriter):
                     ).serialize(),
                 )
 
-            if not self.code_model.options["models-mode"]:
+            if not self.code_model.options["models-mode"] and not self.code_model.generate_typeddict_only:
                 # keep models file if users ended up just writing a models file
                 model_path = generation_path / Path("models.py")
                 if self.read_file(model_path):
@@ -321,7 +321,7 @@ class JinjaSerializer(ReaderAndWriter):
         # Write the models folder
         models_path = self.code_model.get_generation_dir(namespace) / "models"
         models_mode = self.code_model.options["models-mode"]
-        if models_mode in ("dpg", "typeddict"):
+        if models_mode == "dpg" or self.code_model.generate_typeddict_only:
             serializer = DpgModelSerializer
         else:
             serializer = MsrestModelSerializer

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

@@ -32,7 +32,7 @@ from ..models import (
     ParameterListType,
     ByteArraySchema,
 )
-from ..models.utils import NamespaceType
+from ..models.utils import NamespaceType, escape_sphinx_field_name
 from .parameter_serializer import ParameterSerializer, PopKwargType, check_body_optional
 from ..models.parameter_list import ParameterType
 from . import utils
@@ -311,16 +311,15 @@ class _BuilderBaseSerializer(Generic[BuilderType]):
                 or param.method_location == ParameterMethodLocation.KWARG
             ):
                 continue
+            escaped_name = escape_sphinx_field_name(param.client_name)
             description_list.extend(
-                f":{param.description_keyword} {param.client_name}: {param.description}".replace("\n", "\n ").split(
-                    "\n"
-                )
+                f":{param.description_keyword} {escaped_name}: {param.description}".replace("\n", "\n ").split("\n")
             )
             docstring_type = param.docstring_type(
                 async_mode=self.async_mode,
                 serialize_namespace=self.serialize_namespace,
             )
-            description_list.append(f":{param.docstring_type_keyword} {param.client_name}: {docstring_type}")
+            description_list.append(f":{param.docstring_type_keyword} {escaped_name}: {docstring_type}")
         return description_list
 
     def param_description_and_response_docstring(self, builder: BuilderType) -> list[str]:
@@ -715,7 +714,9 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
         send_xml = builder.parameters.body_parameter.type.is_xml
         xml_serialization_ctxt = body_param.type.xml_serialization_ctxt if send_xml else None
         ser_ctxt_name = "serialization_ctxt"
-        if xml_serialization_ctxt and self.code_model.options["models-mode"]:
+        if xml_serialization_ctxt and (
+            self.code_model.options["models-mode"] or self.code_model.generate_typeddict_only
+        ):
             retval.append(f'{ser_ctxt_name} = {{"xml": {{{xml_serialization_ctxt}}}}}')
         if self.code_model.options["models-mode"] == "msrest":
             is_xml_cmd = _xml_config(send_xml, builder.parameters.body_parameter.content_types)
@@ -725,7 +726,7 @@ 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":
+        elif self.code_model.generate_typeddict_only:
             # 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":
@@ -844,7 +845,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"] in ("dpg", "typeddict") and builder.overloads:
+        if (
+            self.code_model.options["models-mode"] == "dpg" or self.code_model.generate_typeddict_only
+        ) and builder.overloads:
             all_dpg_model_overloads = all(
                 _is_dpg_or_typeddict_body(o.parameters.body_parameter) for o in builder.overloads
             )
@@ -1131,8 +1134,8 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
             retval.extend([f"    {l}" for l in response_read])
         retval.append("    map_error(status_code=response.status_code, response=response, error_map=error_map)")
         error_model = ""
-        if (  # pylint: disable=too-many-nested-blocks
-            builder.non_default_errors and self.code_model.options["models-mode"]
+        if builder.non_default_errors and (  # pylint: disable=too-many-nested-blocks
+            self.code_model.options["models-mode"] or self.code_model.generate_typeddict_only
         ):
             error_model = ", model=error"
             condition = "if"
@@ -1214,7 +1217,9 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
                     condition = "elif"
         # default error handling
         default_error_deserialization = builder.default_error_deserialization(self.serialize_namespace)
-        if default_error_deserialization and self.code_model.options["models-mode"]:
+        if default_error_deserialization and (
+            self.code_model.options["models-mode"] or self.code_model.generate_typeddict_only
+        ):
             error_model = ", model=error"
             indent = "        " if builder.non_default_errors else "    "
             if builder.non_default_errors:
@@ -1293,7 +1298,11 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
             else:
                 retval.extend(self.response_headers_and_deserialization(builder, builder.responses[0]))
                 retval.append("")
-        if builder.has_optional_return_type or self.code_model.options["models-mode"]:
+        if (
+            builder.has_optional_return_type
+            or self.code_model.options["models-mode"]
+            or self.code_model.generate_typeddict_only
+        ):
             deserialized = "deserialized"
         else:
             deserialized = f"cast({builder.response_type_annotation(async_mode=self.async_mode)}, deserialized)"
@@ -1329,7 +1338,9 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
 
     def error_map(self, builder: OperationType) -> list[str]:
         retval = ["error_map: MutableMapping = {"]
-        if builder.non_default_errors and self.code_model.options["models-mode"]:
+        if builder.non_default_errors and (
+            self.code_model.options["models-mode"] or self.code_model.generate_typeddict_only
+        ):
             # TODO: we should decide whether to add the build-in error map when there is a customized default error type
             if self._need_specific_error_map(401, builder):
                 retval.append("    401: ClientAuthenticationError,")
@@ -1693,7 +1704,7 @@ class _LROOperationSerializer(_OperationSerializer[LROOperationType]):
             if builder.lro_response.headers:
                 retval.append("    response_headers = {}")
             if (
-                not self.code_model.options["models-mode"]
+                (not self.code_model.options["models-mode"] and not self.code_model.generate_typeddict_only)
                 or self.code_model.options["models-mode"] == "dpg"
                 or builder.lro_response.headers
             ):

package/generator/build/lib/pygen/codegen/serializers/client_serializer.py

@@ -8,6 +8,7 @@ from typing import cast
 from . import utils
 from ..models import Client, ParameterMethodLocation, Parameter, ParameterLocation
 from .parameter_serializer import ParameterSerializer, PopKwargType
+from ..models.utils import escape_sphinx_field_name
 from ...utils import build_policies
 
 
@@ -61,13 +62,16 @@ class ClientSerializer:
         retval: list[str] = []
         operations_folder = ".aio.operations." if async_mode else ".operations."
         for og in [og for og in self.client.operation_groups if not og.is_mixin]:
-            retval.append(f":ivar {og.property_name}: {og.class_name} operations")
+            retval.append(f":ivar {escape_sphinx_field_name(og.property_name)}: {og.class_name} operations")
             property_type = f"{self.client.code_model.namespace}{operations_folder}{og.class_name}"
-            retval.append(f":vartype {og.property_name}: {property_type}")
+            retval.append(f":vartype {escape_sphinx_field_name(og.property_name)}: {property_type}")
         for param in self.client.parameters.method:
-            retval.append(f":{param.description_keyword} {param.client_name}: {param.description}")
             retval.append(
-                f":{param.docstring_type_keyword} {param.client_name}: {param.docstring_type(async_mode=async_mode)}"
+                f":{param.description_keyword} {escape_sphinx_field_name(param.client_name)}: {param.description}"
+            )
+            retval.append(
+                f":{param.docstring_type_keyword} {escape_sphinx_field_name(param.client_name)}: "
+                f"{param.docstring_type(async_mode=async_mode)}"
             )
         if self.client.has_public_lro_operations:
             retval.append(
@@ -315,7 +319,10 @@ class ConfigSerializer:
     def property_descriptions(self, async_mode: bool) -> list[str]:
         retval: list[str] = []
         for p in self.client.config.parameters.method:
-            retval.append(f":{p.description_keyword} {p.client_name}: {p.description}")
-            retval.append(f":{p.docstring_type_keyword} {p.client_name}: {p.docstring_type(async_mode=async_mode)}")
+            retval.append(f":{p.description_keyword} {escape_sphinx_field_name(p.client_name)}: {p.description}")
+            retval.append(
+                f":{p.docstring_type_keyword} {escape_sphinx_field_name(p.client_name)}: "
+                f"{p.docstring_type(async_mode=async_mode)}"
+            )
         retval.append('"""')
         return retval

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

@@ -23,7 +23,7 @@ from ..models.primitive_types import (
 )
 from .import_serializer import FileImportSerializer
 from .base_serializer import BaseSerializer
-from ..models.utils import NamespaceType, add_to_pylint_disable
+from ..models.utils import NamespaceType, add_to_pylint_disable, escape_sphinx_field_name
 
 
 def _get_xml_deserializer_name(prop: Property) -> Optional[str]:  # pylint: disable=too-many-return-statements
@@ -80,6 +80,9 @@ def _documentation_string(
     doc_name = (
         prop.wire_name if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE else prop.client_name
     )
+    # Escape names that Sphinx would otherwise misinterpret in the info field target
+    # (e.g. a wire name with a leading "@" such as "@search.facets").
+    doc_name = escape_sphinx_field_name(doc_name)
     sphinx_prefix = f":{description_keyword} {doc_name}:"
     description = prop.description(is_operation_file=False).replace("\\", "\\\\")
     retval.append(f"{sphinx_prefix} {description}" if description else sphinx_prefix)