@typespec/http-client-python 0.35.1 → 0.37.0

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

@@ -32,15 +32,36 @@ 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 ..models.response import (
+    DEFAULT_SSE_EVENT_TYPE,
+    StreamingEvent,
+    get_streaming_event_discriminator,
+)
 from . import utils
 from ...utils import xml_serializable, json_serializable
 
 T = TypeVar("T")
 OrderedSet = dict[T, None]
 
+
+def _sse_event_data_expression(payload_content_type: Optional[str]) -> str:
+    """Return the generated expression that decodes an SSE event's UTF-8 data field."""
+    media_type = payload_content_type.split(";", 1)[0].strip().lower() if payload_content_type else None
+    is_json = media_type is None or media_type == "application/json" or media_type.endswith("+json")
+    return "json.loads(_event.data)" if is_json else "_event.data"
+
+
+def _sse_fallback_data_expression(events: list[StreamingEvent]) -> str:
+    """Decode fallback events only when every candidate payload is JSON."""
+    if not events:
+        return "_event.data"
+    expressions = {_sse_event_data_expression(event.payload_content_type) for event in events}
+    return "json.loads(_event.data)" if expressions == {"json.loads(_event.data)"} else "_event.data"
+
+
 BuilderType = TypeVar(
     "BuilderType",
     bound=Union[
@@ -311,16 +332,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 +735,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 +747,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 +866,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
             )
@@ -1018,7 +1042,19 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
         return retval
 
     def call_request_builder(self, builder: OperationType, is_paging: bool = False) -> list[str]:
-        return self._call_request_builder_helper(builder, builder.request_builder, is_paging=is_paging)
+        retval = self._call_request_builder_helper(builder, builder.request_builder, is_paging=is_paging)
+        if builder.has_structured_stream_response and any(
+            response.streaming_kind == "sse" for response in builder.responses
+        ):
+            retval.insert(0, '_last_event_id = kwargs.pop("last_event_id", None)')
+            retval.extend(
+                [
+                    "",
+                    "if _last_event_id is not None:",
+                    '    _request.headers["Last-Event-ID"] = _last_event_id',
+                ]
+            )
+        return retval
 
     def response_headers_and_deserialization(
         self,
@@ -1131,8 +1167,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"
@@ -1164,25 +1200,12 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
                                     "        )",
                                 ]
                             )
-                        # add build-in error type
-                        # TODO: we should decide whether need to this wrapper for customized error type
-                        status_code_error_map = {
-                            401: "ClientAuthenticationError",
-                            404: "ResourceNotFoundError",
-                            409: "ResourceExistsError",
-                            304: "ResourceNotModifiedError",
-                        }
-                        if status_code in status_code_error_map:
-                            retval.append(
-                                "        raise {}(response=response{}{})".format(
-                                    status_code_error_map[cast(int, status_code)],
-                                    error_model,
-                                    (", error_format=ARMErrorFormat" if self.code_model.options["azure-arm"] else ""),
-                                )
-                            )
-                            condition = "if"
-                        else:
-                            condition = "elif"
+                        # The dedicated azure-core error type for a standard status
+                        # code is raised by ``map_error`` via the error map, so here
+                        # we only deserialize the customized error body (used by the
+                        # generic ``HttpResponseError`` fallback for non-standard
+                        # status codes within the response).
+                        condition = "elif"
                 # ranged status code only exist in typespec and will not have multiple status codes
                 else:
                     retval.append(
@@ -1214,7 +1237,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:
@@ -1250,15 +1275,140 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
         )
         return retval
 
