Skip to content

aiollm.response

response

Response containers and streams.

Modules:

Name Description
aiohttp

IStreamResponse and body reading over aiohttp responses.

buffered

Fully read HTTP responses.

parse

Parsers that turn responses into typed results.

protocols

Interface for HTTP responses consumed as a stream.

stream

The object returned to callers of session.stream().

Classes:

Name Description
BufferedResponse

An HTTP response whose body has been read completely.

IStreamResponse

An HTTP response whose body has not been read yet.

Stream

Async iterator over the items of a streamed response.

Functions:

Name Description
map_stream

Open a stream and convert each of its items.

transform_stream

Open a stream and pass its items through transform.

BufferedResponse dataclass

BufferedResponse(
    status: int,
    headers: Mapping[str, str],
    body: bytes,
    charset: str | None = None,
)

An HTTP response whose body has been read completely.

Transport-neutral: the session produces it from whatever HTTP client it uses, and parsers consume it.

Attributes:

Name Type Description
status int

HTTP status code.

headers Mapping[str, str]

Response headers.

body bytes

The raw response body.

charset str | None

Charset from the Content-Type header, if any.

IStreamResponse

Bases: Protocol

An HTTP response whose body has not been read yet.

The session owns it and closes it once the stream is done; a stream parser only consumes iter_chunks().

Methods:

Name Description
iter_chunks

Yield the body as it arrives.

read

Read the whole remaining body.

aclose

Release the connection.

Attributes:

Name Type Description
status int

HTTP status code.

headers Mapping[str, str]

Response headers.

charset str | None

Charset from the Content-Type header, if any.

status property

status: int

HTTP status code.

headers property

headers: Mapping[str, str]

Response headers.

charset property

charset: str | None

Charset from the Content-Type header, if any.

iter_chunks

iter_chunks() -> AsyncIterator[bytes]

Yield the body as it arrives.

Yields:

Type Description
AsyncIterator[bytes]

Chunks of the body, of arbitrary size.

Raises:

Type Description
APITransportError

If the connection fails mid-stream or the body ends before it is complete (APIConnectionError), which Stream raises as APIStreamInterruptedError.

read async

read() -> bytes

Read the whole remaining body.

Returns:

Type Description
bytes

The body; used for error responses.

aclose async

aclose() -> None

Release the connection.

Safe to call before the body is fully read; the connection is then closed instead of being reused.

Stream

Stream(items: AsyncIterator[T])

Async iterator over the items of a streamed response.

Obtained from async with session.stream(method) as stream; the session closes it when the async with block exits, and iterating it after that raises RuntimeError.

A transport failure while iterating (a lost connection, a silent stream timing out) is raised as APIStreamInterruptedError, which is never retried, with the original error as its __cause__.

Example

async with session.stream(Download()) as stream: ... async for chunk in stream: ... handle(chunk)

Wrap the parser's item iterator.

Parameters:

Name Type Description Default
items AsyncIterator[T]

Items produced by the method's stream parser.

required

Methods:

Name Description
aclose

Close the underlying parser generator, if it is one.

save

Write a byte stream to a file without buffering it in memory.

Attributes:

Name Type Description
items_received int

How many items the stream has given so far.

items_received property

items_received: int

How many items the stream has given so far.

aclose async

aclose() -> None

Close the underlying parser generator, if it is one.

save async

save(path: str | PathLike[str]) -> int

Write a byte stream to a file without buffering it in memory.

Only available on Stream[bytes]. Opening, writing and closing run in a worker thread; after a cancellation the file is closed, in the thread too, once the write running there is over.

Parameters:

Name Type Description Default
path str | PathLike[str]

Destination file; it is created or overwritten.

required

Returns:

Type Description
int

Number of bytes written.

Raises:

Type Description
RuntimeError

If the stream is closed; the file is not touched.

APIStreamInterruptedError

If the stream breaks mid-way; the file keeps what was written.

map_stream

map_stream(
    source: AbstractAsyncContextManager[Stream[T]],
    convert: Callable[[T], R],
) -> AbstractAsyncContextManager[Stream[R]]

Open a stream and convert each of its items.

The one-to-one case of transform_stream, with the same closing order.

Parameters:

Name Type Description Default
source AbstractAsyncContextManager[Stream[T]]

The stream to open, e.g. session.stream(method).

required
convert Callable[[T], R]

Turns one source item into one result item.

required

Returns:

Type Description
AbstractAsyncContextManager[Stream[R]]

A context manager that yields a stream of converted items.

Example

async with map_stream(session.stream(Deltas()), to_event) as s: ... async for event in s: ... handle(event)

transform_stream

