Session Interface

The Session and AsyncSession are abstract classes that act as adapters to underlying HTTP client libraries. A session instance is used by Client or AsyncClient to perform all the HTTP requests to the Yandex.Disk API.

These interfaces can be implemented to add support for any HTTP library. For a concrete example, see the source code of any existing implementation (e.g. HTTPXSession).

Synchronous

class yadisk.Session

HTTP session class. Maintains open connections, stores headers and some other request parameters.

Must be explicitly closed (can be done using the with statement).

close() → None

Closes the session.

Note

This is an abstract method that needs to be implemented.

send_request(method: Literal['GET'] | Literal['POST'] | Literal['PUT'] | Literal['PATCH'] | Literal['DELETE'] | Literal['OPTIONS'] | Literal['HEAD'] | Literal['CONNECT'] | Literal['TRACE'], url: str, *, params: dict[str, Any] | None = None, data: bytes | Iterator[bytes] | None = None, timeout: float | tuple[float | None, float | None] | None = None, stream: bool = False, **kwargs) → Response

Sends an HTTP request with given parameters. In case an error occurs, the method should throw one of exceptions derived from YaDiskError. Additional keyword arguments may be passed, they may be forwarded to the underlying HTTP client without modification.

Note

This is an abstract method that needs to be implemented.

Parameters:

• method – str, HTTP method

• url – str, URL

• params – dict, GET parameters

• data – bytes, an iterator or a file-like object, data to be sent in the request body

• headers – dict, additional headers to be set

• timeout – request timeout, a tuple of (read timeout, connect timeout), float or None (no timeout)

• stream – bool, if False, the response content will be immediately downloaded

Returns:

Response, response object

set_headers(headers: dict[str, str]) → None

Updates session’s headers.

Note

This is an abstract method that needs to be implemented.

Parameters:

headers – dictionary of headers to be set

set_token(token: str) → None

Sets token for the session by setting the Authorization header.

Parameters:

token – str, API token

class yadisk.Response

Represents an HTTP response.

In case an error occurs, methods of this class should throw one of exceptions derived from YaDiskError.

Variables:

status – int, HTTP status code

close() → None

Closes the response and releases the underlying connection into the pool

Note

This is an abstract method that needs to be implemented.

download(consume_callback: Callable[[bytes], None]) → None

Downloads response’s content.

Note

This is an abstract method that needs to be implemented.

Parameters:

consume_callback – function, takes one parameter - chunk of data (bytes), consumes the chunk (e.g. by writing to a file)

get_exception() → YaDiskError

Convenience wrapper for yadisk.utils.get_exception.

json() → dict | list | str | int | float | None

Returns JSON-content of the response (parses JSON).

Note

This is an abstract method that needs to be implemented.

Returns:

dict, list, str, int, float or None

Asynchronous

class yadisk.AsyncSession

HTTP session class. Maintains open connections, stores headers and some other request parameters.

Must be explicitly closed (can be done using the with statement).

async close() → None

Closes the session.

Note

This is an abstract method that needs to be implemented.

async send_request(method: Literal['GET'] | Literal['POST'] | Literal['PUT'] | Literal['PATCH'] | Literal['DELETE'] | Literal['OPTIONS'] | Literal['HEAD'] | Literal['CONNECT'] | Literal['TRACE'], url: str, *, params: dict[str, Any] | None = None, data: bytes | Iterator[bytes] | AsyncIterator[bytes] | None = None, timeout: float | tuple[float | None, float | None] | None = None, stream: bool = False, **kwargs) → AsyncResponse

Sends an HTTP request with given parameters. In case an error occurs, the method should throw one of exceptions derived from YaDiskError. Additional keyword arguments may be passed, they may be forwarded to the underlying HTTP client without modification.

Note

This is an abstract method that needs to be implemented.

Parameters:

• method – str, HTTP method

• url – str, URL

• params – dict, GET parameters

• data – bytes, iterator (possibly async) or a file-like object (possible async), data to be sent in the request body

• headers – dict, additional headers to be set

• timeout – request timeout, a tuple of (read timeout, connect timeout), float or None (no timeout)

• stream – bool, if False, the response content will be immediately downloaded

Returns:

Response, response object

set_headers(headers: dict[str, str]) → None

Updates session’s headers.

Note

This is an abstract method that needs to be implemented.

Parameters:

headers – dictionary of headers to be set

set_token(token: str) → None

Sets token for the session by setting the Authorization header.

Parameters:

token – str, API token

class yadisk.AsyncResponse

Represents an HTTP response.

In case an error occurs, methods of this class should throw one of exceptions derived from YaDiskError.

Variables:

status – int, HTTP status code

async close() → None

Closes the response and releases the underlying connection into the pool.

Note

This is an abstract method that needs to be implemented.

async download(consume_callback: Callable[[bytes], None] | Callable[[bytes], Awaitable[None]]) → None

Downloads response’s content.

Note

This is an abstract method that needs to be implemented.

Parameters:

consume_callback – regular or async function, takes one parameter - chunk of data (bytes), consumes the chunk (e.g. by writing to a file)

async get_exception() → YaDiskError

Convenience wrapper for yadisk.utils.get_exception.

async json() → dict | list | str | int | float | None

Returns JSON-content of the response (parses JSON).

Note

This is an abstract method that needs to be implemented.

Returns:

dict, list, str, int, float or None