-    def handle_response(self, builder: OperationType) -> list[str]:
-        retval: list[str] = ["response = pipeline_response.http_response"]
-        retval.append("")
-        retval.extend(self.handle_error_response(builder))
+    # pylint: disable=too-many-statements
+    def handle_structured_stream_response(self, builder: OperationType) -> list[str]:
+        """Emit the body for an operation returning a structured (JSONL / SSE) stream.
+
+        Produces a per-event deserialization callback and returns a ``Stream`` /
+        ``AsyncStream`` wrapping the streamed HTTP response.
+        """
+        response = next(r for r in builder.responses if r.is_structured_stream)
+        item_annotation = response.stream_item_annotation(
+            is_operation_file=True, serialize_namespace=self.serialize_namespace
+        )
+        stream_class = response.stream_class_name(self.async_mode)  # type: ignore[attr-defined]
+        terminal_event = getattr(response, "terminal_event", None)
+        terminal_event_names = getattr(response, "terminal_event_names", [])
+        streaming_events = getattr(response, "streaming_events", [])
+        unnamed_events = [event for event in streaming_events if event.event_type is None]
+        unnamed_discriminator = get_streaming_event_discriminator(unnamed_events)
+        retval: list[str] = []
+        retval.append("def _callback(_http_response, _event):")
+        if response.streaming_kind == "sse":  # type: ignore[attr-defined]
+            named_events = [event for event in streaming_events if event.event_type is not None]
+
+            def emit_deserialized_event(event: StreamingEvent, indent: str) -> None:
+                event_item_type = event.payload_type
+                event_annotation = event_item_type.type_annotation(
+                    is_operation_file=True,
+                    serialize_namespace=self.serialize_namespace,
+                )
+                if self.code_model.options["models-mode"] == "msrest":
+                    serialization_type = event_item_type.serialization_type(
+                        serialize_namespace=self.serialize_namespace
+                    )
+                    retval.append(f"{indent}deserialized = self._deserialize(")
+                    retval.append(f"{indent}    '{serialization_type}',")
+                    retval.append(f"{indent}    _event_json")
+                    retval.append(f"{indent})")
+                else:
+                    retval.append(f"{indent}deserialized = _deserialize({event_annotation}, _event_json)")
+
+            def emit_typed_event(event: StreamingEvent, indent: str) -> None:
+                event_json = _sse_event_data_expression(event.payload_content_type)
+                retval.append(f"{indent}_event_json = {event_json}")
+                emit_deserialized_event(event, indent)
+
+            def emit_multiple_unnamed_events(events: list[StreamingEvent], indent: str) -> None:
+                event_json = _sse_fallback_data_expression(events)
+                retval.append(f"{indent}_event_json = {event_json}")
+                if unnamed_discriminator is None or event_json != "json.loads(_event.data)":
+                    retval.append(f"{indent}deserialized = _event_json")
+                    return
+                discriminator_name, variants = unnamed_discriminator
+                for index, (discriminator_value, event) in enumerate(variants):
+                    keyword = "if" if index == 0 else "elif"
+                    retval.append(
+                        f"{indent}{keyword} isinstance(_event_json, dict) "
+                        f"and _event_json.get({discriminator_name!r}) == {discriminator_value!r}:"
+                    )
+                    emit_deserialized_event(event, indent + "    ")
+                retval.append(f"{indent}else:")
+                retval.append(f"{indent}    deserialized = _event_json")
+
+            def emit_message_branch(keyword: str) -> None:
+                retval.append(f"    {keyword} _event.event == {DEFAULT_SSE_EVENT_TYPE!r}:")
+                if len(unnamed_events) == 1:
+                    emit_typed_event(unnamed_events[0], "        ")
+                else:
+                    emit_multiple_unnamed_events(unnamed_events, "        ")
+
+            if named_events:
+                for index, event in enumerate(named_events):
+                    event_type = event.event_type
+                    keyword = "if" if index == 0 else "elif"
+                    retval.append(f"    {keyword} _event.event == {event_type!r}:")
+                    emit_typed_event(event, "        ")
+                if unnamed_events:
+                    emit_message_branch("elif")
+            elif unnamed_events:
+                emit_message_branch("if")
+
+            if named_events or unnamed_events:
+                retval.append("    else:")
+                retval.append('        raise ValueError(f"Unknown SSE event type: {_event.event!r}")')
+            else:
+                retval.append('    raise ValueError(f"Unknown SSE event type: {_event.event!r}")')
+        else:
+            retval.append("    _event_json = _event.json()")
+            if self.code_model.options["models-mode"] == "msrest":
+                serialization_type = response.stream_item_type.serialization_type(
+                    serialize_namespace=self.serialize_namespace
+                )
+                retval.append("    deserialized = self._deserialize(")
+                retval.append(f"        '{serialization_type}',")
+                retval.append("        _event_json")
+                retval.append("    )")
+            else:
+                retval.append(f"    deserialized = _deserialize({item_annotation}, _event_json)")
+        retval.append("    return deserialized")
         retval.append("")
