axio-sse 0.11.0__py3-none-any.whl

axio_sse/__init__.py

@@ -0,0 +1,43 @@
+"""Read ``text/event-stream``: a decoder you feed, and a reader for what its payloads mean.
+
+``Decoder`` is the format and nothing else. Feed it chunks — bytes or text, cut anywhere — and take
+the events they completed. It is synchronous and holds no connection, so every wire case is
+testable without a loop, and a thread or a non-asyncio caller can drive it. ``events()`` and
+``payloads()`` are the async skin over it: chunks in, ``Event`` or ``Payload`` out. Chunks must
+carry their line terminators, so an iterator of lines will not do.
+
+A stream whose events are all one shape needs nothing above ``payloads()``: every JSON object the
+stream carries, and nothing more to learn. ``until`` names the one data payload that closes the
+stream — ``until="[DONE]"`` — so a sentinel that is not JSON never reaches a caller.
+
+A stream that says what each event is subclasses ``Reader`` and writes one ``@on(...)`` method per
+event. ``by`` on the class line names the payload key that holds the name, or ``EVENT_NAME`` for
+the format's own ``event:`` field. That class body is one endpoint's whole vocabulary, the events
+it deliberately drops included. An event no method claims is skipped and logged at DEBUG. It
+raises ``UnknownEvent`` when the caller reads with ``strict=True``, which is how a test fails on
+the day the provider sends something new.
+
+This module knows nothing about HTTP and imports no client.
+"""
+
+from .decoder import Decoder, EventTooLarge
+from .event import Event, MalformedPayload, Payload
+from .reader import EVENT_NAME, Handled, Reader, UnknownEvent, on
+from .stream import events, payloads
+from .wire import Wire
+
+__all__ = [
+    "EVENT_NAME",
+    "Decoder",
+    "Event",
+    "EventTooLarge",
+    "Handled",
+    "MalformedPayload",
+    "Payload",
+    "Reader",
+    "UnknownEvent",
+    "Wire",
+    "events",
+    "on",
+    "payloads",
+]

axio_sse/decoder.py

