Synchronous API
- class yadisk.Client(id: str = '', secret: str = '', token: str = '', *, default_args: dict[str, Any] | None = None, session: Session | Literal['httpx'] | Literal['pycurl'] | Literal['requests'] | None = None, open_file: Callable[[str | bytes, Literal['rb'] | Literal['wb']], BinaryIO] | None = None, session_factory: Callable[[], Session] | None = None)[source]
Implements access to Yandex.Disk REST API (provides synchronous API).
HTTP client implementation can be specified using the
session
parameter.RequestsSession
is used by default. For other options, see Available Session Implementations.Almost all methods of
Client
(the ones that accept **kwargs) accept some additional arguments:n_retries - int, maximum number of retries for a request
retry_interval - float, delay between retries (in seconds)
headers - dict or None, additional request headers
timeout - tuple (
(<connect timeout>, <read timeout>)
) or float (specifies both connect and read timeout), request timeout (in seconds)
Additional parameters, specific to a given HTTP client library can also be passed, see documentation for specific
Session
subclasses (Available Session Implementations).- Parameters:
id – application ID
secret – application secret password
token – application token
default_args – dict or None, default arguments for methods. Can be used to set the default timeout, headers, etc.
session –
None, str or an instance of
Session
. Ifsession
is a string, the appropriate session class will be imported, it must be one of the following values:"httpx"
-HTTPXSession
"pycurl"
-PycURLSession
"requests"
-RequestsSession
open_file – None or a function that opens a file for reading or writing (
open()
by default)session_factory – kept for compatibility, callable that returns an instance of
Session
- Variables:
id – str, application ID
secret – str, application secret password
token – str, application token
default_args – dict, default arguments for methods. Can be used to set the default timeout, headers, etc.
session – current session (
Session
instance)open_file – function that opens a file for reading or writing (
open()
by default)
The following exceptions may be raised by most API requests:
- Raises:
RequestError – HTTP client raised an exception while making a request
BadRequestError – server returned HTTP code 400
FieldValidationError – request contains fields with invalid data
UnauthorizedError – server returned HTTP code 401
ForbiddenError – server returned HTTP code 403
NotAcceptableError – server returned HTTP code 406
ConflictError – server returned HTTP code 409
PayloadTooLargeError – server returned code 413
UnsupportedMediaError – server returned HTTP code 415
LockedError – server returned HTTP code 423
TooManyRequestsError – server returned HTTP code 429
InternalServerError – server returned HTTP code 500
BadGatewayError – server returned HTTP code 502
UnavailableError – server returned HTTP code 503
GatewayTimeoutError – server returned HTTP code 504
InsufficientStorageError – server returned HTTP code 509
UnknownYaDiskError – other unknown error
- check_token(token: str | None = None, /, **kwargs) bool [source]
Check whether the token is valid.
- Parameters:
token – token to check, equivalent to self.token if None
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
- Returns:
bool
- close() None [source]
Closes the session. Do not call this method while there are other active threads using this object.
This method can also be called implicitly by using the with statement.
- copy(src_path: str, dst_path: str, /, **kwargs) SyncResourceLinkObject | SyncOperationLinkObject [source]
Copy src_path to dst_path. If the operation is performed asynchronously, returns the link to the operation, otherwise, returns the link to the newly created resource.
- Parameters:
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
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
- Raises:
PathNotFoundError – resource was not found on Disk
PathExistsError – destination path already exists
ForbiddenError – application doesn’t have enough rights for this request
InsufficientStorageError – cannot complete request due to lack of storage space
ResourceIsLockedError – resource is locked by another request
UploadTrafficLimitExceededError – upload limit has been exceeded
- Returns:
- download(src_path: str, file_or_path: str | bytes | BinaryIO, /, **kwargs) SyncResourceLinkObject [source]
Download the file.
- Parameters:
src_path – source path
file_or_path – destination path or file-like object
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
SyncResourceLinkObject
, link to the source resource
- download_by_link(link: str, file_or_path: str | bytes | BinaryIO, /, **kwargs) None [source]
Download the file from the link.
- Parameters:
link – download link
file_or_path – destination path or file-like object
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
- download_public(public_key: str, file_or_path: str | bytes | BinaryIO, /, **kwargs) SyncPublicResourceLinkObject [source]
Download the public resource.
- Parameters:
public_key – public key or public URL of the public resource
file_or_path – destination path or file-like object
path – relative path to the resource within the public folder
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
- exists(path: str, /, **kwargs) bool [source]
Check whether path exists.
- Parameters:
path – path to the resource
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
bool
- get_auth_url(type: Literal['code'] | Literal['token'], device_id: str | None = None, device_name: str | None = None, redirect_uri: str | None = None, login_hint: str | None = None, scope: str | None = None, optional_scope: str | None = None, force_confirm: bool = True, state: str | None = None, code_challenge: str | None = None, code_challenge_method: Literal['plain'] | Literal['S256'] | None = None, display: None = None) str [source]
Get authentication URL for the user to go to. This method doesn’t send any HTTP requests and merely constructs the URL.
- Parameters:
type – response type (“code” to get the confirmation code or “token” to get the token automatically)
device_id – unique device ID, must be between 6 and 50 characters
device_name – device name, should not be longer than 100 characters
redirect_uri – the URL to redirect the user to after they allow access to the app, by default, the first redirect URI specified in the app settings is used
display – doesn’t do anything, kept for compatibility
login_hint – username or email for the account the token is being requested for
scope – str, list of permissions for the application
optional_scope – str, list of optional permissions for the application
force_confirm – if True, user will be required to confirm access to the account even if the user has already granted access for the application
state – The state string, which Yandex.OAuth returns without any changes (<= 1024 characters)
code_challenge – string derived from the generated
code_verifier
value using one of the two possible transformations (plain or S256)code_challenge_method – specifies what function was used to transform the
code_verifier
value tocode_challenge
, allowed values are"plain"
and"S256"
(recommended). If"S256"
is used,code_challenge
must be produced by hashing thecode_verifier
value and encoding it to base64
- Raises:
ValueError – invalid arguments were passed
- Returns:
authentication URL
- get_code_url(device_id: str | None = None, device_name: str | None = None, redirect_uri: str | None = None, login_hint: str | None = None, scope: str | None = None, optional_scope: str | None = None, force_confirm: bool = True, state: str | None = None, code_challenge: str | None = None, code_challenge_method: Literal['plain'] | Literal['S256'] | None = None, display: None = None) str [source]
Get the URL for the user to get the confirmation code. The confirmation code can later be used to get the token. This method doesn’t send any HTTP requests and merely constructs the URL.
- Parameters:
device_id – unique device ID, must be between 6 and 50 characters
device_name – device name, should not be longer than 100 characters
redirect_uri – the URL to redirect the user to after they allow access to the app, by default, the first redirect URI specified in the app settings is used
display – doesn’t do anything, kept for compatibility
login_hint – username or email for the account the token is being requested for
scope – str, list of permissions for the application
optional_scope – str, list of optional permissions for the application
force_confirm – if True, user will be required to confirm access to the account even if the user has already granted access for the application
state – The state string, which Yandex.OAuth returns without any changes (<= 1024 characters)
code_challenge – string derived from the generated
code_verifier
value using one of the two possible transformations (plain or S256)code_challenge_method – specifies what function was used to transform the
code_verifier
value tocode_challenge
, allowed values are"plain"
and"S256"
(recommended). If"S256"
is used,code_challenge
must be produced by hashing thecode_verifier
value and encoding it to base64
- Raises:
ValueError – invalid arguments were passed
- Returns:
authentication URL
- get_device_code(**kwargs) DeviceCodeObject [source]
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 using theClient.get_token_from_device_code()
.- Parameters:
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
- Raises:
InvalidClientError – invalid client ID
BadRequestError – invalid request parameters
- Returns:
DeviceCodeObject
containinguser_code
anddevice_code
- get_disk_info(**kwargs) DiskInfoObject [source]
Get disk information.
- Parameters:
fields – list of keys to be included in the response
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
- get_download_link(path: str, /, **kwargs) str [source]
Get a download link for a file (or a directory).
- Parameters:
path – path to the resource
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
str
- get_files(**kwargs) Generator[SyncResourceObject, None, None] [source]
Get a flat list of all files (that doesn’t include directories).
- Parameters:
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
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
generator of
ResourceObject
- get_last_uploaded(**kwargs) Generator[SyncResourceObject, None, None] [source]
Get the list of latest uploaded files sorted by upload date.
- Parameters:
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
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
generator of
ResourceObject
- get_meta(path: str, /, **kwargs) SyncResourceObject [source]
Get meta information about a file/directory.
- Parameters:
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
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
- get_operation_status(operation_id: str, /, **kwargs) str [source]
Get operation status.
- Parameters:
operation_id – ID of the operation or a link
fields – list of keys to be included in the response
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
- Raises:
OperationNotFoundError – requested operation was not found
- Returns:
str,
"in-progress"
indicates that the operation is currently running,"success"
indicates that the operation was successful,"failed"
means that the operation failed
- get_public_download_link(public_key: str, /, **kwargs) str [source]
Get a download link for a public resource.
- Parameters:
public_key – public key or public URL of the public resource
path – relative path to the resource within the public folder
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
str
- get_public_meta(public_key: str, /, **kwargs) SyncPublicResourceObject [source]
Get meta-information about a public resource.
- Parameters:
public_key – public key or public URL of the public 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
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
- get_public_resources(**kwargs) SyncPublicResourcesListObject [source]
Get a list of public resources.
- Parameters:
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
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
- get_public_type(public_key: str, /, **kwargs) str [source]
Get public resource type.
- Parameters:
public_key – public key or public URL of the public resource
path – relative path to the resource within the public folder
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
“file” or “dir”
- get_token(code: str, /, **kwargs) TokenObject [source]
Get a new token.
- Parameters:
code – confirmation code
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
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
- Raises:
BadVerificationCodeError – confirmation code has invalid format
InvalidGrantError – invalid or expired confirmation code
InvalidClientError – invalid client ID or client secret
BadRequestError – invalid request parameters
- Returns:
- get_token_from_device_code(device_code: str, /, **kwargs) TokenObject [source]
Get a new token from a device code, previously obtained with
Client.get_device_code()
.- Parameters:
code – confirmation code
device_id – unique device ID (between 6 and 50 characters)
device_name – device name, should not be longer than 100 characters
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
- Raises:
AuthorizationPendingError – user has not authorized the application yet
BadVerificationCodeError –
device_code
has invalid formatInvalidGrantError – invalid or expired
device_code
InvalidClientError – invalid client ID or client secret
BadRequestError – invalid request parameters
- Returns:
- get_trash_meta(path: str, /, **kwargs) SyncTrashResourceObject [source]
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
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
- get_trash_type(path: str, /, **kwargs) str [source]
Get trash resource type.
- Parameters:
path – path to the trash resource
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
“file” or “dir”
- get_type(path: str, /, **kwargs) str [source]
Get resource type.
- Parameters:
path – path to the resource
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
“file” or “dir”
- get_upload_link(path: str, /, **kwargs) str [source]
Get a link to upload the file using the PUT request.
- Parameters:
path – destination path
overwrite – bool, determines whether to overwrite the destination
fields – list of keys to be included in the response
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
- Raises:
ParentNotFoundError – parent directory doesn’t exist
PathExistsError – destination path already exists
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
InsufficientStorageError – cannot upload file due to lack of storage space
UploadTrafficLimitExceededError – upload limit has been exceeded
- Returns:
str
- is_dir(path: str, /, **kwargs) bool [source]
Check whether path is a directory.
- Parameters:
path – path to the resource
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
True if path is a directory, False otherwise (even if it doesn’t exist)
- is_file(path: str, /, **kwargs) bool [source]
Check whether path is a file.
- Parameters:
path – path to the resource
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
True if path is a file, False otherwise (even if it doesn’t exist)
- is_public_dir(public_key: str, /, **kwargs) bool [source]
Check whether the public resource is a public directory.
- Parameters:
public_key – public key or public URL of the public resource
path – relative path to the resource within the public folder
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
True if public_key is a directory, False otherwise (even if it doesn’t exist)
- is_public_file(public_key: str, /, **kwargs) bool [source]
Check whether the public resource is a public file.
- Parameters:
public_key – public key or public URL of the public resource
path – relative path to the resource within the public folder
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
True if public_key is a file, False otherwise (even if it doesn’t exist)
- is_trash_dir(path: str, /, **kwargs) bool [source]
Check whether path is a trash directory.
- Parameters:
path – path to the trash resource
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
True if path is a directory, False otherwise (even if it doesn’t exist)
- is_trash_file(path: str, /, **kwargs) bool [source]
Check whether path is a trash file.
- Parameters:
path – path to the trash resource
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
True if path is a file, False otherwise (even if it doesn’t exist)
- listdir(path: str, /, **kwargs) Generator[SyncResourceObject, None, None] [source]
Get contents of path.
- Parameters:
path – path to the directory
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
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
WrongResourceTypeError – resource is not a directory
- Returns:
generator of
ResourceObject
- mkdir(path: str, /, **kwargs) SyncResourceLinkObject [source]
Create a new directory.
- Parameters:
path – path to the directory to be created
fields – list of keys to be included in the response
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
- Raises:
ParentNotFoundError – parent directory doesn’t exist
DirectoryExistsError – destination path already exists
InsufficientStorageError – cannot create directory due to lack of storage space
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
- move(src_path: str, dst_path: str, /, **kwargs) SyncResourceLinkObject | SyncOperationLinkObject [source]
Move src_path to dst_path.
- Parameters:
src_path – source path to be moved
dst_path – destination path
overwrite – bool, determines whether to overwrite the destination
force_async – forces the operation to be executed asynchronously
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
PathExistsError – destination path already exists
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
- patch(path: str, properties: dict, /, **kwargs) SyncResourceObject [source]
Update custom properties of a resource.
- Parameters:
path – path to the resource
properties – dict, custom properties to update
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
- public_exists(public_key: str, /, **kwargs) bool [source]
Check whether the public resource exists.
- Parameters:
public_key – public key or public URL of the public resource
path – relative path to the resource within the public folder
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
bool
- public_listdir(public_key: str, /, **kwargs) Generator[SyncPublicResourceObject, None, None] [source]
Get contents of a public directory.
- Parameters:
public_key – public key or public URL of the public resource
path – relative path to the resource in the public folder. By specifying the key of the published folder in public_key, you can request contents of any nested folder.
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
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
WrongResourceTypeError – resource is not a directory
- Returns:
generator of
SyncPublicResourceObject
- publish(path: str, /, **kwargs) SyncResourceLinkObject [source]
Make a resource public.
- Parameters:
path – path to the resource to be published
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
SyncResourceLinkObject
, link to the resource
- refresh_token(refresh_token: str, /, **kwargs) TokenObject [source]
Refresh an existing token.
- Parameters:
refresh_token – the refresh token that was received with the token
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
- Raises:
InvalidGrantError – invalid or expired refresh token or it doesn’t belong to this application
InvalidClientError – invalid client ID or client secret
BadRequestError – invalid request parameters
- Returns:
- remove(path: str, /, **kwargs) SyncOperationLinkObject | None [source]
Remove the resource.
- Parameters:
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
md5 – str, MD5 hash of the file to remove
force_async – forces the operation to be executed asynchronously
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
BadRequestError – MD5 check is only available for files
ResourceIsLockedError – resource is locked by another request
- Returns:
SyncOperationLinkObject
if the operation is performed asynchronously, None otherwise
- remove_trash(path: str, /, **kwargs) SyncOperationLinkObject | None [source]
Remove a trash resource.
- Parameters:
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
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
SyncOperationLinkObject
if the operation is performed asynchronously, None otherwise
- rename(src_path: str, new_name: str, /, **kwargs) SyncResourceLinkObject | SyncOperationLinkObject [source]
Rename src_path to have filename new_name. Does the same as move() but changes only the filename.
- Parameters:
src_path – source path to be moved
new_name – target filename to rename to
overwrite – bool, determines whether to overwrite the destination
force_async – forces the operation to be executed asynchronously
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
PathExistsError – destination path already exists
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
ValueError – new_name is not a valid filename
- Returns:
- restore_trash(path: str, /, dst_path: str | None = None, **kwargs) SyncResourceLinkObject | SyncOperationLinkObject [source]
Restore a trash resource. Returns a link to the newly created resource or a link to the asynchronous operation.
- Parameters:
path – path to the trash resource to be restored
dst_path – destination path
overwrite – bool, determines whether the destination can be overwritten
force_async – forces the operation to be executed asynchronously
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
PathExistsError – destination path already exists
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
- revoke_token(token: str | None = None, /, **kwargs) TokenRevokeStatusObject [source]
Revoke the token.
- Parameters:
token – token to revoke
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
- Raises:
InvalidGrantError – specified token doesn’t belong to this application
InvalidClientError – invalid client ID or client secret
UnsupportedTokenTypeError – token could not be revoked because it doesn’t have a
device_id
BadRequestError – invalid request parameters
- Returns:
- save_to_disk(public_key: str, /, **kwargs) SyncResourceLinkObject | SyncOperationLinkObject [source]
Saves a public resource to the disk. Returns the link to the operation if it’s performed asynchronously, or a link to the resource otherwise.
- Parameters:
public_key – public key or public URL of the public 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
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
InsufficientStorageError – cannot upload file due to lack of storage space
UploadTrafficLimitExceededError – upload limit has been exceeded
- Returns:
- trash_exists(path: str, /, **kwargs) bool [source]
Check whether the trash resource at path exists.
- Parameters:
path – path to the trash resource
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
- Raises:
ForbiddenError – application doesn’t have enough rights for this request
- Returns:
bool
- trash_listdir(path: str, /, **kwargs) Generator[SyncTrashResourceObject, None, None] [source]
Get contents of a trash resource.
- Parameters:
path – path to the directory in the trash bin
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
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
WrongResourceTypeError – resource is not a directory
- Returns:
generator of
SyncTrashResourceObject
- unpublish(path: str, /, **kwargs) SyncResourceLinkObject [source]
Make a public resource private.
- Parameters:
path – path to the resource to be unpublished
fields – list of keys to be included in the response
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
- Raises:
PathNotFoundError – resource was not found on Disk
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
- Returns:
- upload(file_or_path: str | bytes | BinaryIO | Callable[[], Iterator[bytes]], dst_path: str, /, **kwargs) SyncResourceLinkObject [source]
Upload a file to disk.
- Parameters:
file_or_path – path, file-like object to be uploaded or a function that returns an iterator (or generator)
dst_path – destination path
overwrite – if True, the resource will be overwritten if it already exists, an error will be raised otherwise
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
- Raises:
ParentNotFoundError – parent directory doesn’t exist
PathExistsError – destination path already exists
InsufficientStorageError – cannot upload file due to lack of storage space
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
UploadTrafficLimitExceededError – upload limit has been exceeded
- Returns:
SyncResourceLinkObject
, link to the destination resource
- upload_by_link(file_or_path: str | bytes | BinaryIO | Callable[[], Iterator[bytes]], link: str, /, **kwargs) None [source]
Upload a file to disk using an upload link.
- Parameters:
file_or_path – path, file-like object to be uploaded or a function that returns an iterator (or generator)
link – upload link
overwrite – if True, the resource will be overwritten if it already exists, an error will be raised otherwise
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
- Raises:
InsufficientStorageError – cannot upload file due to lack of storage space
- upload_url(url: str, path: str, /, **kwargs) SyncOperationLinkObject [source]
Upload a file from URL.
- Parameters:
url – source URL
path – destination path
disable_redirects – bool, forbid redirects
fields – list of keys to be included in the response
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
- Raises:
ParentNotFoundError – parent directory doesn’t exist
PathExistsError – destination path already exists
InsufficientStorageError – cannot upload file due to lack of storage space
ForbiddenError – application doesn’t have enough rights for this request
ResourceIsLockedError – resource is locked by another request
UploadTrafficLimitExceededError – upload limit has been exceeded
- Returns:
SyncOperationLinkObject
, link to the asynchronous operation