@typespec/http-client-python 0.36.0 → 0.37.1

package/generator/build/lib/pygen/codegen/templates/streaming_base.py.jinja2

@@ -0,0 +1,767 @@
+# coding=utf-8
+{% if code_model.license_header %}
+{{ code_model.license_header }}
+{% endif %}
+# pylint: disable=line-too-long,useless-suppression,unnecessary-ellipsis
+# --------------------------------------------------------------------------
+# This file is vendored from the core streaming runtime
+# ({{ code_model.core_library }}.streaming). It provides the Stream / AsyncStream
+# helpers (plus the JSONL / SSE decoders and event types) used by generated
+# structured-streaming operations, so the generated package does not take a hard
+# dependency on a core runtime that ships the streaming helpers. Do not edit by hand.
+# --------------------------------------------------------------------------
+import codecs
+import json
+from contextlib import aclosing
+from types import TracebackType
+from typing import (
+    Any,
+    AsyncGenerator,
+    AsyncIterator,
+    Callable,
+    Generator,
+    Iterator,
+    List,
+    Optional,
+    Protocol,
+    Sequence,
+    Type,
+    TypeVar,
+    cast,
+    runtime_checkable,
+)
+
+from typing_extensions import Self
+
+from {{ code_model.core_library }}.rest import AsyncHttpResponse, HttpResponse
+
+DecodedType = TypeVar("DecodedType")
+ReturnType_co = TypeVar("ReturnType_co", covariant=True)
+T_co = TypeVar("T_co", covariant=True)
+
+
+@runtime_checkable
+class StreamDecoder(Protocol[T_co]):
+    """Protocol for stream decoders."""
+
+    def iter_events(self, iter_bytes: Iterator[bytes]) -> Iterator[T_co]:
+        """Iterate over events from a byte iterator.
+
+        :param iter_bytes: An iterator of byte chunks.
+        :type iter_bytes: Iterator[bytes]
+        :return: An iterator of decoded data.
+        :rtype: Iterator[DecodedType_co]
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncStreamDecoder(Protocol[T_co]):
+    """Protocol for async stream decoders."""
+
+    # Why this isn't async def: https://mypy.readthedocs.io/en/stable/more_types.html#asynchronous-iterators
+    def aiter_events(self, iter_bytes: AsyncIterator[bytes]) -> AsyncIterator[T_co]:
+        """Asynchronously iterate over events from a byte iterator.
+
+        :param iter_bytes: An asynchronous iterator of byte chunks.
+        :type iter_bytes: AsyncIterator[bytes]
+        :return: An asynchronous iterator of decoded data.
+        :rtype: AsyncIterator[DecodedType_co]
+        """
+        ...
+
+
+class JSONLEvent:
+    """A single JSON Lines (JSONL) event.
+
+    :ivar data: The raw JSONL record.
+    :vartype data: str or None
+    :keyword data: The raw JSONL record.
+    :paramtype data: str or None
+    """
+
+    def __init__(
+        self,
+        *,
+        data: Optional[str] = None,
+    ) -> None:
+        self.data = data
+
+    def json(self) -> Any:
+        """Parse the event data as JSON.
+
+        :return: The parsed JSON value.
+        :rtype: Any
+        """
+        return json.loads(cast(str, self.data))
+
+
+class _JSONLLineFramer:
+    """Incremental JSONL line framer with linear-time behavior.
+
+    JSONL records are separated only by ``"\\n"`` (tolerating ``"\\r\\n"``). Unlike
+    ``str.splitlines()``, other Unicode boundaries (``\\v``, ``\\f``, ``\\x1c``-``\\x1e``,
+    ``\\x85``, ``\\u2028``, ``\\u2029``) are preserved because they are valid inside a JSONL
+    record's string value.
+
+    Rather than re-concatenating and re-splitting the whole pending record on every network chunk
+    (which is O(n^2) for a single long record fragmented across many chunks), the unfinished record
+    is held as a list of fragments and joined only when a terminator arrives (or at EOF). Only the
+    newly decoded text is scanned per chunk, giving O(total) behavior.
+    """
+
+    def __init__(self) -> None:
+        # Fragments of the current, not-yet-terminated record. Never contains a "\n".
+        self._parts: List[str] = []
+
+    def push(self, text: str) -> List[str]:
+        """Feed newly decoded text and return any completed records.
+
+        :param text: Newly decoded text from a single chunk.
+        :type text: str
+        :return: Completed records produced by this chunk (may be empty).
+        :rtype: list[str]
+        """
+        if not text:
+            return []
+
+        segments = text.split("\n")
+        # Fast path: no line terminator, so this is a continuation of the current record. Stash the
+        # fragment without joining or rescanning the accumulated tail.
+        if len(segments) == 1:
+            self._parts.append(text)
+            return []
+
+        first = "".join(self._parts) + segments[0]
+        # All but the final segment are complete records (terminated by "\n"). Strip a trailing "\r"
+        # to tolerate "\r\n" line endings.
+        completed = [line[:-1] if line.endswith("\r") else line for line in [first, *segments[1:-1]]]
+        self._parts = [segments[-1]]
+        return completed
+
+    def flush(self, extra: str = "") -> List[str]:
+        """Return the final unterminated record, if any, at end of stream.
+
+        :param extra: Trailing text from finalizing the incremental decoder.
+        :type extra: str
+        :return: The final record, if non-empty.
+        :rtype: list[str]
+        """
+        tail = "".join(self._parts) + extra
+        self._parts = []
+        if not tail:
+            return []
+        return [tail[:-1] if tail.endswith("\r") else tail]
+
+
+def iter_lines(iter_bytes: Iterator[bytes]) -> Iterator[str]:
+    """Iterate over lines from a byte iterator.
+
+    :param iter_bytes: An iterator of byte chunks.
+    :type iter_bytes: Iterator[bytes]
+    :rtype: Iterator[str]
+    :return: An iterator of lines.
+    """
+    decoder = codecs.getincrementaldecoder("utf-8")()
+    framer = _JSONLLineFramer()
+
+    for chunk in iter_bytes:
+        yield from framer.push(decoder.decode(chunk))
+
+    yield from framer.flush(decoder.decode(b"", final=True))
+
+
+async def aiter_lines(iter_bytes: AsyncIterator[bytes]) -> AsyncGenerator[str, None]:
+    """Iterate over lines from a byte iterator.
+
+    :param iter_bytes: An iterator of byte chunks.
+    :type iter_bytes: Iterator[bytes]
+    :rtype: Iterator[str]
+    :return: An iterator of lines.
+    """
+    decoder = codecs.getincrementaldecoder("utf-8")()
+    framer = _JSONLLineFramer()
+
+    try:
+        async for chunk in iter_bytes:
+            for line in framer.push(decoder.decode(chunk)):
+                yield line
+    finally:
+        aclose = getattr(iter_bytes, "aclose", None)
+        if aclose is not None:
+            await aclose()
+
+    for line in framer.flush(decoder.decode(b"", final=True)):
+        yield line
+
+
+class JSONLDecoder:
+    """Decoder for JSON Lines (JSONL) format. https://jsonlines.org/"""
+
+    def iter_events(self, iter_bytes: Iterator[bytes]) -> Iterator[JSONLEvent]:
+        """Iterate over JSONL events from a byte iterator.
+
+        :param iter_bytes: An iterator of byte chunks.
+        :type iter_bytes: Iterator[bytes]
+        :rtype: Iterator[JSONLEvent]
+        :return: An iterator of JSONL events.
+        """
+
+        yield from (JSONLEvent(data=line) for line in iter_lines(iter_bytes))
+
+
+class AsyncJSONLDecoder:
+    """Asynchronous decoder for JSON Lines (JSONL) format. https://jsonlines.org/"""
+
+    # pylint: disable=invalid-overridden-method
+    async def aiter_events(self, iter_bytes: AsyncIterator[bytes]) -> AsyncIterator[JSONLEvent]:
+        """Asynchronously iterate over JSONL events from a byte iterator.
+
+        :param iter_bytes: An asynchronous iterator of byte chunks.
+        :type iter_bytes: AsyncIterator[bytes]
+        :rtype: AsyncIterator[JSONLEvent]
+        :return: An asynchronous iterator of JSONL events.
+        """
+
+        async with aclosing(aiter_lines(iter_bytes)) as lines:
+            async for line in lines:
+                yield JSONLEvent(data=line)
+
+
+class ServerSentEvent:
+    """A single Server-Sent Event (SSE).
+
+    https://html.spec.whatwg.org/multipage/server-sent-events.html
+
+    :ivar event: The event type. Defaults to ``"message"`` when the stream does not
+        specify one.
+    :vartype event: str
+    :ivar data: The event payload. Multiple ``data`` lines are joined with ``"\\n"``.
+        Left as a raw string; the caller is responsible for any further parsing.
+    :vartype data: str
+    :ivar id: The last event ID. Defaults to an empty string until the stream
+        provides one.
+    :vartype id: str
+    :ivar retry: The reconnection time in milliseconds, if the stream provided one.
+    :vartype retry: int or None
+    :keyword event: The event type. Defaults to ``"message"`` when the stream does not
+        specify one.
+    :paramtype event: str
+    :keyword data: The event payload. Multiple ``data`` lines are joined with ``"\\n"``.
+        Left as a raw string; the caller is responsible for any further parsing.
+    :paramtype data: str
+    :keyword id: The last event ID. Defaults to an empty string until the stream
+        provides one.
+    :paramtype id: str
+    :keyword retry: The reconnection time in milliseconds, if the stream provided one.
+    :paramtype retry: int or None
+    """
+
+    def __init__(
+        self,
+        *,
+        event: str = "message",
+        data: str = "",
+        id: str = "",  # pylint: disable=redefined-builtin
+        retry: Optional[int] = None,
+    ) -> None:
+        self.event = event
+        self.data = data
+        self.id = id
+        self.retry = retry
+
+    def __repr__(self) -> str:
+        return f"ServerSentEvent(event={self.event!r}, data={self.data!r}, " f"id={self.id!r}, retry={self.retry!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ServerSentEvent):
+            return NotImplemented
+        return (self.event, self.data, self.id, self.retry) == (
+            other.event,
+            other.data,
+            other.id,
+            other.retry,
+        )
+
+
+class _SSELineFramer:
+    """Incremental SSE line framer with linear-time behavior.
+
+    Per the SSE spec, lines may be separated by ``"\\r\\n"``, ``"\\r"`` or ``"\\n"``. A lone trailing
+    ``"\\r"`` at a chunk boundary is ambiguous (it may be the first half of a ``"\\r\\n"``) and its
+    resolution is deferred until the next chunk (or EOF).
+
+    Rather than re-concatenating and re-scanning the whole pending line on every network chunk
+    (which is O(n^2) for a single long line fragmented across many chunks), the unfinished line is
+    held as a list of fragments and joined only when a terminator arrives (or at EOF). Only the
+    newly decoded text is scanned per chunk, giving O(total) behavior.
+    """
+
+    def __init__(self) -> None:
+        # Fragments of the current, not-yet-terminated line. Never contains a separator.
+        self._parts: List[str] = []
+        # True when the previous chunk ended with a lone "\r" whose "\r\n" status is still unknown.
+        self._pending_cr = False
+
+    def _emit_current(self) -> str:
+        line = "".join(self._parts)
+        self._parts = []
+        return line
+
+    def push(self, text: str) -> List[str]:
+        """Feed newly decoded text and return any completed lines.
+
+        :param text: Newly decoded text from a single chunk.
+        :type text: str
+        :return: Completed lines (separators stripped) produced by this chunk.
+        :rtype: list[str]
+        """
+        if not text:
+            return []
+
+        out: List[str] = []
+        if self._pending_cr:
+            # The deferred "\r" terminates the current line now that more data is available.
+            out.append(self._emit_current())
+            self._pending_cr = False
+            # A leading "\n" is the second half of that "\r\n" pair: consume it.
+            if text[:1] == "\n":
+                text = text[1:]
+
+        n = len(text)
+        start = 0
+        i = 0
+        while i < n:
+            char = text[i]
+            if char == "\n":
+                self._parts.append(text[start:i])
+                out.append(self._emit_current())
+                i += 1
+                start = i
+            elif char == "\r":
+                if i + 1 < n:
+                    self._parts.append(text[start:i])
+                    out.append(self._emit_current())
+                    i += 2 if text[i + 1] == "\n" else 1
+                    start = i
+                else:
+                    # Trailing lone "\r": defer resolution until the next chunk.
+                    self._parts.append(text[start:i])
+                    self._pending_cr = True
+                    start = n
+                    break
+            else:
+                i += 1
+
+        if start < n:
+            self._parts.append(text[start:n])
+        return out
+
+    def flush(self, extra: str = "") -> List[str]:
+        """Return any remaining lines at end of stream.
+
+        A lone trailing ``"\\r"`` is treated as a terminator (its ``"\\r\\n"`` half never arrives),
+        and a non-empty final unterminated line is emitted; an empty tail is not, so no blank line
+        (and therefore no spurious event) is invented at EOF.
+
+        :param extra: Trailing text from finalizing the incremental decoder.
+        :type extra: str
+        :return: The remaining lines, if any.
+        :rtype: list[str]
+        """
+        out: List[str] = []
+        if self._pending_cr:
+            out.append(self._emit_current())
+            self._pending_cr = False
+            if extra[:1] == "\n":
+                extra = extra[1:]
+
+        if extra:
+            out.extend(self.push(extra))
+
+        if self._pending_cr:
+            # 'extra' ended in a lone "\r": at EOF it is a terminator; emit the preceding content.
+            out.append(self._emit_current())
+            self._pending_cr = False
+        else:
+            tail = self._emit_current()
+            if tail:
+                out.append(tail)
+        return out
+
+
+def _iter_sse_lines(iter_bytes: Iterator[bytes]) -> Iterator[str]:
+    """Iterate over SSE lines (line separators stripped) from a byte iterator.
+
+    :param iter_bytes: An iterator of byte chunks.
+    :type iter_bytes: Iterator[bytes]
+    :rtype: Iterator[str]
+    :return: An iterator of decoded lines.
+    """
+    # SSE is always UTF-8 (WHATWG spec). Use utf-8-sig to drop one leading BOM and
+    # errors="replace" so invalid byte sequences become U+FFFD instead of crashing.
+    decoder = codecs.getincrementaldecoder("utf-8-sig")(errors="replace")
+    framer = _SSELineFramer()
+
+    for chunk in iter_bytes:
+        yield from framer.push(decoder.decode(chunk))
+
+    yield from framer.flush(decoder.decode(b"", final=True))
+
+
+async def _aiter_sse_lines(iter_bytes: AsyncIterator[bytes]) -> AsyncGenerator[str, None]:
+    """Asynchronously iterate over SSE lines (separators stripped) from a byte iterator.
+
+    :param iter_bytes: An asynchronous iterator of byte chunks.
+    :type iter_bytes: AsyncIterator[bytes]
+    :rtype: AsyncIterator[str]
+    :return: An asynchronous iterator of decoded lines.
+    """
+    # SSE is always UTF-8 (WHATWG spec). Use utf-8-sig to drop one leading BOM and
+    # errors="replace" so invalid byte sequences become U+FFFD instead of crashing.
+    decoder = codecs.getincrementaldecoder("utf-8-sig")(errors="replace")
+    framer = _SSELineFramer()
+
+    try:
+        async for chunk in iter_bytes:
+            for line in framer.push(decoder.decode(chunk)):
+                yield line
+    finally:
+        aclose = getattr(iter_bytes, "aclose", None)
+        if aclose is not None:
+            await aclose()
+
+    for line in framer.flush(decoder.decode(b"", final=True)):
+        yield line
+
+
+class _SSEEventBuilder:
+    """Accumulates SSE field lines and builds :class:`ServerSentEvent` instances."""
+
+    def __init__(self) -> None:
+        self._data: List[str] = []
+        self._event_type = ""
+        self._last_id = ""
+        self._retry: Optional[int] = None
+
+    def add_line(self, line: str) -> Optional[ServerSentEvent]:
+        """Process a single SSE line, dispatching an event on a blank line.
+
+        :param line: A single SSE line with its terminator already stripped.
+        :type line: str
+        :return: A :class:`ServerSentEvent` when ``line`` is blank and an event is
+            pending, otherwise ``None``.
+        :rtype: ServerSentEvent or None
+        """
+        if line == "":
+            return self._dispatch()
+        if line.startswith(":"):
+            # Comment line, ignored.
+            return None
+
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+
+        if field == "event":
+            self._event_type = value
+        elif field == "data":
+            self._data.append(value)
+        elif field == "id":
+            if "\x00" not in value:
+                self._last_id = value
+        elif field == "retry":
+            if value.isascii() and value.isdigit():
+                try:
+                    self._retry = int(value)
+                except ValueError:
+                    # All ASCII digits but too long for int() (CPython's int-string
+                    # conversion limit). Ignore rather than crashing the stream.
+                    pass
+        # Unknown fields are ignored per spec.
+        return None
+
+    def _dispatch(self) -> Optional[ServerSentEvent]:
+        if not self._data:
+            # No data accumulated: reset and dispatch nothing.
+            self._event_type = ""
+            return None
+        event = ServerSentEvent(
+            event=self._event_type or "message",
+            data="\n".join(self._data),
+            id=self._last_id,
+            retry=self._retry,
+        )
+        self._data = []
+        self._event_type = ""
+        return event
+
+
+class SSEDecoder:
+    """Decoder for Server-Sent Events (SSE).
+
+    https://html.spec.whatwg.org/multipage/server-sent-events.html
+    """
+
+    def iter_events(self, iter_bytes: Iterator[bytes]) -> Iterator[ServerSentEvent]:
+        """Iterate over SSE events from a byte iterator.
+
+        :param iter_bytes: An iterator of byte chunks.
+        :type iter_bytes: Iterator[bytes]
+        :rtype: Iterator[ServerSentEvent]
+        :return: An iterator of server-sent events.
+        """
+        builder = _SSEEventBuilder()
+        for line in _iter_sse_lines(iter_bytes):
+            event = builder.add_line(line)
+            if event is not None:
+                yield event
+
+
+class AsyncSSEDecoder:
+    """Asynchronous decoder for Server-Sent Events (SSE).
+
+    https://html.spec.whatwg.org/multipage/server-sent-events.html
+    """
+
+    # pylint: disable=invalid-overridden-method
+    async def aiter_events(self, iter_bytes: AsyncIterator[bytes]) -> AsyncIterator[ServerSentEvent]:
+        """Asynchronously iterate over SSE events from a byte iterator.
+
+        :param iter_bytes: An asynchronous iterator of byte chunks.
+        :type iter_bytes: AsyncIterator[bytes]
+        :rtype: AsyncIterator[ServerSentEvent]
+        :return: An asynchronous iterator of server-sent events.
+        """
+        builder = _SSEEventBuilder()
+        async with aclosing(_aiter_sse_lines(iter_bytes)) as lines:
+            async for line in lines:
+                event = builder.add_line(line)
+                if event is not None:
+                    yield event
+
+
+class Stream(Iterator[ReturnType_co]):
+    """Stream class for consuming a decoded event stream (e.g. JSONL or SSE).
+
+    :keyword response: The response object.
+    :paramtype response: ~{{ code_model.core_library }}.rest.HttpResponse
+    :keyword decoder: A decoder to use for the stream. If omitted, the decoder is
+        inferred from the response ``Content-Type`` header.
+    :paramtype decoder: StreamDecoder
+    :keyword deserialization_callback: A callback that takes the response and the decoded event and
+        returns a deserialized object.
+    :paramtype deserialization_callback: Callable[[~{{ code_model.core_library }}.rest.HttpResponse, Any], ReturnType]
+    :keyword terminal_event: Optional event ``data`` value that terminates the stream (e.g.
+        ``"[DONE]"``). When an event's ``data`` equals this value, iteration stops and the
+        event is not passed to ``deserialization_callback``.
+    :paramtype terminal_event: str or None
+    :keyword terminal_event_names: Optional event names (the SSE ``event`` field) that terminate
+        the stream. Unlike ``terminal_event``, such an event carries a payload: it is passed to
+        ``deserialization_callback`` and yielded, and iteration stops immediately afterwards.
+    :paramtype terminal_event_names: ~typing.Sequence[str] or None
+    :keyword terminal_event_predicate: Optional predicate that identifies a payload-bearing
+        terminal event. The event is yielded before iteration stops.
+    :paramtype terminal_event_predicate: Callable[[Any], bool] or None
+    """
+
+    def __init__(
+        self,
+        *,
+        response: HttpResponse,
+        deserialization_callback: Callable[[HttpResponse, DecodedType], ReturnType_co],
+        decoder: Optional[StreamDecoder[DecodedType]] = None,
+        terminal_event: Optional[str] = None,
+        terminal_event_names: Optional[Sequence[str]] = None,
+        terminal_event_predicate: Optional[Callable[[DecodedType], bool]] = None,
+    ) -> None:
+        self._response = response
+        content_type = response.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+        self._decoder: StreamDecoder[Any] = (
+            decoder if decoder is not None else (SSEDecoder() if content_type == "text/event-stream" else JSONLDecoder())
+        )
+        self._deserialization_callback = deserialization_callback
+        self._terminal_event = terminal_event
+        self._terminal_event_names = frozenset(terminal_event_names or ())
+        self._terminal_event_predicate = terminal_event_predicate
+        self._last_event_id: Optional[str] = None
+        self._retry: Optional[int] = None
+        self._iterator = self._iter_results()
+
+    @property
+    def last_event_id(self) -> Optional[str]:
+        """The most recently received SSE event ID, if one was provided."""
+        return self._last_event_id
+
+    @property
+    def retry(self) -> Optional[int]:
+        """The most recently received valid SSE retry value, if one was provided."""
+        return self._retry
+
+    def __next__(self) -> ReturnType_co:
+        return self._iterator.__next__()
+
+    def __iter__(self) -> Self:
+        return self
+
+    def _iter_results(self) -> Generator[ReturnType_co, None, None]:
+        try:
+            for event in self._decoder.iter_events(self._response.iter_bytes()):
+                event_id = getattr(event, "id", None)
+                if event_id is not None:
+                    self._last_event_id = event_id
+                event_retry = getattr(event, "retry", None)
+                if event_retry is not None:
+                    self._retry = event_retry
+                if self._terminal_event is not None and getattr(event, "data", None) == self._terminal_event:
+                    break
+                result = self._deserialization_callback(self._response, event)
+                yield result
+                if (
+                    self._terminal_event_names
+                    and getattr(event, "event", None) in self._terminal_event_names
+                ) or (
+                    self._terminal_event_predicate is not None
+                    and self._terminal_event_predicate(event)
+                ):
+                    break
+        finally:
+            self._response.close()
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]] = None,
+        exc_value: Optional[BaseException] = None,
+        traceback: Optional[TracebackType] = None,
+    ) -> None:
+        self.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def close(self) -> None:
+        try:
+            self._iterator.close()
+        finally:
+            self._response.close()
+
+
+class AsyncStream(AsyncIterator[ReturnType_co]):
+    """AsyncStream class for asynchronously consuming a decoded event stream (e.g. JSONL or SSE).
+
+    :keyword response: The response object.
+    :paramtype response: ~{{ code_model.core_library }}.rest.AsyncHttpResponse
+    :keyword decoder: A decoder to use for the stream. If omitted, the decoder is
+        inferred from the response ``Content-Type`` header.
+    :paramtype decoder: AsyncStreamDecoder
+    :keyword deserialization_callback: A callback that takes the response and the decoded event and
+        returns a deserialized object.
+    :paramtype deserialization_callback: Callable[[~{{ code_model.core_library }}.rest.AsyncHttpResponse, Any], ReturnType]
+    :keyword terminal_event: Optional event ``data`` value that terminates the stream (e.g.
+        ``"[DONE]"``). When an event's ``data`` equals this value, iteration stops and the
+        event is not passed to ``deserialization_callback``.
+    :paramtype terminal_event: str or None
+    :keyword terminal_event_names: Optional event names (the SSE ``event`` field) that terminate
+        the stream. Unlike ``terminal_event``, such an event carries a payload: it is passed to
+        ``deserialization_callback`` and yielded, and iteration stops immediately afterwards.
+    :paramtype terminal_event_names: ~typing.Sequence[str] or None
+    :keyword terminal_event_predicate: Optional predicate that identifies a payload-bearing
+        terminal event. The event is yielded before iteration stops.
+    :paramtype terminal_event_predicate: Callable[[Any], bool] or None
+    """
+
+    def __init__(
+        self,
+        *,
+        response: AsyncHttpResponse,
+        deserialization_callback: Callable[[AsyncHttpResponse, DecodedType], ReturnType_co],
+        decoder: Optional[AsyncStreamDecoder[DecodedType]] = None,
+        terminal_event: Optional[str] = None,
+        terminal_event_names: Optional[Sequence[str]] = None,
+        terminal_event_predicate: Optional[Callable[[DecodedType], bool]] = None,
+    ) -> None:
+        self._response = response
+        content_type = response.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+        self._decoder: AsyncStreamDecoder[Any] = (
+            decoder
+            if decoder is not None
+            else (AsyncSSEDecoder() if content_type == "text/event-stream" else AsyncJSONLDecoder())
+        )
+        self._deserialization_callback = deserialization_callback
+        self._terminal_event = terminal_event
+        self._terminal_event_names = frozenset(terminal_event_names or ())
+        self._terminal_event_predicate = terminal_event_predicate
+        self._last_event_id: Optional[str] = None
+        self._retry: Optional[int] = None
+        self._iterator = self._iter_results()
+
+    @property
+    def last_event_id(self) -> Optional[str]:
+        """The most recently received SSE event ID, if one was provided."""
+        return self._last_event_id
+
+    @property
+    def retry(self) -> Optional[int]:
+        """The most recently received valid SSE retry value, if one was provided."""
+        return self._retry
+
+    async def __anext__(self) -> ReturnType_co:
+        return await self._iterator.__anext__()
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def _iter_results(self) -> AsyncGenerator[ReturnType_co, None]:
+        events = self._decoder.aiter_events(self._response.iter_bytes())
+        try:
+            async for event in events:
+                event_id = getattr(event, "id", None)
+                if event_id is not None:
+                    self._last_event_id = event_id
+                event_retry = getattr(event, "retry", None)
+                if event_retry is not None:
+                    self._retry = event_retry
+                if self._terminal_event is not None and getattr(event, "data", None) == self._terminal_event:
+                    break
+                result = self._deserialization_callback(self._response, event)
+                yield result
+                if (
+                    self._terminal_event_names
+                    and getattr(event, "event", None) in self._terminal_event_names
+                ) or (
+                    self._terminal_event_predicate is not None
+                    and self._terminal_event_predicate(event)
+                ):
+                    break
+        finally:
+            try:
+                aclose = getattr(events, "aclose", None)
+                if aclose is not None:
+                    await aclose()
+            finally:
+                await self._response.close()
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]] = None,
+        exc_value: Optional[BaseException] = None,
+        traceback: Optional[TracebackType] = None,
+    ) -> None:
+        await self.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def close(self) -> None:
+        try:
+            await self._iterator.aclose()
+        finally:
+            await self._response.close()
+
+
+__all__ = [
+    "Stream",
+    "AsyncStream",
+    "JSONLEvent",
+    "ServerSentEvent",
+]