transform_stream(
    source: AbstractAsyncContextManager[Stream[T]],
    transform: Callable[
        [AsyncIterator[T]], AsyncIterator[R]
    ],
) -> AbstractAsyncContextManager[Stream[R]]
transform_stream(
    source: AbstractAsyncContextManager[Stream[T]],
    transform: Callable[
        [AsyncIterator[T]], AsyncIterator[R]
    ],
    *,
    stream_type: Callable[[AsyncIterator[R]], S],
) -> AbstractAsyncContextManager[S]
transform_stream(
    source: AbstractAsyncContextManager[Stream[T]],
    transform: Callable[
        [AsyncIterator[T]], AsyncIterator[R]
    ],
    *,
    stream_type: Callable[
        [AsyncIterator[R]], Stream[Any]
    ] = Stream,
) -> AbstractAsyncContextManager[Stream[Any]]

Open a stream and pass its items through transform.

transform sees the whole source, so it can keep state between items, skip some and turn one item into several, e.g. collect text deltas into a final event. On exit, including break and exceptions, the transformed stream is closed first and the source after it; iterating the result after the block raises RuntimeError.

Parameters:

Name Type Description Default
source AbstractAsyncContextManager[Stream[T]]

The stream to open, e.g. session.stream(method).

required
transform Callable[[AsyncIterator[T]], AsyncIterator[R]]

Turns the source items into result items; usually an async generator function.

required
stream_type Callable[[AsyncIterator[R]], Stream[Any]]

The Stream class to yield, such as GenerationStream; built on the transformed items once, with no second wrapper.

Stream

Returns:

Type Description
AbstractAsyncContextManager[Stream[Any]]

A context manager that yields a stream of transformed items.

Example

async def texts(events): ... async for event in events: ... if event.text: ... yield event.text async with transform_stream(session.stream(Deltas()), texts) as s: ... async for text in s: ... handle(text)

parse

Parsers that turn responses into typed results.

Modules:

Name Description
buffered

Parser for fully read responses.

lines

Incremental splitting of a byte stream into text lines.

protocols

Interfaces for turning responses into typed results.

sse

Server-sent events, assembled from lines as the HTML standard says.

stream

Parser for streamed responses.

Classes:

Name Description
BufferedResponseParser

Parses JSON, text, bytes and empty responses.

IResponseParser

Parses a fully read response into the method's result type.

IStreamParser

Parses a streamed response into an iterator of items.

ServerSentEvent

One server-sent event.

StreamResponseParser

Turns a streamed body into chunks, text pieces or events.

BufferedResponseParser

BufferedResponseParser(
    *, error_responses: IEventMatcher | None = None
)

Parses JSON, text, bytes and empty responses.

Create the parser.

Parameters:

Name Type Description Default
error_responses IEventMatcher | None

Recognizes a validated JSON result that reports a failure although its status is below 400, such as OpenAI's Response with status failed (FieldValues("status", "failed")). Such a result is raised as the APIStatusError the session's error resolver builds from the body, with the result as its raw. None accepts every result.

None

Methods:

Name Description
parse

Parse the body according to method.response_format.

parse

parse(
    method: IAPIMethod[T],
    response: BufferedResponse,
    json_loads: JsonLoads,
    error_resolver: IErrorResolver,
) -> T

Parse the body according to method.response_format.

Parameters:

Name Type Description Default
method IAPIMethod[T]

The method that was sent.

required
response BufferedResponse

The successful response.

required
json_loads JsonLoads

JSON decoder of the session. With the default decoder the body is validated by Pydantic directly in JSON mode; a custom decoder's result is validated in Python mode, where strict fields reject JSON strings for dates, UUIDs and enums.

required
error_resolver IErrorResolver

Error resolver of the session, for results that error_responses matches.

required

Returns:

Type Description
T

A validated model for JSON, str for TEXT, bytes for

T

BYTES and None for NONE.

Raises:

Type Description
APIStatusError

If error_responses matches the result.

APIResponseError

If the body is not valid JSON (also for a custom decoder), fails validation, cannot be decoded as text, or is not empty when NONE is expected. The parser raises it itself, so the session passes any other error on as the bug it is.

TypeError

If a JSON method has no model response type.

ValueError

If the format is not supported for buffered responses.

IResponseParser

Bases: Protocol

Parses a fully read response into the method's result type.

Methods:

Name Description
parse

Parse a successful response.

parse

parse(
    method: IAPIMethod[T],
    response: BufferedResponse,
    json_loads: JsonLoads,
    error_resolver: IErrorResolver,
) -> T

Parse a successful response.

Parameters:

Name Type Description Default
method IAPIMethod[T]