@@ -0,0 +1,263 @@
+"""The format as a state machine, with no I/O and no loop."""
+
+from __future__ import annotations
+
+import codecs
+from typing import Final
+
+from .event import Event
+
+#: The only line endings the format allows. ``str.splitlines`` breaks on more than these.
+#: ``_take`` hard-codes them; changing this tuple alone changes nothing.
+ENDINGS: Final = ("\r\n", "\n", "\r")
+
+#: How large a held piece grows before the next chunk starts a new one. Bounds the number of
+#: string headers a fragmented event costs, at no measurable cost to an ordinary read buffer.
+_MIN_PIECE = 4096
+
+#: How long a ``retry:`` value may be. ``str.isdigit`` is true for 128 characters ``int()``
+#: refuses, and CPython refuses to parse past 4300 digits.
+_RETRY_DIGITS: Final = 18
+
+#: How large one event may grow before the decoder refuses it, in characters. Nothing in the
+#: format ends an event but a blank line, so an endpoint that never sends one — or a line that
+#: never terminates — is held in full until the process runs out of memory. Generous enough that
+#: no real event meets it: an inline base64 image is the largest thing any of these streams carry.
+MAX_EVENT: Final = 32 * 1024 * 1024
+
+
+class EventTooLarge(ValueError):
+    """One event grew past the decoder's limit, and the stream was refused rather than held."""
+
+
+class Decoder:
+    """The format as a state machine: feed it chunks, take the events they completed.
+
+    Same shape as ``codecs.IncrementalDecoder``: ``decode(chunk, final)`` and ``reset()``. The
+    problem is the same one. Input is cut at arbitrary points, and output only sometimes
+    completes. It takes chunks and never lines. ``aiohttp``'s ``readuntil`` raises ``LineTooLong``
+    past 131072 bytes, and ``LineTooLong`` is not a ``ClientError``. A large reasoning event killed
+    a turn with no answer.
+
+    Held text costs time for its size, and never for its square. Chunks with no terminator wait
+    in a list. A read line is left behind rather than sliced out. A scanned tail is never scanned
+    twice.
+    """
+
+    __slots__ = (
+        "_limit",
+        "_pending",
+        "_data_size",
+        "_text",
+        "_held",
+        "_parts",
+        "_start",
+        "_scan",
+        "_trailing_cr",
+        "_opened",
+        "_data",
+        "_event",
+        "_id",
+        "_retry",
+    )
+
+    def __init__(self, limit: int = MAX_EVENT) -> None:
+        self._limit = limit
+        self.reset()
+
+    def reset(self) -> None:
+        """Forget the half-read event and the half-read character, ready for another stream."""
+        # What has arrived. ``utf-8-sig`` strips a leading byte order mark, which the format
+        # requires. ``_parts`` holds chunks apart until a terminator arrives, because joining each
+        # one into the buffer copies the whole held event again.
+        #
+        # ``strict``: this stream carries the base64 of a signature, which a provider refuses
+        # on replay if one character changed. A U+FFFD there shows up a request later.
+        self._text = codecs.getincrementaldecoder("utf-8-sig")(errors="strict")
+        self._parts: list[str] = []
+        self._held = ""
+        #: Characters held that no line has taken yet, against ``_limit``.
+        self._pending = 0
+        self._start = 0
+        self._scan = 0
+        self._opened = False
+        self._trailing_cr = False
+
+        # What the lines read so far have collected, for the next dispatch.
+        self._data: list[str] = []
+        self._data_size = 0
+        self._event = ""
+        self._id = ""
+        self._retry: int | None = None
+
+    def decode(self, chunk: bytes | str = b"", final: bool = False) -> list[Event]:
+        """Every event this chunk completed.
+
+        ``final=True`` closes the stream: what is still pending is discarded, which the format
+        requires of an event that never reached its blank line. Without that last call a stream
+        cut mid-character keeps the half character instead of replacing it.
+        """
+        text = self._text_of(chunk, final)
+        self._hold(text)
+        if not final and "\n" not in text and "\r" not in text:
+            self._bounded()
+            return []
+        self._join()
+
+        made: list[Event] = []
+        while (line := self._take()) is not None:
+            if (event := self._read(line)) is not None:
+                made.append(event)
+        if final:
+            self._forget()
+        elif self._start and self._start * 2 >= len(self._held):
+            self._compact()
+        self._bounded()
+        return made
+
+    def _text_of(self, chunk: bytes | str, final: bool) -> str:
+        """This chunk as text, with the byte order mark and a split terminator dealt with."""
+        if isinstance(chunk, bytes):
+            text = self._text.decode(chunk)
+        else:
+            # Half a character whose other half arrived as text, so nothing can complete it:
+            # refused, like every other byte that will not decode. A final flush keeps a partial
+            # mark, so the state is cleared as well as read.
+            if pending := self._text.getstate()[0]:
+                self._text.setstate((b"", 0))
+            text = pending.decode("utf-8") + chunk
+        if not self._opened:
+            # The byte decoder took one mark already, and a second is data. Stripped here as well,
+            # two marks would read differently as bytes than as text.
+            if not isinstance(chunk, bytes):
+                text = text.removeprefix("\ufeff")
+            if text or final:
+                self._opened = True
+                # Flag 0 means no mark is expected, which the byte decoder cannot know on its own.
+                # The pending bytes stay: they are half a character, not a mark.
+                self._text.setstate((self._text.getstate()[0], 0))
+        if final:
+            try:
+                text += self._text.decode(b"", True)
+            except UnicodeDecodeError:
+                # The stream stopped mid-character. Whatever it was carrying never reached its
+                # blank line either, and `_forget` drops that; half a character is the same loss.
+                pass
+        if self._trailing_cr:
+            text, self._trailing_cr = "\r" + text, False
+        if text.endswith("\r") and not final:
+            # A chunk can end mid-terminator. Hold the ``\r`` until the next chunk says whether a
+            # ``\n`` follows, or it invents a blank line and dispatches half an event.
+            text, self._trailing_cr = text[:-1], True
+        return text
+
+    def _hold(self, text: str) -> None:
+        """Keep this text until a terminator arrives."""
+        if not text:
+            return
+        # Every piece costs a string header, so a byte at a time held forty times its size.
+        if self._parts and len(self._parts[-1]) < _MIN_PIECE:
+            self._parts[-1] += text
+        else:
+            self._parts.append(text)
+        self._pending += len(text)
+
+    def _bounded(self) -> None:
+        """Refuse a line that never ends, measured once the complete ones are gone.
+
+        Checked as the chunk arrives instead, ``_pending`` was still the whole unread buffer, so
+        one read holding many small complete events tripped a limit about a single line and named
+        a cause that had not happened.
+        """
+        if self._pending > self._limit:
+            raise EventTooLarge(f"a line ran past {self._limit} characters with no terminator")
+
+    def _compact(self) -> None:
+        """Drop the lines already read, once they outweigh what is left."""
+        self._held = self._held[self._start :]
+        self._scan -= self._start
+        self._start = 0
+
+    def _forget(self) -> None:
+        """Discard what never completed, which is what end of file means for this format.
+
+        Dispatched instead, a connection cut between a frame and the blank line after it makes a
+        truncated turn read as a finished one.
+        """
+        self._held, self._start, self._scan, self._pending = "", 0, 0, 0
+        self._data, self._data_size, self._event, self._retry = [], 0, "", None
+
+    def _join(self) -> None:
+        """Make the held text one string again, and drop the lines already read."""
+        self._parts.insert(0, self._held[self._start :])
+        self._held = "".join(self._parts)
+        self._parts.clear()
+        self._scan -= self._start
+        self._start = 0
+
+    def _take(self) -> str | None:
+        """The next complete line, or None while none is complete.
+
+        At the same position take the longest ending: splitting ``\\r`` out of ``\\r\\n`` leaves a
+        ``\\n`` that reads as a blank line, which dispatches.
+        """
+        held = self._held
+        nl = held.find("\n", self._scan)
+        # Look for a ``\r`` only before that ``\n``. A search for the two-character ``\r\n`` runs to
+        # the end of an LF-only buffer, at a fraction of the speed of a one-character search.
+        cr = held.find("\r", self._scan, len(held) if nl == -1 else nl)
+        if cr != -1:
+            at, after = cr, cr + 2 if cr + 1 == nl else cr + 1
+        elif nl != -1:
+            at, after = nl, nl + 1
+        else:
+            # The tail carries no terminator, so no later chunk scans it again.
+            self._scan = len(held)
+            return None
+        line = held[self._start : at]
+        self._pending -= after - self._start
+        self._start = self._scan = after
+        return line
+
+    def _collected(self) -> bool:
+        """Whether a blank line here fires anything.
+
+        The format dispatches on the data buffer, and on nothing else. A name alone fires nothing,
+        and so does a ``retry:``, which sets the stream's reconnection time rather than sending
+        anything. ``Event.retry`` still reports the value where data arrived beside it.
+        """
+        return bool(self._data)
+
+    def _dispatch(self) -> Event:
+        made = Event(data="\n".join(self._data), event=self._event, id=self._id, retry=self._retry)
+        # The id survives dispatch, per the format: it is the stream's position, not this event's.
+        self._data, self._data_size, self._event, self._retry = [], 0, "", None
+        return made
+
+    def _read(self, line: str) -> Event | None:
+        if not line:
+            # A blank line dispatches, but only if something was collected: a stream of keep-alives
+            # must not become a stream of empty events.
+            if self._collected():
+                return self._dispatch()
+            # `_retry` as well: the format sets the reconnection time from the field, and a
+            # value left behind here rode out on whatever event dispatched next.
+            self._data, self._data_size, self._event, self._retry = [], 0, "", None
+            return None
+        if line.startswith(":"):
+            return None  # comment line
+        name, _, value = line.partition(":")
+        value = value.removeprefix(" ")  # exactly one space, per the format
+        if name == "data":
+            self._data.append(value)
+            self._data_size += len(value) + 1
+            if self._data_size > self._limit:
+                raise EventTooLarge(f"an event collected more than {self._limit} characters of data")
+        elif name == "event":
+            self._event = value
+        elif name == "id" and "\0" not in value:
+            self._id = value
+        elif name == "retry" and value.isascii() and value.isdigit() and len(value) <= _RETRY_DIGITS:
+            self._retry = int(value)
+        # Any other field is ignored, which the format requires: it is how it is extended.
+        return None

