Low-Level API

API Request Objects

class yadisk.api.APIRequest(session: Session | AsyncSession, args: dict, **kwargs)[source]

Base class for all API requests.

Parameters:

  • session – an instance of Session

  • args – dict of arguments, that will be passed to process_args

  • timeout – float or tuple, request timeout

  • headers – dict or None, additional request headers

  • n_retries – int, maximum number of retries

  • retry_interval – delay between retries in seconds

  • kwargs – other arguments for Session.send_request

Variables:

  • url – str, request URL

  • method – str, request method

  • content_type – str, Content-Type header (“application/x-www-form-urlencoded” by default)

  • timeout – float or tuple, request timeout

  • n_retries – int, maximum number of retries

  • success_codes – list-like, list of response codes that indicate request’s success

  • retry_interval – float, delay between retries in seconds

async aprocess(**kwargs) → T[source]

Process the response.

Parameters:

kwargs – extra arguments (optional)

Returns:

depends on self.process_json()

async asend() → AsyncResponse[source]

Actually send the request

Returns:

AsyncResponse (self.response)

process(**kwargs) → T[source]

Process the response.

Parameters:

kwargs – extra arguments (optional)

Returns:

depends on self.process_json()

process_json(js: dict | list | str | int | float | None, **kwargs) → T[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

send() → Response[source]

Actually send the request

Returns:

Response (self.response)

class yadisk.api.auth.GetDeviceCodeRequest(session: AnySession, client_id: str, device_id: str | None = None, device_name: str | None = None, scope: str | None = None, optional_scope: str | None = None, **kwargs)[source]

Bases: APIRequest

This request is used for authorization using the Yandex OAuth page. In this case the user must enter the verification code (user_code) in the browser on the Yandex OAuth page. After the user has entered the code on the OAuth page, the application can exchange the device_code for the token.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • client_id – application ID

  • device_id – unique device ID (between 6 and 50 characters)

  • device_name – device name, should not be longer than 100 characters

  • scope – str, list of permissions for the application

  • optional_scope – str, list of optional permissions for the application

process_json(js: dict | list | str | int | float | None, **kwargs) → DeviceCodeObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.auth.GetTokenRequest(session: AnySession, grant_type: Literal['authorization_code'] | Literal['device_code'] | Literal['refresh_token'], client_id: str, code: str | None = None, token: str | None = None, client_secret: str | None = None, device_id: str | None = None, device_name: str | None = None, code_verifier: str | None = None, **kwargs)[source]

Bases: APIRequest

A request to get the token.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • code – confirmation code

  • client_id – application ID

  • client_secret – application secret password

  • device_id – unique device ID (between 6 and 50 characters)

  • device_name – device name, should not be longer than 100 characters

  • code_verifier – str, verifier code, used with the PKCE authorization flow

Returns:

TokenObject

process_json(js: dict | list | str | int | float | None, **kwargs) → TokenObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.auth.RefreshTokenRequest(session: AnySession, refresh_token: str, client_id: str, client_secret: str, **kwargs)[source]

Bases: APIRequest

A request to refresh an existing token.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • refresh_token – the refresh token that was received with the original token

  • client_id – application ID

  • client_secret – application secret password

Returns:

TokenObject

process_json(js: dict | list | str | int | float | None, **kwargs) → TokenObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.auth.RevokeTokenRequest(session: AnySession, token: str, client_id: str, client_secret: str, **kwargs)[source]

Bases: APIRequest

A request to revoke the token.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • token – the token to be revoked

  • client_id – application ID

  • client_secret – application secret password

Returns:

TokenRevokeStatusObject

process_json(js: dict | list | str | int | float | None, **kwargs) → TokenRevokeStatusObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.disk.DiskInfoRequest(session: AnySession, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get disk information.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • fields – list of keys to be included in the response

Returns:

DiskInfoObject

process_json(js: dict | None) → DiskInfoObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.CopyRequest(session: AnySession, src_path: str, dst_path: str, overwrite: bool = False, force_async: bool = False, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to copy a file or a directory.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • src_path – source path

  • dst_path – destination path

  • overwrite – if True the destination path can be overwritten, otherwise, an error will be raised

  • force_async – forces the operation to be executed asynchronously

  • fields – list of keys to be included in the response

Returns:

ResourceLinkObject or OperationLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → OperationLinkObject | ResourceLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.DeleteRequest(session: AnySession, path: str, permanently: bool = False, md5: str | None = None, force_async: bool = False, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to delete a file or a directory.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • path – path to the resource to be removed

  • permanently – if True, the resource will be removed permanently, otherwise, it will be just moved to the trash

  • force_async – forces the operation to be executed asynchronously

  • md5 – str, MD5 hash of the file to remove

  • fields – list of keys to be included in the response

Returns:

OperationLinkObject or None

process_json(js: dict | None, yadisk: AnyClient | None = None) → OperationLinkObject | None[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.DeleteTrashRequest(session: AnySession, path: str | None = None, force_async: bool = False, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to delete a trash resource.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • path – path to the trash resource to be deleted

  • force_async – forces the operation to be executed asynchronously

  • fields – list of keys to be included in the response

Returns:

OperationLinkObject or None

process_json(js: dict | None, yadisk: AnyClient | None = None) → OperationLinkObject | None[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.FilesRequest(session: AnySession, offset: int = 0, limit: int = 20, media_type: str | Iterable[str] | None = None, preview_size: str | None = None, preview_crop: bool | None = None, sort: str | None = None, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get a flat list of all files (that doesn’t include directories).

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • offset – offset from the beginning of the list

  • limit – number of list elements to be included

  • media_type – type of files to include in the list

  • sort – str, field to be used as a key to sort children resources

  • preview_size – size of the file preview

  • preview_crop – bool, cut the preview to the size specified in the preview_size

  • fields – list of keys to be included in the response

Returns:

FilesResourceListObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → FilesResourceListObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.GetDownloadLinkRequest(session: AnySession, path: str, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get a download link to a resource.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • path – path to the resource to be downloaded

  • fields – list of keys to be included in the response

Returns:

ResourceDownloadLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → ResourceDownloadLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.GetMetaRequest(session: AnySession, path: str, limit: int | None = None, offset: int | None = None, preview_size: str | None = None, preview_crop: bool | None = None, sort: str | None = None, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get meta-information about a resource.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • path – path to the resource

  • limit – number of children resources to be included in the response

  • offset – number of children resources to be skipped in the response

  • preview_size – size of the file preview

  • preview_crop – bool, cut the preview to the size specified in the preview_size

  • sort – str, field to be used as a key to sort children resources

  • fields – list of keys to be included in the response

Returns:

ResourceObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → ResourceObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.GetPublicDownloadLinkRequest(session: AnySession, public_key: str, path: str | None = None, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get a download link for a public resource.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • public_key – public key or public URL of the resource

  • path – relative path to the resource within the public folder

  • fields – list of keys to be included in the response

Returns:

ResourceDownloadLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → ResourceDownloadLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.GetPublicMetaRequest(session: AnySession, public_key: str, offset: int = 0, limit: int = 20, path: str | None = None, sort: str | None = None, preview_size: str | None = None, preview_crop: bool | None = None, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get meta-information about a public resource.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • public_key – public key or public URL of the resource

  • path – relative path to a resource in a public folder. By specifying the key of the published folder in public_key, you can request metainformation for any resource in the folder.

  • offset – offset from the beginning of the list of nested resources

  • limit – maximum number of nested elements to be included in the list

  • sort – str, field to be used as a key to sort children resources

  • preview_size – file preview size

  • preview_crop – bool, allow preview crop

  • fields – list of keys to be included in the response

Returns:

PublicResourceObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → PublicResourceObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.GetPublicResourcesRequest(session: AnySession, offset: int = 0, limit: int = 20, preview_size: str | None = None, preview_crop: bool | None = None, type: str | None = None, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get a list of public resources.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • offset – offset from the beginning of the list

  • limit – maximum number of elements in the list

  • preview_size – size of the file preview

  • preview_crop – bool, cut the preview to the size specified in the preview_size

  • type – filter based on type of resources (“file” or “dir”)

  • fields – list of keys to be included in the response

Returns:

PublicResourcesListObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → PublicResourcesListObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.GetTrashRequest(session: AnySession, path: str, offset: int = 0, limit: int = 20, sort: str | None = None, preview_size: str | None = None, preview_crop: bool | None = None, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get meta-information about a trash resource.

Parameters:

  • path – path to the trash resource

  • limit – number of children resources to be included in the response

  • offset – number of children resources to be skipped in the response

  • preview_size – size of the file preview

  • preview_crop – bool, cut the preview to the size specified in the preview_size

  • sort – str, field to be used as a key to sort children resources

  • fields – list of keys to be included in the response

Returns:

TrashResourceObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → TrashResourceObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.GetUploadLinkRequest(session: AnySession, path: str, overwrite: bool = False, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get an upload link.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • path – path to be uploaded at

  • overwrite – bool, determines whether to overwrite the destination

  • fields – list of keys to be included in the response

Returns:

ResourceUploadLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → ResourceUploadLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.LastUploadedRequest(session: AnySession, limit: int = 20, media_type: str | Iterable[str] | None = None, preview_size: str | None = None, preview_crop: bool | None = None, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get the list of latest uploaded files sorted by upload date.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • limit – maximum number of elements in the list

  • media_type – type of files to include in the list

  • preview_size – size of the file preview

  • preview_crop – bool, cut the preview to the size specified in the preview_size

  • fields – list of keys to be included in the response

Returns:

LastUploadedResourceListObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → LastUploadedResourceListObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.MkdirRequest(session: AnySession, path: str, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to create a new directory.

Parameters:

  • path – path to the directory to be created

  • fields – list of keys to be included in the response

Returns:

ResourceLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → ResourceLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.MoveRequest(session: AnySession, src_path: str, dst_path: str, force_async: bool = False, overwrite: bool = False, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to move a resource.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • src_path – source path to be moved

  • dst_path – destination path

  • force_async – forces the operation to be executed asynchronously

  • overwrite – bool, determines whether to overwrite the destination

  • fields – list of keys to be included in the response

Returns:

OperationLinkObject or ResourceLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → OperationLinkObject | ResourceLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.PatchRequest(session: AnySession, path: str, properties: dict, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to update custom properties of a resource.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • path – path to the resource

  • properties – dict, custom properties to update

  • fields – list of keys to be included in the response

Returns:

ResourceObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → ResourceObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.PublishRequest(session: AnySession, path: str, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to make a resource public.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • path – path to the resource to be published

  • fields – list of keys to be included in the response

Returns:

ResourceLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → ResourceLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.RestoreTrashRequest(session: AnySession, path: str, dst_path: str | None = None, force_async: bool = False, overwrite: bool = False, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to restore trash.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • path – path to the trash resource to be restored

  • dst_path – destination path

  • force_async – forces the operation to be executed asynchronously

  • overwrite – bool, determines whether the destination can be overwritten

  • fields – list of keys to be included in the response

Returns:

ResourceLinkObject or OperationLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → OperationLinkObject | ResourceLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.SaveToDiskRequest(session: AnySession, public_key: str, name: str | None = None, path: str | None = None, save_path: str | None = None, force_async: bool = False, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to save a public resource to the disk.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • public_key – public key or public URL of the resource

  • name – filename of the saved resource

  • path – path to the copied resource in the public folder

  • save_path – path to the destination directory (downloads directory by default)

  • force_async – forces the operation to be executed asynchronously

  • fields – list of keys to be included in the response

Returns:

ResourceLinkObject or OperationLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → OperationLinkObject | ResourceLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.UnpublishRequest(session: AnySession, path: str, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to make a public resource private.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • path – path to the resource to be unpublished

  • fields – list of keys to be included in the response

Returns:

ResourceLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → ResourceLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.resources.UploadURLRequest(session: AnySession, url: str, path: str, disable_redirects: bool = False, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to upload a file from URL.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • url – source URL

  • path – destination path

  • disable_redirects – bool, forbid redirects

  • fields – list of keys to be included in the response

Returns:

OperationLinkObject

process_json(js: dict | None, yadisk: AnyClient | None = None) → OperationLinkObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything

class yadisk.api.operations.GetOperationStatusRequest(session: AnySession, operation_id: str, fields: Iterable[str] | None = None, **kwargs)[source]

Bases: APIRequest

A request to get operation status.

Parameters:

  • session – an instance of Session or AsyncSession with prepared headers

  • operation_id – operation ID or link

  • fields – list of keys to be included in the response

Returns:

OperationStatusObject

process_json(js: dict | None) → OperationStatusObject[source]

Process the JSON response.

Parameters:

  • js – dict or None, JSON response

  • kwargs – extra arguments (optional)

Returns:

processed response, can be anything