The method that was sent; its response format and type decide how the body is parsed.

required
response BufferedResponse

The response, with a status below 400.

required
json_loads JsonLoads

JSON decoder of the session.

required
error_resolver IErrorResolver

Error resolver of the session, for a result that reports a failure although its status is below 400.

required

Returns:

Type Description
T

The parsed result.

Raises:

Type Description
APIResponseError

If the body cannot be decoded or validated. The session does not wrap other errors, so a parser reports a bad body this way itself.

APIStatusError

If the result reports a failure.

IStreamParser

Bases: Protocol

Parses a streamed response into an iterator of items.

Methods:

Name Description
parse

Start parsing a successful streamed response.

parse

parse(
    method: IStreamMethod[T],
    response: IStreamResponse,
    json_loads: JsonLoads,
    error_resolver: IErrorResolver,
) -> AsyncIterator[T]

Start parsing a successful streamed response.

Parameters:

Name Type Description Default
method IStreamMethod[T]

The method that was sent; its response format decides how chunks are turned into items.

required
response IStreamResponse

The response, with a status below 400.

required
json_loads JsonLoads

JSON decoder of the session.

required
error_resolver IErrorResolver

Error resolver of the session, for errors reported inside the stream.

required

Returns:

Type Description
AsyncIterator[T]

An iterator over the stream's items. It raises

AsyncIterator[T]

APIResponseError for an item that cannot be decoded or

AsyncIterator[T]

validated, and APIStatusError for an error event.

ServerSentEvent dataclass

ServerSentEvent(
    data: str,
    event: str = "message",
    id: str | None = None,
    retry: int | None = None,
)

One server-sent event.

Use it as the item type of a stream method to receive events as they are, without validating their data.

Attributes:

Name Type Description
data str

The data lines of the event, joined with \n.

event str

The event type; "message" when the event has none.

id str | None

The last event ID seen so far in the stream, if any.

retry int | None

The reconnection time in milliseconds last set in the stream, if any. As for id, the HTML standard applies a retry field at once, not to its event only, so it is kept until another one replaces it.

StreamResponseParser

StreamResponseParser(
    *,
    max_line_size: int | None = MAX_LINE_SIZE,
    max_event_size: int | None = MAX_EVENT_SIZE,
    require_event_stream: bool = True,
    error_events: IEventMatcher = ERROR_EVENTS,
)

Turns a streamed body into chunks, text pieces or events.

Create the parser.

Parameters:

Name Type Description Default
max_line_size int | None

Longest SSE or NDJSON line accepted, in characters; MAX_LINE_SIZE (32 Mi) by default, None for no limit.

MAX_LINE_SIZE
max_event_size int | None

Largest SSE event data accepted, in characters; MAX_EVENT_SIZE (32 Mi) by default, None for no limit.

MAX_EVENT_SIZE
require_event_stream bool

Whether an SSE response must have Content-Type: text/event-stream. A proxy or captive portal answering 200 with an HTML page would otherwise give a silently empty stream; turn it off only for a server that sends another type.

True
error_events IEventMatcher

Recognizes the decoded JSON of an SSE event or an NDJSON line that reports an error; such an event is raised as the APIStatusError the session's error resolver builds, instead of being yielded. An SSE event of type error is always raised. ServerSentEvent items are checked too when their data is JSON; data that is not JSON is yielded as it is.

ERROR_EVENTS

Methods:

Name Description
parse

Start parsing according to method.response_format.

Attributes:

Name Type Description
error_events IEventMatcher

Recognizes the decoded event data that is raised as an error.

error_events property

error_events: IEventMatcher

Recognizes the decoded event data that is raised as an error.

parse

parse(
    method: IStreamMethod[T],
    response: IStreamResponse,
    json_loads: JsonLoads,
    error_resolver: IErrorResolver,
) -> AsyncIterator[T]

Start parsing according to method.response_format.

Parameters:

Name Type Description Default
method IStreamMethod[T]

The method that was sent.

required
response IStreamResponse

The successful streamed response.

required
json_loads JsonLoads

JSON decoder of the session.

required
error_resolver IErrorResolver

Error resolver of the session, for errors reported inside the stream.

required

Returns:

Type Description
AsyncIterator[T]

Raw chunks for BYTES, decoded text pieces for TEXT, and events

AsyncIterator[T]

validated into the method's item type for SSE and NDJSON

AsyncIterator[T]

(ServerSentEvent items are returned as they are). For SSE

AsyncIterator[T]

and NDJSON, method.stream_terminal is enforced as

AsyncIterator[T]

BaseStreamMethod.__stream_terminal__ describes.

Raises:

Type Description
ValueError

If the format is not supported for streams.