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()
- 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 thedevice_code
for the token.- Parameters:
session – an instance of
Session
orAsyncSession
with prepared headersclient_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
- 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
orAsyncSession
with prepared headerscode – 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:
- 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
orAsyncSession
with prepared headersrefresh_token – the refresh token that was received with the original token
client_id – application ID
client_secret – application secret password
- Returns:
- 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
orAsyncSession
with prepared headerstoken – the token to be revoked
client_id – application ID
client_secret – application secret password
- Returns:
- 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
orAsyncSession
with prepared headersfields – list of keys to be included in the response
- Returns:
- 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
orAsyncSession
with prepared headerssrc_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:
- 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
orAsyncSession
with prepared headerspath – 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
- 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
orAsyncSession
with prepared headerspath – 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
- 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
orAsyncSession
with prepared headersoffset – 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:
- 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
orAsyncSession
with prepared headerspath – path to the resource to be downloaded
fields – list of keys to be included in the response
- Returns:
- 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
orAsyncSession
with prepared headerspath – 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:
- 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
orAsyncSession
with prepared headerspublic_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:
- 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
orAsyncSession
with prepared headerspublic_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:
- 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
orAsyncSession
with prepared headersoffset – 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:
- 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:
- 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
orAsyncSession
with prepared headerspath – path to be uploaded at
overwrite – bool, determines whether to overwrite the destination
fields – list of keys to be included in the response
- Returns:
- 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
orAsyncSession
with prepared headerslimit – 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:
- 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:
- 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
orAsyncSession
with prepared headerssrc_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:
- 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
orAsyncSession
with prepared headerspath – path to the resource
properties – dict, custom properties to update
fields – list of keys to be included in the response
- Returns:
- 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
orAsyncSession
with prepared headerspath – path to the resource to be published
fields – list of keys to be included in the response
- Returns:
- 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
orAsyncSession
with prepared headerspath – 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:
- 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
orAsyncSession
with prepared headerspublic_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:
- 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
orAsyncSession
with prepared headerspath – path to the resource to be unpublished
fields – list of keys to be included in the response
- Returns:
- 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
orAsyncSession
with prepared headersurl – source URL
path – destination path
disable_redirects – bool, forbid redirects
fields – list of keys to be included in the response
- Returns:
- 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
orAsyncSession
with prepared headersoperation_id – operation ID or link
fields – list of keys to be included in the response
- Returns:
- 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