aiollm.response¶
response
¶
Response containers and streams.
Modules:
| Name | Description |
|---|---|
aiohttp |
|
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 |
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 |
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 |
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 |
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 ( |
aclose
async
¶
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. |
save
async
¶
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. |
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. |
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
|
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 |
None
|
Methods:
| Name | Description |
|---|---|
parse |
Parse the body according to |
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 |
required |
Returns:
| Type | Description |
|---|---|
T
|
A validated model for JSON, |
T
|
BYTES and |
Raises:
| Type | Description |
|---|---|
APIStatusError
|
If |
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]
|
|
AsyncIterator[T]
|
validated, and |
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 |
event |
str
|
The event type; |
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 |
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
|
max_event_size
|
int | None
|
Largest SSE event data accepted, in
characters; |
MAX_EVENT_SIZE
|
require_event_stream
|
bool
|
Whether an SSE response must have
|
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 |
ERROR_EVENTS
|
Methods:
| Name | Description |
|---|---|
parse |
Start parsing according to |
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]
|
( |
AsyncIterator[T]
|
and NDJSON, |
AsyncIterator[T]
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the format is not supported for streams. |