@typespec/http-client-python 0.36.0 → 0.37.1

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

@@ -35,12 +35,33 @@ from ..models import (
 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[
@@ -1021,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,
@@ -1167,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(
@@ -1255,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 = [], [], []
@@ -1298,6 +1443,21 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
             else:
                 retval.extend(self.response_headers_and_deserialization(builder, builder.responses[0]))
                 retval.append("")
+        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"]
@@ -1323,38 +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"] 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,")
-            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(

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/types_serializer.py

@@ -243,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.
 
@@ -303,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(
@@ -329,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()}"
@@ -362,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