Skip to content

aiollm.methods

methods

Declarative API methods.

Modules:

Name Description
base

Base classes for declaring API methods.

fields

Helpers for method classes: field types, query values and uploads.

path

Parsing and escaping of request path templates.

protocols

Interfaces of API methods as seen by sessions and parsers.

Classes:

Name Description
BaseAPIMethod

A method whose whole response is read and parsed at once.

BaseMethod

Request contract shared by buffered and stream methods.

BaseStreamMethod

A method whose response is consumed as a stream.

IAPIMethod

A method whose response is read at once.

IBaseMethod

What a session needs to know to send any method.

IStreamMethod

A method whose response is consumed as a stream.

BaseAPIMethod

Bases: BaseMethod[ResponseT]

A method whose whole response is read and parsed at once.

ResponseT is the type of the parsed response: a BaseAPIType model (parsed as JSON), str, bytes or None.

Other arguments (list[Model], dict, unions, type aliases) raise TypeError at class definition unless the method sets its own __response_parser__: the default parser could only fail on the response, after the request was sent.

Attributes:

Name Type Description
__response_parser__ IResponseParser

Parser of the response.

__response_argument__ Any

The generic argument as written.

Example

class ListModels(BaseAPIMethod[ModelList]): ... request_path = "/models" ... request_method = "GET"

response_parser property

response_parser: IResponseParser

Parser of the response.

BaseMethod

Bases: BaseModel, ABC

Request contract shared by buffered and stream methods.

A method is a Pydantic model: its fields are the request parameters, and dunder class attributes describe the HTTP request. Subclass BaseAPIMethod or BaseStreamMethod rather than this class.

A field is sent as it is declared: one without a default is required, None is sent as null, and a field that defaults to MISSING is left out of the request until it is given, so x: int | None | MISSING = MISSING can be absent, null or a number. A default of None is a TypeError at class definition (it would send null for a field nobody set), and so is a model with such a field inside a field's type: describe nested request data with a TypedDict, whose NotRequired keys are left out.

The generic argument determines __returning__ and __response_format__, unless a subclass sets them explicitly.

Attributes:

Name Type Description
__request_path__ str

Path appended to the API's base URL. It may contain {field} placeholders, filled from the fields of the same name and percent-encoded.

__request_path_params__ frozenset[str]

Names of the placeholders; derived from __request_path__.

__request_path_safe__ str

Characters left unescaped in path parameters. Empty by default; set it to "/" for identifiers such as "org/model".

__request_method__ str

HTTP method, e.g. "POST".

__request_headers__ HeadersType | None

Headers sent with every request of the method, as a mapping or an IHeaders collection; None for none. They override the session's default headers and are overridden by the headers of a call.

__request_query__ Set[str]

Names of fields sent as query parameters; all other fields go to the body. Any set may be given; it is stored as a frozenset. A list or tuple is sent as a repeated key (ids=a&ids=b); mappings and models are rejected.

__returning__ type[Any] | None

Runtime class of the result; inferred from the generic argument unless a subclass sets it explicitly.

__request_body_format__ BodyFormat

Encoding of the request body.

__value_formatter__ IValueFormatter

Writes dates, times and durations in every part of the request (body, form, query and path). ISO 8601 by default; a provider whose API wants another format sets its own on its base method.

__retryable__ bool

Whether transient failures may be retried. Ignored when the request carries a file that can be read only once.

__response_format__ ResponseFormat

How the response body is parsed.

__definition_error__ str | None

Set when the class failed a check on completing at its first use (a forward reference); every instance then raises it as TypeError. None otherwise.

Methods:

Name Description
model_post_init

Wrap raw binary streams in any field into IOFile.

get_query_map

Return the query parameters.

get_body_map

Return the body fields.

request_headers property

request_headers: IHeaders

Headers of the method, as a new collection on every access.

request_path property

request_path: str

Path appended to the API's base URL, placeholders filled in.

Each parameter is written as text (enums as their values, booleans as true/false, dates through value_formatter) and percent-encoded; only __request_path_safe__ characters are kept.

Raises:

Type Description
TypeError

If a parameter (of a field typed Any) holds a mapping, a model or a collection.

ValueError

If a parameter is None, NaN or infinite, empty, or a ./.. segment.

request_path_template property

request_path_template: str

The path as declared, placeholders kept, e.g. /files/{id}.

It holds none of the request's values, so it is what a log may show: a path parameter can be an identifier of a user's data.

request_method property

request_method: str

HTTP method.

request_body_format property

request_body_format: BodyFormat

Encoding of the request body.

value_formatter property

value_formatter: IValueFormatter

Writes the dates, times and durations of the request.

retryable property

retryable: bool

Whether this request may be retried.

False when __retryable__ is not set or the request carries a file that can be read only once. The fields are looked into one by one, as when streams are wrapped, so a field nested as deep as the limit allows does not count the method as a level.

response_format property

response_format: ResponseFormat

How the response body is parsed.

response_type property

response_type: type[ResponseT] | None

Runtime class of the result, if known.

model_post_init

model_post_init(context: Any) -> None

Wrap raw binary streams in any field into IOFile.

This happens once, at construction: model_dump() would turn raw streams into lazy iterators, and the wrapper records the start position needed to resend the content on retry.

Parameters:

Name Type Description Default
context Any

Pydantic validation context.

required

Raises:

Type Description
TypeError

If the class failed a check when it completed (__definition_error__).

ValueError

If a field holds a text stream.

get_query_map

get_query_map() -> Query | None

