Request API

This module provides low-level API request/response interfaces based on aiohttp.

Depending on the session object where the request is made from, Request and Response differentiate their behavior: works as plain Python functions or returns awaitables.

class ai.backend.client.request.Request(session, method='GET', path=None, content=None, *, content_type=None, params=None, reporthook=None)[source]

The API request object.

with async with fetch(**kwargs) as Response[source]

Sends the request to the server and reads the response.

You may use this method either with plain synchronous Session or AsyncSession. Both the followings patterns are valid:

from ai.backend.client.request import Request
from ai.backend.client.session import Session

with Session() as sess:
  rqst = Request(sess, 'GET', ...)
  with rqst.fetch() as resp:
    print(resp.text())
from ai.backend.client.request import Request
from ai.backend.client.session import AsyncSession

async with AsyncSession() as sess:
  rqst = Request(sess, 'GET', ...)
  async with rqst.fetch() as resp:
    print(await resp.text())
Return type

FetchContextManager

async with connect_websocket(**kwargs) as WebSocketResponse or its derivatives[source]

Creates a WebSocket connection.

Warning

This method only works with AsyncSession.

Return type

WebSocketContextManager

content

Retrieves the content in the original form. Private codes should NOT use this as it incurs duplicate encoding/decoding.

Return type

Union[bytes, bytearray, str, StreamReader, IOBase, None]

set_content(value, *, content_type=None)[source]

Sets the content of the request.

set_json(value)[source]

A shortcut for set_content() with JSON objects.

attach_files(files)[source]

Attach a list of files represented as AttachedFile.

connect_events(**kwargs)[source]

Creates a Server-Sent Events connection.

Warning

This method only works with AsyncSession.

Return type

SSEContextManager

class ai.backend.client.request.Response(session, underlying_response, *, async_mode=False)[source]

Represents the Backend.AI API response. Also serves as a high-level wrapper of aiohttp.ClientResponse.

The response objects are meant to be created by the SDK, not the callers.

text(), json() methods return the resolved content directly with plain synchronous Session while they return the coroutines with AsyncSession.

class ai.backend.client.request.WebSocketResponse(session, underlying_ws)[source]

A high-level wrapper of aiohttp.ClientWebSocketResponse.

class ai.backend.client.request.FetchContextManager(session, rqst_ctx_builder, *, response_cls=<class 'ai.backend.client.request.Response'>, check_status=True)[source]

The context manager returned by Request.fetch().

It provides both synchronouse and asynchronous contex manager interfaces.

class ai.backend.client.request.WebSocketContextManager(session, ws_ctx_builder, *, on_enter=None, response_cls=<class 'ai.backend.client.request.WebSocketResponse'>)[source]

The context manager returned by Request.connect_websocket().

class ai.backend.client.request.AttachedFile(filename, stream, content_type)

A struct that represents an attached file to the API request.

Parameters
  • filename (str) – The name of file to store. It may include paths and the server will create parent directories if required.

  • stream (Any) – A file-like object that allows stream-reading bytes.

  • content_type (str) – The content type for the stream. For arbitrary binary data, use “application/octet-stream”.

content_type

Alias for field number 2

count(value) → integer -- return number of occurrences of value
filename

Alias for field number 0

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

stream

Alias for field number 1