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"
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 |
__request_path_params__ |
frozenset[str]
|
Names of the placeholders; derived from
|
__request_path_safe__ |
str
|
Characters left unescaped in path
parameters.
Empty by default; set it to |
__request_method__ |
str
|
HTTP method, e.g. |
__request_headers__ |
HeadersType | None
|
Headers sent with every request of the
method, as a mapping or an |
__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 |
__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 |
Methods:
| Name | Description |
|---|---|
model_post_init |
Wrap raw binary streams in any field into |
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 |
ValueError
|
If a parameter is |
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.
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_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
( |
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 |
Query | None
|
(booleans as |
Query | None
|
|
Query | None
|
of strings; |
Query | None
|
A field left |
Raises:
| Type | Description |
|---|---|
TypeError
|
If a value is an object or contains one. |
ValueError
|
If a value is |
get_body_map
¶
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. |
__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; |
Example
class Download(BaseStreamMethod[bytes]): ... request_path = "/files/content" ... request_method = "GET" ... request_query = {"file_id"} ... file_id: str
stream_terminal
property
¶
stream_terminal: IEventMatcher | None
Recognizes the item that ends a complete stream, if declared.
response_adapter
property
¶
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. |
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 |
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.
value_formatter
property
¶
value_formatter: IValueFormatter
Writes the dates, times and durations of the request.
response_type
property
¶
response_type: type[ResponseT] | None
Runtime class of the result; ties ResponseT to the method.
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; |
stream_terminal
property
¶
stream_terminal: IEventMatcher | None
Recognizes the item that ends a complete stream, if declared.
response_adapter
property
¶
Validator of one SSE or NDJSON item; None when not used.