axio_sse/event.py

@@ -0,0 +1,104 @@
+"""One event and the JSON object inside it."""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+log = logging.getLogger("axio.sse")
+
+
+class Payload(dict[str, Any]):
+    """The JSON object inside one event, read by path.
+
+    ``payload.number("message", "usage", "input_tokens")`` walks the path and gives the default
+    wherever a step is missing, null, or the wrong type — which is what an optional provider field
+    is. It is a ``dict``, so ``payload["x"]``, ``in``, and ``json.dumps`` all still work. The four
+    readers exist so a handler carries no ``Any`` and no chain of ``.get({})``.
+    """
+
+    __slots__ = ()
+
+    def _at(self, keys: tuple[str, ...]) -> Any:
+        found: Any = self
+        for key in keys:
+            if not isinstance(found, dict):
+                return None
+            found = found.get(key)
+        return found
+
+    def string(self, *keys: str, default: str = "") -> str:
+        """The string at this path, or the default where the provider sent none."""
+        found = self._at(keys)
+        return found if isinstance(found, str) else default
+
+    def number(self, *keys: str, default: int = 0) -> int:
+        """The whole number at this path, or the default where the provider sent none."""
+        found = self._at(keys)
+        # bool is an int in Python. A true/false field must not read here as 1 or 0.
+        return found if isinstance(found, int) and not isinstance(found, bool) else default
+
+    def obj(self, *keys: str) -> Payload:
+        """The object at this path, empty where there is none, so a path can be walked in steps."""
+        found = self._at(keys)
+        return Payload(found) if isinstance(found, dict) else Payload()
+
+    def objs(self, *keys: str) -> list[Payload]:
+        """Every object in the list at this path. A missing list reads as no objects."""
+        found = self._at(keys)
+        if not isinstance(found, list):
+            return []
+        return [Payload(one) for one in found if isinstance(one, dict)]
+
+
+class MalformedPayload(ValueError):
+    """An event that carried data no reader can act on.
+
+    Raised rather than skipped: the stream said this event mattered, and there is no way to
+    continue reading it that does not report a partial turn as a whole one.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """One dispatched event, with the four fields the format defines."""
+
+    data: str = ""
+    #: What the ``event:`` field carried, empty where the stream sent none.
+    event: str = ""
+    #: The stream position for a client that reconnects, not an id of this event.
+    id: str = ""
+    retry: int | None = None
+
+    @property
+    def name(self) -> str:
+        """The event's type. An unnamed event is of type ``message``, which the format defines.
+
+        Dispatched on the raw field instead, an ``@on("message")`` handler never runs for the
+        ordinary unnamed event, and a strict read rejects it as unknown.
+        """
+        return self.event or "message"
+
+    def payload(self) -> Payload | None:
+        """This event's JSON object, or None where the event carries no data at all.
+
+        Data that will not parse raises. Skipped instead, a text or tool-call event whose JSON
+        arrived corrupt was dropped, the completion event after it still reported success, and the
+        caller got a short answer or half a tool's arguments with nothing saying anything was lost.
+
+        A sentinel such as ``[DONE]`` is data too, and reaches here as junk. Name it in ``until``,
+        which ends the stream before it is read.
+        """
+        if not self.data:
+            return None
+        try:
+            got = json.loads(self.data)
+        except json.JSONDecodeError as exc:
+            log.error("payload is not JSON: %.80s", self.data)
+            raise MalformedPayload(f"event {self.name!r} carries data that is not JSON: {exc}") from exc
+        if not isinstance(got, dict):
+            log.error("payload is not an object: %.80s", self.data)
+            raise MalformedPayload(f"event {self.name!r} carries {type(got).__name__} and not an object")
+        return Payload(got)

axio_sse/reader.py

@@ -0,0 +1,200 @@
+"""What one endpoint sends, as one method per event."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterable, AsyncIterator, Callable, Iterable, Mapping
+from types import MappingProxyType
+from typing import Any, ClassVar, Final, cast
+
+from .event import Event, Payload
+from .stream import events
+from .wire import Wire
+
+log = logging.getLogger("axio.sse")
+
+#: ``by=EVENT_NAME`` dispatches on the format's own ``event:`` field. Any other ``by`` names
+#: a key in the payload, and no provider puts a colon in a key.
+EVENT_NAME: Final = "event:"
+
+
+class UnknownEvent(LookupError):
+    """A name no method of this reader claims, met while the reader reads strictly."""
+
+
+def _made[T](result: Handled[T]) -> list[T]:
+    """What a handler returned, as a list.
+
+    A ``str`` is one result, never its letters. It satisfies ``Iterable[str]``, so a ``Reader[str]``
+    handler returning "hello" gave the caller five events.
+    """
+    if result is None:
+        return []
+    if isinstance(result, (str, bytes)):
+        return [cast(T, result)]
+    return list(result)
+
+
+#: What a handler returns: what it made, or nothing. A ``str`` or ``bytes`` counts as one result,
+#: never as a sequence of its parts.
+type Handled[T] = Iterable[T] | None
+
+type _Handler[R, P, T] = Callable[[R, P], Handled[T]]
+
+
+def on[R, P, T](*claimed: str | type[Wire]) -> Callable[[_Handler[R, P, T]], _Handler[R, P, T]]:
+    """Give a ``Reader`` method the payloads it reads.
+
+    Give it a ``Wire`` shape and the method is handed that shape, its fields read by declared name
+    and type. Give it wire names and the method is handed the ``Payload`` itself, which is what a
+    method that only forwards an event wants. Declaring a shape for a payload nobody reads a field
+    of would be a schema written for nothing.
+
+    Several names on one method is how a stream that sends one thing under two names is written.
+    Both stay in the class body, so ``strict`` has nothing to fire on and no second list exists to
+    keep in step with the first.
+    """
+    shapes = [one for one in claimed if isinstance(one, type)]
+    if len(shapes) > 1:
+        raise ValueError("on() takes one shape, or names; a method reads one shape at a time")
+    if shapes and len(claimed) > 1:
+        raise ValueError(f"on({shapes[0].__name__}) already carries its names; do not repeat them")
+
+    if shapes:
+        shape = shapes[0]
+        if not issubclass(shape, Wire):
+            raise TypeError(f"{shape.__name__} is not a Wire, so it cannot say what it reads")
+        if not shape.names:
+            raise ValueError(f"{shape.__name__} has no name to read under — give it name= on the class line")
+        names: tuple[str, ...] = shape.names
+    else:
+        names = tuple(one for one in claimed if isinstance(one, str))
+        shape = None
+        if not names or not all(names):
+            raise ValueError("on() takes at least one event name, and no name may be empty")
+
+    def tag(method: _Handler[R, P, T]) -> _Handler[R, P, T]:
+        # setattr, not an assignment: a type checker refuses a new attribute on a Callable.
+        setattr(method, "_sse_names", names)
+        setattr(method, "_sse_shape", shape)
+        return method
+
+    return tag
+
+
+def _redecorated(klass: type, attribute: str) -> bool:
+    """Whether this class gives that attribute names of its own."""
+    return bool(getattr(vars(klass).get(attribute), "_sse_names", ()))
+
+
+class Reader[T]:
+    """What one endpoint sends, as one method per event.
+
+        class Messages(Reader[StreamEvent], by=EVENT_NAME):
+            @on("content_block_delta")
+            def _delta(self, payload: Payload) -> Iterator[StreamEvent]: ...
+
+    One instance reads one stream. The turn's running totals and id maps live on ``self`` instead
+    of travelling through a call. A reader used for a second response would carry the first one's
+    state into it. Construct one per response. Being that state, a reader must not be frozen.
+    ``read`` latches the caller's ``strict`` on ``self``, and ``@dataclass(frozen=True)`` refuses
+    that assignment. With ``slots=True`` as well, the refusal comes from inside the rebuilt class
+    and says only that ``super()`` got the wrong type. ``@dataclass(slots=True)`` alone is fine.
+
+    A handler returns what the event became — an iterable, or None where the event only moved that
+    state. ``by`` names the payload key that holds the event's name, or ``EVENT_NAME`` for the
+    format's own ``event:`` field. A subclass that does not give ``by`` inherits it.
+    """
+
+    _by: ClassVar[str] = "type"
+    #: Wire name to the method name that reads it and the shape it reads it as. Keyed by the
+    #: function, a subclass that overrides a handler without repeating ``@on`` never runs.
+    _handlers: ClassVar[Mapping[str, tuple[str, type[Wire] | None]]] = MappingProxyType({})
+    #: What the running read was asked for, so ``unknown()`` obeys it from inside a handler.
+    _strict: bool = False
+
+    def __init_subclass__(cls, *, by: str | None = None, **rest: object) -> None:
+        super().__init_subclass__(**rest)
+        if by is not None:
+            cls._by = by
+        found: dict[str, tuple[str, type[Wire] | None]] = {}
+        # Base first, so a subclass replaces only the names it claims again.
+        for klass in reversed(cls.__mro__):
+            here: dict[str, tuple[str, type[Wire] | None]] = {}
+            # Redecorating an inherited name replaces what the parent read, not just how.
+            for stale in [n for n, (attribute, _) in found.items() if _redecorated(klass, attribute)]:
+                del found[stale]
+            for attribute, method in vars(klass).items():
+                shape = cast("type[Wire] | None", getattr(method, "_sse_shape", None))
+                for name in cast(tuple[str, ...], getattr(method, "_sse_names", ())):
+                    if name in here:
+                        # Definition order would silently leave one of the two never called.
+                        taken = here[name][0]
+                        raise ValueError(f"{klass.__qualname__} reads {name!r} twice: {taken} and {attribute}")
+                    here[name] = (attribute, shape)
+            found.update(here)
+        cls._handlers = MappingProxyType(found)
+
+    @classmethod
+    def names(cls) -> frozenset[str]:
+        """Every name this reader claims, for a test to hold against the provider's own list."""
+        return frozenset(cls._handlers)
+
+    def unknown(self, name: str) -> None:
+        """The one policy for a name nothing here reads: DEBUG, or refuse under ``strict``.
+
+        A handler calls it for a second discriminator inside one event, such as a block that names
+        the kind of its own chunks. A nested name nobody read then fails the same replay a new
+        event fails, instead of disappearing.
+        """
+        log.debug("%s does not read %r", type(self).__name__, name)
+        if self._strict:
+            raise UnknownEvent(
+                f"{type(self).__name__} does not read {name!r}; it reads {', '.join(sorted(self.names()))}"
+            )
+
+    def unmatched(self, name: str, payload: Payload) -> Handled[T]:
+        """What a payload no method claims becomes. Nothing, unless a reader says otherwise.
+
+        Override it to forward instead of drop. That is what a stream whose vocabulary grows on its
+        own needs. An endpoint that runs tools names an event per tool. That set is a function
+        of which tools exist and which were asked for, not of the protocol. Naming them one by one
+        makes the reader stale the day a tool is added. It also reports a new tool as news about
+        the protocol, when it is news about the tools.
+
+        Name here only what this reader interprets. ``strict`` still refuses anything unnamed. A test can
+        therefore hold the interpreted set against the schema, and the reader carries no list it
+        cannot keep true.
+        """
+        return None
+
+    def read(self, event: Event, *, strict: bool = False) -> list[T]:
+        """Everything this one event became, empty where it became nothing."""
+        # Latched first, so a nested unknown obeys the same policy as a top-level one, and so a
+        # read that raises before its handler runs has not left the last read's policy on self.
+        self._strict = strict
+        payload = event.payload()
+        if payload is None:
+            return []
+        name = event.name if self._by == EVENT_NAME else payload.string(self._by)
+        claimed = self._handlers.get(name)
+        if claimed is None:
+            # unknown() first: under strict it raises, so a reader that forwards still fails a replay.
+            self.unknown(name)
+            return _made(self.unmatched(name, payload))
+        attribute, shape = claimed
+        handler = cast(Callable[[Any], Handled[T]], getattr(self, attribute))
+        made = handler(payload if shape is None else shape.read(payload))
+        return _made(made)
+
+    async def over(
+        self, chunks: AsyncIterable[bytes | str], *, strict: bool = False, until: str = ""
+    ) -> AsyncIterator[T]:
+        """Read a whole stream of chunks, yielding what each event became.
+
+        An event that becomes nothing yields nothing, so the outputs do not line up with the
+        events.
+        """
+        async for event in events(chunks, until=until):
+            for made in self.read(event, strict=strict):
+                yield made