-        if builder.has_optional_return_type:
-            retval.append("deserialized = None")
-        if builder.any_response_has_headers:
-            retval.append("response_headers = {}")
+        stream_kwargs = ["response=response", "deserialization_callback=_callback"]
+        if terminal_event is not None:
+            stream_kwargs.append(f"terminal_event={terminal_event!r}")
+        if terminal_event_names:
+            stream_kwargs.append(f"terminal_event_names={terminal_event_names!r}")
+        unnamed_terminal_values = (
+            [discriminator_value for discriminator_value, event in unnamed_discriminator[1] if event.is_terminal]
+            if unnamed_discriminator is not None
+            else []
+        )
+        if unnamed_terminal_values:
+            discriminator_name = unnamed_discriminator[0]  # type: ignore[index]
+            retval.append("")
+            retval.append("def _is_terminal_event(_event):")
+            retval.append(f"    if _event.event != {DEFAULT_SSE_EVENT_TYPE!r}:")
+            retval.append("        return False")
+            retval.append("    try:")
+            retval.append("        _event_json = json.loads(_event.data)")
+            retval.append("    except (TypeError, ValueError):")
+            retval.append("        return False")
+            retval.append(
+                f"    return isinstance(_event_json, dict) "
+                f"and _event_json.get({discriminator_name!r}) in {unnamed_terminal_values!r}"
+            )
+            stream_kwargs.append("terminal_event_predicate=_is_terminal_event")
+        retval.append(
+            f"deserialized: {stream_class}[{item_annotation}] = "
+            f"{stream_class}({', '.join(stream_kwargs)})  # type: ignore"
+        )
+        retval.append("if cls:")
+        retval.append("    return cls(pipeline_response, deserialized, {})  # type: ignore")
+        retval.append("return deserialized")
+        return retval
+
+    def _handle_response_body(self, builder: OperationType) -> list[str]:
+        retval: list[str] = []
         if builder.has_response_body or builder.any_response_has_headers:  # pylint: disable=too-many-nested-blocks
             if len(builder.responses) > 1:
                 status_codes, res_headers, res_deserialization = [], [], []
@@ -1293,7 +1443,26 @@ 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"]:
+        return retval
+
+    def handle_response(self, builder: OperationType) -> list[str]:
+        retval: list[str] = ["response = pipeline_response.http_response"]
+        retval.append("")
+        retval.extend(self.handle_error_response(builder))
+        retval.append("")
+        if builder.has_structured_stream_response:
+            retval.extend(self.handle_structured_stream_response(builder))
+            return retval
+        if builder.has_optional_return_type:
+            retval.append("deserialized = None")
+        if builder.any_response_has_headers:
+            retval.append("response_headers = {}")
+        retval.extend(self._handle_response_body(builder))
+        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)"
@@ -1314,36 +1483,17 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
             retval.append("return 200 <= response.status_code <= 299")
         return retval
 
-    def _need_specific_error_map(self, code: int, builder: OperationType) -> bool:
-        for non_default_error in builder.non_default_errors:
-            # single status code
-            if code in non_default_error.status_codes:
-                return False
-            # ranged status code
-            if (
-                isinstance(non_default_error.status_codes[0], list)
-                and non_default_error.status_codes[0][0] <= code <= non_default_error.status_codes[0][1]
-            ):
-                return False
-        return True
-
     def error_map(self, builder: OperationType) -> list[str]:
         retval = ["error_map: MutableMapping = {"]