Return the query parameters.

Returns:

Type Description
Query | None

Fields listed in __request_query__ converted to strings

Query | None

(booleans as "true"/"false", dates through

Query | None

value_formatter) or, for lists, tuples and sets, to lists

Query | None

of strings; None if the method has no query parameters.

Query | None

A field left MISSING is not sent.

Raises:

Type Description
TypeError

If a value is an object or contains one.

ValueError

If a value is None or a list contains it (a query has no null), or a value is NaN or infinite or rejected by the formatter.

get_body_map

get_body_map() -> Mapping[str, Any]

Return the body fields.

Returns:

Type Description
Mapping[str, Any]

All fields except path and query parameters, keyed by alias:

Mapping[str, Any]

a field left MISSING is not sent, and None is sent as

Mapping[str, Any]

null, also nested, in a model put into the body too.

BaseStreamMethod

Bases: BaseMethod[ItemT]

A method whose response is consumed as a stream.

ItemT is the type of one streamed item: bytes (raw chunks, the default), str (decoded text) or ServerSentEvent (server-sent events as they are). Send it with session.stream().

Other item types, such as models and discriminated unions, need __response_format__ set to SSE or NDJSON: each event is then validated into the item type. Without an explicit format or __stream_parser__ they raise TypeError at class definition; otherwise the stream would yield bytes typed as the model.

Attributes:

Name Type Description
__stream_parser__ IStreamParser

Parser of the stream.

__stream_terminal__ IEventMatcher | None

Recognizes the item that ends a complete SSE or NDJSON stream, e.g. EventTypes("message_stop") or DONE. When it is set, a body that ends without it raises APIStreamInterruptedError and an item after it raises APIResponseError (the body is read to its end). None, the default, checks nothing: by the HTTP and SSE standards the end of the body is a normal end.

__stream_item__ Any

The generic argument as written, including unions and type aliases.

__response_adapter__ TypeAdapter[Any] | None

Validator of the item type for SSE and NDJSON; None for ServerSentEvent items and other formats.

Example

class Download(BaseStreamMethod[bytes]): ... request_path = "/files/content" ... request_method = "GET" ... request_query = {"file_id"} ... file_id: str

stream_parser property

stream_parser: IStreamParser

Parser of the stream.

stream_terminal property

stream_terminal: IEventMatcher | None

Recognizes the item that ends a complete stream, if declared.

response_adapter property

response_adapter: TypeAdapter[ItemT] | None

Validator of one SSE or NDJSON item, if events are validated.

IAPIMethod

Bases: IBaseMethod[ResponseT], Protocol

A method whose response is read at once.

ResponseT is the type of the whole parsed response.

Attributes:

Name Type Description
response_parser IResponseParser

Parser of the response.

response_parser property

response_parser: IResponseParser

Parser of the response.

IBaseMethod

Bases: Protocol

What a session needs to know to send any method.

Only regular properties are declared, never the dunder class attributes of BaseMethod: pyright does not accept unannotated class attributes of subclasses as implementing protocol members declared as ClassVar.

Methods:

Name Description
get_query_map

Return the query parameters.

get_body_map

Return the body fields.

Attributes:

Name Type Description
request_headers IHeaders

Headers sent with every request of the method.

request_path str

Path appended to the API's base URL, parameters filled in.

request_path_template str

The path as declared, placeholders kept: safe to log.

request_method str

HTTP method.

request_body_format BodyFormat

Encoding of the request body.

value_formatter IValueFormatter

Writes the dates, times and durations of the request.

retryable bool

Whether transient failures may be retried.

response_format ResponseFormat

How the response body is parsed.

response_type type[ResponseT] | None

Runtime class of the result; ties ResponseT to the method.

request_headers property

request_headers: IHeaders

Headers sent with every request of the method.

request_path property

request_path: str

Path appended to the API's base URL, parameters filled in.

request_path_template property

request_path_template: str

The path as declared, placeholders kept: safe to log.

request_method property

request_method: str

HTTP method.

request_body_format property

request_body_format: BodyFormat

Encoding of the request body.

value_formatter property

value_formatter: IValueFormatter

Writes the dates, times and durations of the request.

retryable property

retryable: bool

Whether transient failures may be retried.

response_format property

response_format: ResponseFormat

How the response body is parsed.

response_type property

response_type: type[ResponseT] | None

Runtime class of the result; ties ResponseT to the method.

get_query_map

get_query_map() -> Query | None

Return the query parameters.

Returns:

Type Description
Query | None

Parameters as strings or lists of strings, or None if

Query | None

there are none.

get_body_map

get_body_map() -> Mapping[str, Any]

Return the body fields.

Returns:

Type Description
Mapping[str, Any]

Body fields keyed by their wire names.

IStreamMethod

Bases: IBaseMethod[ItemT], Protocol

A method whose response is consumed as a stream.

ItemT is the type of a single item yielded by the stream.

Attributes:

Name Type Description
stream_parser IStreamParser

Parser of the stream.

stream_terminal IEventMatcher | None

Recognizes the item that ends a complete stream, if declared.

response_adapter TypeAdapter[ItemT] | None

Validator of one SSE or NDJSON item; None when not used.

stream_parser property

stream_parser: IStreamParser

Parser of the stream.

stream_terminal property

stream_terminal: IEventMatcher | None

Recognizes the item that ends a complete stream, if declared.

response_adapter property

response_adapter: TypeAdapter[ItemT] | None

Validator of one SSE or NDJSON item; None when not used.