axio_sse/stream.py

@@ -0,0 +1,37 @@
+"""The async skin over the decoder: chunks in, events or payloads out."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterable, AsyncIterator
+
+from .decoder import Decoder
+from .event import Event, Payload
+
+
+async def events(chunks: AsyncIterable[bytes | str], *, until: str = "") -> AsyncIterator[Event]:
+    """Every event in this stream, as the chunks arrive.
+
+    Chunks must carry their line terminators: ``aiter_lines()`` strips them, so nothing dispatches.
+    A stream that stops without its final blank line still yields what it collected. ``until``
+    names the data payload that closes the stream, and is not yielded.
+    """
+    decoder = Decoder()
+    async for chunk in chunks:
+        for event in decoder.decode(chunk):
+            if until and event.data == until:
+                return
+            yield event
+    for event in decoder.decode(final=True):
+        if until and event.data == until:
+            return
+        yield event
+
+
+async def payloads(chunks: AsyncIterable[bytes | str], *, until: str = "") -> AsyncIterator[Payload]:
+    """The JSON object of every event in this stream. Comments, keep-alives and junk do not arrive.
+
+    All a stream with no discriminator needs: its events are one shape, read field by field.
+    """
+    async for event in events(chunks, until=until):
+        if (payload := event.payload()) is not None:
+            yield payload

axio_sse/wire.py

@@ -0,0 +1,132 @@
+"""Payload shapes: one class per wire name, read into declared fields."""
+
+import logging
+from collections.abc import Iterable, Mapping
+from dataclasses import fields, is_dataclass
+from functools import cache
+from types import UnionType
+from typing import Any, ClassVar, Literal, Self, Union, get_args, get_origin, get_type_hints
+
+from .event import Payload
+
+logger = logging.getLogger(__name__)
+
+
+class Wire:
+    """One payload shape, named by the wire name it arrives under::
+
+        @dataclass(frozen=True, slots=True)
+        class OutputTextDelta(Wire, name="response.output_text.delta"):
+            delta: str = ""
+            output_index: int = 0
+
+    Every field is read by its declared name and type, so a misspelled key is a type error at the
+    place that uses it rather than a default quietly standing in for the value. A field the
+    provider did not send, sent as null, or sent as the wrong type takes its default. That is what
+    an optional provider field is, and one bad field must not lose the whole event.
+
+    A nested object is another ``Wire``; a list of them is ``list[ThatWire]``. Give a shape no
+    ``name=`` and it is only ever nested, never dispatched to.
+
+    Declare a field ``raw: Payload`` and it receives the whole payload, for a shape that varies too
+    much to declare whole. A citation arrives under five shapes and each names its span
+    differently, so the fields worth reading are declared and the rest travels beside them.
+
+    Declaring a shape registers it nowhere. A ``Reader`` claims it with ``@on(ThatShape)``.
+    """
+
+    #: Every name this shape arrives under, from ``name=`` and ``also=`` on the class line.
+    names: ClassVar[tuple[str, ...]] = ()
+
+    def __init_subclass__(cls, *, name: str = "", also: str | Iterable[str] = (), **rest: object) -> None:
+        super().__init_subclass__(**rest)
+        if also and not name:
+            raise ValueError(f"{cls.__name__} gives also= without name=; a shape names itself whole")
+        if name:
+            # Replaces rather than extends: a renamed subclass must not keep its parent's names.
+            cls.names = (name, *((also,) if isinstance(also, str) else also))
+            if not all(cls.names):
+                raise ValueError(f"{cls.__name__} claims an empty name, which would capture every payload")
+
+    @classmethod
+    def read(cls, payload: Payload) -> Self:
+        """This payload as this shape. Extra keys are ignored, missing ones take their defaults."""
+        if not is_dataclass(cls):
+            raise TypeError(f"{cls.__name__} is not a dataclass, so it has no fields to read into")
+        hints = _hints(cls)
+        made: dict[str, Any] = {}
+        for field in fields(cls):
+            if field.name == "raw" and hints[field.name] is Payload:
+                made[field.name] = payload
+                continue
+            if field.name not in payload:
+                continue
+            value = _as(hints[field.name], payload[field.name])
+            if value is not None:
+                made[field.name] = value
+        return cls(**made)
+
+
+@cache
+def _hints(cls: type) -> Mapping[str, Any]:
+    """The declared types of one shape, worked out once.
+
+    Annotations do not change, and every transport uses ``from __future__ import annotations``, so
+    without this each event re-evaluates every annotation from its string form. Measured on a real
+    text delta that was nine tenths of the cost of reading the event.
+    """
+    return get_type_hints(cls)
+
+
+def _as(kind: Any, raw: Any) -> Any:
+    """``raw`` as this declared type, or None where it is not that and the default should stand."""
+    origin = get_origin(kind)
+    if origin is UnionType or origin is Union:
+        rest = [arg for arg in get_args(kind) if arg is not type(None)]
+        for member in rest:
+            if (read := _as(member, raw)) is not None:
+                return read
+        return None
+
+    if isinstance(kind, type) and issubclass(kind, Wire):
+        return kind.read(Payload(raw)) if isinstance(raw, dict) else None
+    if origin is list:
+        if not isinstance(raw, list):
+            return None
+        args = get_args(kind)
+        if not args:
+            return list(raw)
+        read = [_as(args[0], one) for one in raw]
+        return [one for one in read if one is not None]
+    if kind is str:
+        return raw if isinstance(raw, str) else None
+    # bool is an int in Python, so each has to refuse the other.
+    if kind is bool:
+        return raw if isinstance(raw, bool) else None
+    if kind is int:
+        return raw if isinstance(raw, int) and not isinstance(raw, bool) else None
+    if kind is float:
+        if not isinstance(raw, (int, float)) or isinstance(raw, bool):
+            return None
+        try:
+            return float(raw)
+        except OverflowError:
+            # A JSON integer is unbounded and float() is not, so a value the caller cannot represent
+            # takes its default.
+            return None
+    if kind is Payload or kind is dict or origin is dict:
+        return Payload(raw) if isinstance(raw, dict) else None
+    if origin is Literal:
+        return raw if raw in get_args(kind) else None
+    if origin is tuple:
+        if not isinstance(raw, list):
+            return None
+        inner = [a for a in get_args(kind) if a is not Ellipsis]
+        items: list[Any] = [_as(inner[0], one) for one in raw] if inner else list(raw)
+        return tuple(one for one in items if one is not None)
+    if kind is Any:
+        return raw
+    # An annotation the ladder cannot read takes its default rather than whatever arrived. Passed
+    # through, a declared field held a value of any shape and the class's own rule said otherwise.
+    logger.debug("No rule for %r, so the field takes its default", kind)
+    return None

axio_sse-0.11.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.5
+Name: axio-sse
+Version: 0.11.0
+Summary: Server-sent events, read from a stream of chunks
+Project-URL: Documentation, https://docs.axio-agent.com
+Project-URL: Homepage, https://github.com/mosquito/axio-agent
+Project-URL: Repository, https://github.com/mosquito/axio-agent
+License: MIT
+Keywords: async,event-stream,server-sent-events,sse,streaming
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# axio-sse
+
+[![PyPI](https://img.shields.io/pypi/v/axio-sse)](https://pypi.org/project/axio-sse/)
+[![Python](https://img.shields.io/pypi/pyversions/axio-sse)](https://pypi.org/project/axio-sse/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Read `text/event-stream`: a decoder you feed, and a reader for what its payloads mean.
+
+The package knows nothing about HTTP and imports no client. It has no dependencies, not even on
+[axio](https://github.com/mosquito/axio-agent).
+
+## Installation
+
+```bash
+pip install axio-sse
+```
+
+## Usage
+
+### `payloads(chunks, *, until="")` — the JSON object of every event
+
+All a stream with no discriminator needs. Comments, keep-alives and junk never arrive. `until` names
+the one data payload that closes the stream, so a sentinel that is not JSON never reaches you.
+
+<!-- name: test_readme_payloads -->
+```python
+import asyncio
+from axio_sse import payloads
+
+async def chunks():
+    yield b': keep-alive\n\n'
+    yield b'data: {"choices":[{"delta":{"content":"Hel"}}]}\n\n'
+    yield b'data: {"choices":[{"delta":{"content":"lo"}}]}\n\n'
+    yield b"data: [DONE]"
+
+async def main() -> None:
+    got = [p["choices"][0]["delta"]["content"] async for p in payloads(chunks(), until="[DONE]")]
+    assert got == ["Hel", "lo"]
+
+asyncio.run(main())
+```
+
+Feed it whatever the transport hands you. A chunk may end mid-field, mid-terminator, or mid-UTF-8
+sequence. The result does not depend on where it was cut. Chunks must still carry their line
+terminators, so `aiter_lines()` will not do. It strips them, and nothing ever dispatches.
+
+A stream that stops without its final blank line still yields what it collected. The example above
+ends on `data: [DONE]` with no newline after it. That is how these streams really end.
+
+### `events(chunks, *, until="")` — the wire events themselves
+
+<!-- name: test_readme_events -->
+```python
+import asyncio
+from axio_sse import Event, events
+
+async def chunks():
+    yield b'data: {"first":\ndata: true}\n\n'
+    yield b"event: named\r\ndata: sec"
+    yield b"ond\r\n\r\n"
+
+async def main() -> None:
+    assert [e async for e in events(chunks())] == [
+        Event(data='{"first":\ntrue}'),
+        Event(data="second", event="named"),
+    ]
+
+asyncio.run(main())
+```
+
+`Event` carries the four fields the format defines — `data`, `event`, `id`, `retry`. An empty
+`event` means unnamed, which the format reads as `"message"`. `Event.payload()` gives the JSON
+object, or `None` where the event carries none.
+
+`events()` suspends nowhere of its own accord, so it needs no async framework: asyncio, trio and
+anyio all drive it. A `yield` in an async generator does not reach the event loop. A caller that
+must stay fair to other tasks — a TUI redrawing, a queue being served — therefore says so itself,
+with `await asyncio.sleep(0)` in its own loop where it knows what else is waiting.
+
+### `Decoder` — the format, with no loop
+
+`Decoder` is the format and nothing else. It is synchronous and holds no connection. Every wire case
+is therefore testable without a loop. A thread or a non-asyncio caller can drive it too. Same shape
+as `codecs.IncrementalDecoder`, because the problem is the same: input cut at arbitrary points,
+output that only sometimes completes.
+
+<!-- name: test_readme_decoder -->
+```python
+from axio_sse import Decoder, Event
+
+decoder = Decoder()
+assert decoder.decode(b"data: hel") == []
+assert decoder.decode(b"lo\n\ndata: wor") == [Event(data="hello")]
+assert decoder.decode(b"ld\n\n", final=True) == [Event(data="world")]
+```
+
+`final=True` closes the stream. What is still pending is discarded, which the format requires: an
+event that never reached its blank line is not dispatched. Dispatched anyway, a connection cut
+between a frame and the blank line after it makes a truncated turn read as a finished one.
+
+The package takes chunks and never lines for a reason. `aiohttp`'s `readuntil` raises `LineTooLong`
+past 131072 bytes. `LineTooLong` is not a `ClientError`. One large reasoning event kills a turn with
+no answer.
+
+### `Wire` — a payload shape
+
+Declare the fields you read. Each is read by its declared name and type. A misspelled key is
+therefore a type error at the place that uses it, rather than a default quietly standing in for the
+value.
+
+<!-- name: test_readme_reader -->
+```python
+from dataclasses import dataclass, field
+from axio_sse import Payload, Wire
+
+@dataclass(frozen=True, slots=True)
+class Usage(Wire):
+    """Nested, and never dispatched to: it has no name of its own."""
+    output_tokens: int = 0
+
+@dataclass(frozen=True, slots=True)
+class ResponseObject(Wire):
+    usage: Usage = field(default_factory=Usage)
+
+@dataclass(frozen=True, slots=True)
+class OutputTextDelta(Wire, name="response.output_text.delta"):
+    delta: str = ""
+
+@dataclass(frozen=True, slots=True)
+class Completed(Wire, name="response.completed"):
+    response: ResponseObject = field(default_factory=ResponseObject)
+```
+
+A field the provider did not send, sent as null, or sent as the wrong type takes its default. That
+is what an optional provider field is. One bad field must not lose the whole event. A nested object
+is another `Wire`. A list of them is `list[ThatWire]`. Declare a field `raw: Payload` and it
+receives the whole payload, for a shape that varies too much to declare whole.
+
+### `Reader` — one method per event
+
+A stream that says what each event is subclasses `Reader` and writes one `@on(...)` method per
+event. That class body is one endpoint's whole vocabulary. `by` on the class line names the payload
+key that holds the event's name. It defaults to `"type"`.
+
+Give `@on` a shape and the method is handed that shape. Give it names and the method is handed the
+`Payload` itself. That is what a method that only forwards an event wants. Declaring a shape for a
+payload nobody reads a field of would be a schema written for nothing.
+
+One instance reads one stream. The turn's running totals and id maps live on `self` instead of
+travelling through a call. Construct one per response.
+
+<!-- name: test_readme_reader -->
+```python
+import asyncio
+from collections.abc import Iterator
+from axio_sse import Reader, on
+
+class Responses(Reader[str]):
+    """What the Responses API sends, and what each event becomes."""
+
+    def __init__(self) -> None:
+        self.output_tokens = 0
+
+    @on(OutputTextDelta)
+    def _text(self, wire: OutputTextDelta) -> Iterator[str]:
+        yield wire.delta
+
+    @on(Completed)
+    def _completed(self, wire: Completed) -> None:
+        self.output_tokens = wire.response.usage.output_tokens
+
+    @on("response.created", "response.in_progress", "response.output_text.done")
+    def _expected(self, payload: Payload) -> None:
+        """The bookkeeping around the deltas. Named so strict fires only on something new."""
+
+async def chunks():
+    yield b'data: {"type":"response.created"}\n\n'
+    yield b'data: {"type":"response.output_text.delta","delta":"Hi"}\n\n'
+    yield b'data: {"type":"response.completed","response":{"usage":{"output_tokens":7}}}\n\n'
+
+async def main() -> None:
+    turn = Responses()
+    assert [made async for made in turn.over(chunks())] == ["Hi"]
+    assert turn.output_tokens == 7
+
+asyncio.run(main())
+```
+
+A handler returns what the event became — an iterable, or `None` where the event only moved that
+state. Several names on one method is how a stream that sends one thing under two names is written.
+It is also how a group of events that means nothing here is written: a method with only a docstring.
+Both stay in the class body, so no second list exists to keep in step with the first.
+
+### `strict` — failing on the day the provider sends something new
+
+An event no method claims is skipped and logged at DEBUG. Read with `strict=True` and it raises
+instead. That is what a test holds against the provider's own published list.
+
+<!-- name: test_readme_reader -->
+```python
+import pytest
+from axio_sse import Event, UnknownEvent
+
+assert Responses.names() == {
+    "response.output_text.delta",
+    "response.completed",
+    "response.created",
+    "response.in_progress",
+    "response.output_text.done",
+}
+
+with pytest.raises(UnknownEvent, match="response.refusal.delta"):
+    Responses().read(Event(data='{"type":"response.refusal.delta"}'), strict=True)
+```
+
+`strict` belongs to the call, not to the reader. A policy that outlived one call would leave a CI
+test's strictness set for the next caller.
+
+### `EVENT_NAME` — dispatching on the format's own field
+
+Some streams name the event in the SSE `event:` field rather than in the payload.
+
+<!-- name: test_readme_event_name -->
+```python
+import asyncio
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from axio_sse import EVENT_NAME, Reader, Wire, on
+
+@dataclass(frozen=True, slots=True)
+class BlockDelta(Wire):
+    text: str = ""
+
+@dataclass(frozen=True, slots=True)
+class ContentBlockDelta(Wire, name="content_block_delta"):
+    delta: BlockDelta = field(default_factory=BlockDelta)
+
+class Messages(Reader[str], by=EVENT_NAME):
+    @on(ContentBlockDelta)
+    def _delta(self, wire: ContentBlockDelta) -> Iterator[str]:
+        yield wire.delta.text
+
+async def chunks():
+    yield b'event: content_block_delta\ndata: {"delta":{"text":"Hi"}}\n\n'
+    yield b"event: ping\ndata: {}\n\n"
+
+async def main() -> None:
+    assert [made async for made in Messages().over(chunks())] == ["Hi"]
+
+asyncio.run(main())
+```
+
+### `Payload` — reading by path
+
+`Payload` is a `dict`, so `payload["x"]`, `in` and `json.dumps` all still work. The four readers
+exist so a handler carries no `Any` and no chain of `.get({})`. Each walks the path and gives the
+default wherever a step is missing, null, or the wrong type. That is what an optional provider field
+is.
+
+<!-- name: test_readme_payload -->
+```python
+from axio_sse import Payload
+
+payload = Payload({"message": {"usage": {"input_tokens": 7}}, "output": [{"type": "function_call"}]})
+
+assert payload.number("message", "usage", "input_tokens") == 7
+assert payload.number("message", "usage", "output_tokens") == 0
+assert payload.number("message", "usage", "output_tokens", default=3) == 3
+assert payload.string("message", "role") == ""
+assert payload.obj("message", "usage") == {"input_tokens": 7}
+assert payload.objs("output") == [{"type": "function_call"}]
+assert payload.objs("nothing") == []
+```
+
+`number()` never reads a `true` as `1`. `bool` is an `int` in Python, so a flag would otherwise read
+as a count and stay unnoticed:
+
+<!-- name: test_readme_payload -->
+```python
+assert Payload({"flag": True}).number("flag") == 0
+```
+
+## License
+
+MIT

axio_sse-0.11.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+axio_sse/__init__.py,sha256=x_xZlv9NuQY2eD5RjXHHXgA1jxSrz53PoCnaAZevLMg,1866
+axio_sse/decoder.py,sha256=KJ7S84fcAgLadADjGXoy7i_ZrQhsUC41PTKeOir1GGs,11619
+axio_sse/event.py,sha256=ISOKLSuj25Kr1draFWZWWLQXee1GdTbXpg6CPgyjrHM,4205
+axio_sse/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+axio_sse/reader.py,sha256=_mkFhQrYktuetIwsjHFe0JOOQge6i8AgVbrHrqWr6TE,9502
+axio_sse/stream.py,sha256=pAyjAZpIzkWVg1yxiW259OfzE6Q-jy9jWgqpaMTRJyw,1419
+axio_sse/wire.py,sha256=pLsWyEikavGuokQZCmMRVyM5xX3cgi-8OHkQOs62VVY,5818
+axio_sse-0.11.0.dist-info/METADATA,sha256=ZXolPzWiaUVOnYjgeefQjh1XvNfS5O6nPEYHcXitYjk,11037
+axio_sse-0.11.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+axio_sse-0.11.0.dist-info/RECORD,,

axio_sse-0.11.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any