-        if builder.non_default_errors and self.code_model.options["models-mode"]:
-            # 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,")
-            if self._need_specific_error_map(404, builder):
-                retval.append("    404: ResourceNotFoundError,")
-            if self._need_specific_error_map(409, builder):
-                retval.append("    409: ResourceExistsError,")
-            if self._need_specific_error_map(304, builder):
-                retval.append("    304: ResourceNotModifiedError,")
-        else:
-            retval.append(
-                "    401: ClientAuthenticationError, 404: ResourceNotFoundError, 409: ResourceExistsError, "
-                "304: ResourceNotModifiedError"
-            )
+        # Always map the standard status codes to their dedicated azure-core error
+        # type so ``map_error`` raises the correct semantic error, even when a
+        # customized error model (single, ranged, or default) covers them. The
+        # customized error body is still deserialized in ``handle_error_response``
+        # for the generic ``HttpResponseError`` fallback.
+        retval.append(
+            "    401: ClientAuthenticationError, 404: ResourceNotFoundError, 409: ResourceExistsError, "
+            "304: ResourceNotModifiedError"
+        )
         retval.append("}")
         if builder.has_etag:
             retval.extend(
@@ -1693,7 +1843,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/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/pygen/codegen/serializers/general_serializer.py

@@ -318,6 +318,10 @@ class GeneralSerializer(BaseSerializer):
         template = self.env.get_template("model_base.py.jinja2")
         return template.render(code_model=self.code_model, file_import=FileImport(self.code_model))
 
+    def serialize_streaming_base_file(self) -> str:
+        template = self.env.get_template("streaming_base.py.jinja2")
+        return template.render(code_model=self.code_model, file_import=FileImport(self.code_model))
+
     def serialize_validation_file(self) -> str:
         template = self.env.get_template("validation.py.jinja2")
         return template.render(

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

@@ -84,6 +84,32 @@ class FileImportSerializer:
         if any(self.file_import.get_imports_from_section(TypingSection.TYPING)):
             self.file_import.add_submodule_import("typing", "TYPE_CHECKING", ImportType.STDLIB)
 
+    def _dedupe_typing_imports(self):
+        """Drop TYPE_CHECKING imports whose bound name is already imported at runtime.
+
+        A name imported in the regular (runtime) section is also available during type checking, so a
+        duplicate import under ``if TYPE_CHECKING:`` is redundant and triggers mypy's ``no-redef``
+        error. This can happen when the same symbol is imported from two different modules — e.g. a
+        cross-namespace enum imported at runtime from its ``_enums`` submodule and again for its
+        annotation from the public ``models`` package. The runtime import is sufficient.
+        """
+        regular_bound_names = {
+            (i.alias or i.submodule_name)
+            for i in self.file_import.get_imports_from_section(TypingSection.REGULAR)
+            if i.submodule_name
+        }
+        if not regular_bound_names:
+            return
+        self.file_import.imports = [
+            i
+            for i in self.file_import.imports
+            if not (
+                i.typing_section == TypingSection.TYPING
+                and i.submodule_name
+                and (i.alias or i.submodule_name) in regular_bound_names
+            )
+        ]
+
     def _add_sys_import_if_needed(self):
         all_imports = list(self.file_import.get_imports_from_section(TypingSection.REGULAR)) + list(
             self.file_import.get_imports_from_section(TypingSection.TYPING)
@@ -106,6 +132,7 @@ class FileImportSerializer:
         return "\n".join(declarations)
 
     def __str__(self) -> str:
+        self._dedupe_typing_imports()
         self._add_type_checking_import()
         self._add_sys_import_if_needed()
         regular_imports = ""

package/generator/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)

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

@@ -103,21 +103,16 @@ class TypesSerializer(BaseSerializer):
 
         TypedDicts (and discriminated-base union aliases) in ``types.py`` describe request-body
         (*input*) shapes. Output-only models already render as classes in ``models/`` and are
-        referenced via ``_models.*``, so a response-only model that nothing input references would be
-        dead code. A model seeds the input surface when it is:
-
-        * a typeddict copy (``base == "typeddict"``) — these only exist as input body overloads
-          (their ``usage`` may carry ``Spread``/``Json`` rather than ``Input``), or
-        * ``is_typed_dict_only`` — includes every model in full ``typeddict`` mode (responses too),
-          and input-only anonymous bodies, or
-        * used as input (``is_usage_input``) — e.g. a model shared between request and response.
+        referenced via ``_models.*``, so a model that no operation references through ``types.py``
+        would be dead code. TypedDict copies and models in full TypedDict mode volunteer through
+        ``is_used_in_operations_via_types``.
 
         The full set rendered in types.py is the transitive closure of these seeds over base
         classes, discriminated subtypes and property types (see :attr:`_types_file_model_names`), so
         an output-only model that *is* referenced by an input model (e.g. ARM ``SystemData`` on
         ``Resource``) is still rendered.
         """
-        return m.base == "typeddict" or m.is_typed_dict_only or m.is_usage_input
+        return m.is_used_in_operations_via_types
 
     @staticmethod
     def _iter_referenced_models(base_type: Any):
@@ -248,6 +243,39 @@ class TypesSerializer(BaseSerializer):
         """Whether any property wire_name is a Python keyword or requires functional TypedDict form."""
         return any(keyword.iskeyword(p.wire_name) or not p.wire_name.isidentifier() for p in model.properties)
 
+    @staticmethod
+    def needs_flat_typeddict(model: ModelType) -> bool:
+        """Whether a TypedDict must be emitted in flat (non-inheriting) form.
+
+        PEP 589 forbids changing an inherited TypedDict field's requiredness in a subclass. When a
+        child redeclares an inherited field with a different requiredness (e.g. the parent renders it
+        as optional via ``total=False`` while the child needs ``Required[...]``), subclassing would
+        emit an illegal ``Overwriting TypedDict field ... while extending`` construct. Such models are
+        instead rendered as a flat TypedDict that lists every field (inherited + own) directly.
+
+        Models with keyword wire_names already flatten all fields via the functional form, so they
+        never hit this path.
+        """
+        if TypesSerializer.has_keyword_wire_names(model):
+            return False
+        non_discriminated_parents = [p for p in model.parents if not p.discriminated_subtypes]
+        if not non_discriminated_parents:
+            return False
+        for parent in non_discriminated_parents:
+            for parent_prop in parent.properties:
+                child_prop = next(
+                    (p for p in model.properties if p.client_name == parent_prop.client_name),
+                    None,
+                )
+                if child_prop is None or child_prop is parent_prop:
+                    # Not overridden by the child (same object is reused when inherited unchanged).
+                    continue
+                parent_required = not (parent_prop.optional or parent_prop.client_default_value is not None)
+                child_required = not (child_prop.optional or child_prop.client_default_value is not None)
+                if parent_required != child_required:
+                    return True
+        return False
+
     def get_shadowed_builtins(self, model: ModelType) -> frozenset[str]:
         """Return the set of builtin type names shadowed by property wire_names in this model.
 
@@ -308,7 +336,11 @@ class TypesSerializer(BaseSerializer):
                 if self.get_shadowed_builtins(model):
                     needs_builtins = True
                 for parent in model.parents:
-                    if parent.client_namespace != model.client_namespace and not parent.discriminated_subtypes:
+                    if (
+                        parent.client_namespace != model.client_namespace
+                        and not parent.discriminated_subtypes
+                        and not self.needs_flat_typeddict(model)
+                    ):
                         # Import parent class from sibling namespace's types module
                         file_import.add_submodule_import(
                             self.code_model.get_relative_import_path(
@@ -334,7 +366,7 @@ class TypesSerializer(BaseSerializer):
         if self.has_keyword_wire_names(model):
             return ""  # functional form is rendered separately
         non_discriminated_parents = [p for p in model.parents if not p.discriminated_subtypes]
-        if non_discriminated_parents:
+        if non_discriminated_parents and not self.needs_flat_typeddict(model):
             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()}"
@@ -367,7 +399,7 @@ class TypesSerializer(BaseSerializer):
         if TypesSerializer.has_keyword_wire_names(model):
             return []  # functional form handles all properties
         non_discriminated_parents = [p for p in model.parents if not p.discriminated_subtypes]
-        if non_discriminated_parents:
+        if non_discriminated_parents and not TypesSerializer.needs_flat_typeddict(model):
             parent_properties = [p for bm in non_discriminated_parents for p in bm.properties]
             return [
                 p