Синхронный 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)[исходный код]

Реализует доступ к REST API Яндекс.Диска (предоставляет синхронный API).

Реализация HTTP-клиента может быть указана с помощью параметра session. По умолчанию используется RequestsSession. см. Доступные реализации сессий для других списка других доступных вариантов.

Почти все методы Client (те, которые принимают **kwargs) принимают некоторые дополнительные параметры:

  • n_retries - int, максимальное число повторных попыток запроса

  • retry_interval - float, задержка между повторными попытками (в секундах)

  • headers - dict или None, дополнительные заголовки запроса

  • timeout - tuple ((<connect timeout>, <read timeout>)) или float (указывает одновременно и connect и read timeout), таймаут запроса в секундах

Дополнительные параметры, относящиеся к конкретной HTTP библиотеке могут также быть переданы, см. документацию для конкретных подклассов Session (Доступные реализации сессий).

Параметры:

  • id – идентификатор приложения

  • secret – пароль приложения

  • token – токен

  • default_args – dict или None, аргументы по умолчанию для методов. Можно использовать, чтобы задать стандартный таймаут, заголовки и т.д.

  • session – None, str или объект Session. Если session - строка, то нужный класс будет автоматически импортирован, допустимые значения: * "httpx" - HTTPXSession * "pycurl" - PycURLSession * "requests" - RequestsSession

  • open_file – None или функция, которая открывает файл для чтения или записи (open() по умолчанию)

  • session_factory – оставлен для совместимости, функция, возвращающая объект Session

Переменные:

  • id – str, идентификатор приложения

  • secret – str, пароль приложения

  • token – str, токен

  • default_args – dict, аргументы по умолчанию для методов. Можно использовать, чтобы задать стандартный таймаут, заголовки и т.д.

  • session – текущая сессия (объект Session)

  • open_file – функция, которая открывает файл для чтения или записи (open() по умолчанию)

Большинство запросов к API могут вызвать следующие исключения:

Исключение:
check_token(token: str | None = None, /, **kwargs) → bool[исходный код]

Проверяет, действителен ли токен.

Параметры:

  • token – токен, подлежащий проверке, то же самое, что self.token при None

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Результат:

bool

close() → None[исходный код]

Закрывает сессию. Не вызывайте этот метод, пока другие потоки используют этот объект.

Этот метод может также быть вызван неявно с помощью конструкции with.

copy(src_path: str, dst_path: str, /, **kwargs) → SyncResourceLinkObject | SyncOperationLinkObject[исходный код]

Копирует src_path в dst_path. Если операция выполняется асинхронно, возвращает ссылку на операцию, иначе, возвращает ссылку на новый ресурс.

Параметры:

  • src_path – исходный путь

  • dst_path – путь назначения

  • overwrite – если True, путь назначения может быть перезаписан, иначе будет вызвана ошибка

  • force_async – заставляет выполнять операцию асинхронно

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • PathExistsError – путь назначения уже существует

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • InsufficientStorageError – невозможно выполнить запрос из-за нехватки свободного места на Диске

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

  • UploadTrafficLimitExceededError – достигнут лимит на загрузку файлов

Результат:

SyncResourceLinkObject или SyncOperationLinkObject

download(src_path: str, file_or_path: str | bytes | BinaryIO, /, **kwargs) → SyncResourceLinkObject[исходный код]

Скачивает файл.

Параметры:

  • src_path – исходный путь

  • file_or_path – путь назначения или файл-подобный объект

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

SyncResourceLinkObject, ссылка на исходный ресурс

Скачивает файл по уже полученной ссылке.

Параметры:

  • link – ссылка для скачивания

  • file_or_path – путь назначения или файл-подобный объект

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

download_public(public_key: str, file_or_path: str | bytes | BinaryIO, /, **kwargs) → SyncPublicResourceLinkObject[исходный код]

Скачивает публичный ресурс.

Параметры:

  • public_key – публичный ключ или URL к публичному ресурсу

  • file_or_path – путь назначения или файл-подобный объект

  • path – относительный путь к ресурсу внутри публичной папки

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

SyncPublicResourceLinkObject

exists(path: str, /, **kwargs) → bool[исходный код]

Проверяет, существует ли path.

Параметры:

  • path – путь к ресурсу

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

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[исходный код]

Получает URL для аутентификации для пользователя. Данный метод не отправляет никаких HTTP запросов.

Параметры:

  • type – тип ответа («code», чтобы получить код подтверждения или «token», чтобы получить токен автоматически)

  • device_id – уникальный идентификатор устройства, от 6 до 50 символов

  • device_name – имя устройства, не более 100 символов

  • redirect_uri – URL на который пользователь будет перенаправлен после предоставления доступа приложению, по умолчанию используется первый URI, указанный в настройках приложения

  • display – ничего не делает, оставлен для совместимости

  • login_hint – username или email аккаунта, для которого будет получен токен

  • scope – str, список разрешений для приложения

  • optional_scope – str, список опциональных разрешений для приложения

  • force_confirm – Если True, пользователь должен будет разрешить доступ к аккаунту, даже если он уже это сделал до этого

  • state – Строка состояния, которую Яндекс.OAuth возвращает без изменений (<= 1024 символов)

  • code_challenge – строка, полученная из сгенерированного значения code_verifier с помощью одного из двух возможных преобразований (plain или S256)

  • code_challenge_method – Указывает функцию, которая будет использована для преобразования значения code_verifier, возможные значения: "plain" и "S256" (рекомендуется). Если используется "S256", значение code_challenge должно быть получено путём хэширования значения code_verifier и кодирования в base64

Исключение:

ValueError – были переданы неправильные аргументы

Результат:

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[исходный код]

Получает URL для получения пользователем кода подтверждения. Он может быть использован для получения токена. Данный метод не отправляет никаких HTTP запросов.

Параметры:

  • device_id – уникальный идентификатор устройства, от 6 до 50 символов

  • device_name – имя устройства, не более 100 символов

  • redirect_uri – URL на который пользователь будет перенаправлен после предоставления доступа приложению, по умолчанию используется первый URI, указанный в настройках приложения

  • display – ничего не делает, оставлен для совместимости

  • login_hint – username или email аккаунта, для которого будет получен токен

  • scope – str, список разрешений для приложения

  • optional_scope – str, список опциональных разрешений для приложения

  • force_confirm – Если True, пользователь должен будет разрешить доступ к аккаунту, даже если он уже это сделал до этого

  • state – Строка состояния, которую Яндекс.OAuth возвращает без изменений (<= 1024 символов)

  • code_challenge – строка, полученная из сгенерированного значения code_verifier с помощью одного из двух возможных преобразований (plain или S256)

  • code_challenge_method – Указывает функцию, которая будет использована для преобразования значения code_verifier, возможные значения: "plain" и "S256" (рекомендуется). Если используется "S256", значение code_challenge должно быть получено путём хэширования значения code_verifier и кодирования в base64

Исключение:

ValueError – были переданы неправильные аргументы

Результат:

URL для аутентификации

get_device_code(**kwargs) → DeviceCodeObject[исходный код]

Данный запрос используется для авторизации с помощью страницы Яндекс OAuth. В данном случае пользователь должен ввести код подтверждения (user_code) в браузере на странице Яндекс OAuth. После того как пользователь ввёл код, приложение может обменять device_code на токен с помощью метода Client.get_token_from_device_code().

Параметры:

  • device_id – уникальный идентификатор устройства (между 6 и 50 символами)

  • device_name – имя устройства, не более 100 символов

  • scope – str, список разрешений для приложения

  • optional_scope – str, список опциональных разрешений для приложения

Исключение:

  • InvalidClientError – неправильный идентификатор приложения

  • BadRequestError – неправильные параметры запроса

Результат:

DeviceCodeObject, содержащий user_code и device_code

get_disk_info(**kwargs) → DiskInfoObject[исходный код]

Получает информацию о диске.

Параметры:

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

DiskInfoObject

Получает ссылку на скачивание файла (или папки).

Параметры:

  • path – путь к ресурсу

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

str

get_files(**kwargs) → Generator[SyncResourceObject, None, None][исходный код]

Получить плоский список всех файлов (без папок).

Параметры:

  • offset – отступ от начала списка

  • limit – максимальное количество элементов списка

  • media_type – тип файлов, которые будут включены в список

  • sort – str, поле использумое для сортировки вложенных ресурсов

  • preview_size – размер превью файла

  • preview_crop – bool, обрезает превью согласно размеру, заданному в preview_size

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

генератор ResourceObject

get_last_uploaded(**kwargs) → Generator[SyncResourceObject, None, None][исходный код]

Получает список последних загруженных файлов, отсортированный по дате загрузки.

Параметры:

  • limit – максимальное число элементов в списке

  • media_type – тип файлов, которые будут включены в список

  • preview_size – размер превью файла

  • preview_crop – bool, обрезает превью согласно размеру, заданному в preview_size

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

генератор ResourceObject

get_meta(path: str, /, **kwargs) → SyncResourceObject[исходный код]

Получает мета-информацию о ресурсе.

Параметры:

  • path – путь к ресурсу

  • limit – количество ресурсов в папке, которые будут включены в ответ

  • offset – количество ресурсов в папке, которые будут пропущены

  • preview_size – размер превью файла

  • preview_crop – bool, обрезает превью согласно размеру, заданному в preview_size

  • sort – str, поле использумое для сортировки вложенных ресурсов

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

SyncResourceObject

get_operation_status(operation_id: str, /, **kwargs) → str[исходный код]

Получает статус операции.

Параметры:

  • operation_id – идентификатор операции или ссылка на нее

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

OperationNotFoundError – указанная операция не найдена

Результат:

str, "in-progress" означает, что операция в процессе, "success" означает, что операция успешно завершилась, "failed" означает, что операция завершилась с ошибкой

Получает ссылку на скачивание публичного ресурса.

Параметры:

  • public_key – публичный ключ или URL к публичному ресурсу

  • path – относительный путь к ресурсу внутри публичной папки

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

str

get_public_meta(public_key: str, /, **kwargs) → SyncPublicResourceObject[исходный код]

Получает мета-информацию о публичном ресурсе.

Параметры:

  • public_key – публичный ключ или URL к публичному ресурсу

  • path – относительный путь к ресурсу внутри публичной папки. Указывая ключ опубликованной папки через public_key, вы можете запросить метаинформацию любого ресурса внутри неё.

  • offset – отступ от начала списка вложенных ресурсов

  • limit – максимальное количество элементов списка вложенных ресурсов

  • sort – str, поле использумое для сортировки вложенных ресурсов

  • preview_size – размер превью файла

  • preview_crop – bool, разрешить обрезку превью

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

SyncPublicResourceObject

get_public_resources(**kwargs) → SyncPublicResourcesListObject[исходный код]

Получает список публичных ресурсов.

Параметры:

  • offset – отступ от начала списка

  • limit – максимальное число элементов в списке

  • preview_size – размер превью файла

  • preview_crop – bool, обрезает превью согласно размеру, заданному в preview_size

  • type – фильтр по типу ресурса («file» или «dir»)

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

SyncPublicResourceObject

get_public_type(public_key: str, /, **kwargs) → str[исходный код]

Получает тип публичного ресурса.

Параметры:

  • public_key – публичный ключ или URL к публичному ресурсу

  • path – относительный путь к ресурсу внутри публичной папки

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

«file» или «dir»

get_token(code: str, /, **kwargs) → TokenObject[исходный код]

Получает новый токен.

Параметры:

  • code – код подтверждения

  • device_id – уникальный идентификатор устройства (между 6 и 50 символами)

  • device_name – имя устройства, не более 100 символов

  • code_verifier – str, код верификатора, используемый при авторизации с PKCE

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • BadVerificationCodeError – неправильный формат кода подтверждения

  • InvalidGrantError – неправильный или истекший код

  • InvalidClientError – неправильный идентификатор или пароль приложения

  • BadRequestError – неправильные параметры запроса

Результат:

TokenObject

get_token_from_device_code(device_code: str, /, **kwargs) → TokenObject[исходный код]

Получает новый токен с помощью кода устройства (device_code), полученногос помощью Client.get_device_code()

Параметры:

  • code – код подтверждения

  • device_id – уникальный идентификатор устройства (между 6 и 50 символами)

  • device_name – имя устройства, не более 100 символов

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:
Результат:

TokenObject

get_trash_meta(path: str, /, **kwargs) → SyncTrashResourceObject[исходный код]

Получает мета-информацию о ресурсе корзины.

Параметры:

  • path – путь к ресурсу корзины

  • limit – количество ресурсов в папке, которые будут включены в ответ

  • offset – количество ресурсов в папке, которые будут пропущены

  • preview_size – размер превью файла

  • preview_crop – bool, обрезает превью согласно размеру, заданному в preview_size

  • sort – str, поле использумое для сортировки вложенных ресурсов

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

SyncTrashResourceObject

get_trash_type(path: str, /, **kwargs) → str[исходный код]

Получает тип ресурса корзины.

Параметры:

  • path – путь к ресурсу корзины

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

«file» или «dir»

get_type(path: str, /, **kwargs) → str[исходный код]

Получает тип ресурса

Параметры:

  • path – путь к ресурсу

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

«file» или «dir»

Получает ссылку для загрузки файла на диск при помощи PUT запроса.

Параметры:

  • path – путь назначения

  • overwrite – bool, определяет, перезаписывать путь назначения или нет

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • ParentNotFoundError – родительская папка не существует

  • PathExistsError – путь назначения уже существует

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

  • InsufficientStorageError – невозможно загрузить файл из-за нехватки места на Диске

  • UploadTrafficLimitExceededError – достигнут лимит на загрузку файлов

Результат:

str

is_dir(path: str, /, **kwargs) → bool[исходный код]

Проверяет, является ли path папкой.

Параметры:

  • path – путь к ресурсу

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

True, если path является папкой, False, в остальных случаях (даже если ресурс не существует)

is_file(path: str, /, **kwargs) → bool[исходный код]

Проверяет, является ли path файлом.

Параметры:

  • path – путь к ресурсу

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

True, если path является файлом, False, в остальных случаях (даже если ресурс не существует)

is_public_dir(public_key: str, /, **kwargs) → bool[исходный код]

Проверяет, является ли публичный ресурс публичной папкой.

Параметры:

  • public_key – публичный ключ или URL к публичному ресурсу

  • path – относительный путь к ресурсу внутри публичной папки

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

True, если public_key является папкой, False, в остальных случаях (даже если ресурс не существует)

is_public_file(public_key: str, /, **kwargs) → bool[исходный код]

Проверяет, является ли публичный ресурс публичным файлом.

Параметры:

  • public_key – публичный ключ или URL к публичному ресурсу

  • path – относительный путь к ресурсу внутри публичной папки

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

True, если public_key является файлом, False, в остальных случаях (даже если ресурс не существует)

is_trash_dir(path: str, /, **kwargs) → bool[исходный код]

Проверяет, является ли path папкой в корзине.

Параметры:

  • path – путь к ресурсу корзины

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

True, если path является папкой, False, в остальных случаях (даже если ресурс не существует)

is_trash_file(path: str, /, **kwargs) → bool[исходный код]

Проверяет, является ли path файлом в корзине.

Параметры:

  • path – путь к ресурсу корзины

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

True, если path является файлом, False, в остальных случаях (даже если ресурс не существует)

listdir(path: str, /, **kwargs) → Generator[SyncResourceObject, None, None][исходный код]

Получает содержимое path.

Параметры:

  • path – путь к папке

  • limit – количество ресурсов в папке, которые будут включены в ответ

  • offset – количество ресурсов в папке, которые будут пропущены

  • preview_size – размер превью файла

  • preview_crop – bool, обрезает превью согласно размеру, заданному в preview_size

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • WrongResourceTypeError – указанный ресурс не является папкой

Результат:

генератор ResourceObject

mkdir(path: str, /, **kwargs) → SyncResourceLinkObject[исходный код]

Создаёт новую папку.

Параметры:

  • path – путь к папке, подлежащей созданию

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • ParentNotFoundError – родительская папка не существует

  • DirectoryExistsError – путь назначения уже существует

  • InsufficientStorageError – невозможно создать папку из-за нехватки места на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

SyncResourceLinkObject

move(src_path: str, dst_path: str, /, **kwargs) → SyncResourceLinkObject | SyncOperationLinkObject[исходный код]

Перемещает src_path в dst_path.

Параметры:

  • src_path – исходный путь, подлежащий перемещению

  • dst_path – путь назначения

  • overwrite – bool, определяет, перезаписывать путь назначения или нет

  • force_async – заставляет выполнять операцию асинхронно

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • PathExistsError – путь назначения уже существует

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

SyncResourceLinkObject или SyncOperationLinkObject

patch(path: str, properties: dict, /, **kwargs) → SyncResourceObject[исходный код]

Обновляет пользовательские свойства ресурса.

Параметры:

  • path – путь к ресурсу

  • properties – dict, новые пользовательские свойства ресурса

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

ResourceObject

public_exists(public_key: str, /, **kwargs) → bool[исходный код]

Проверяет, существует ли публичный ресурс.

Параметры:

  • public_key – публичный ключ или URL к публичному ресурсу

  • path – относительный путь к ресурсу внутри публичной папки

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

bool

public_listdir(public_key: str, /, **kwargs) → Generator[SyncPublicResourceObject, None, None][исходный код]

Получает содержимое публичной папки.

Параметры:

  • public_key – публичный ключ или URL к публичному ресурсу

  • path – относительный путь к ресурсу в публичной папке. Указывая ключ опубликованной папки через public_key, вы можете запросить содержимое любой вложенной папки.

  • limit – количество ресурсов в папке, которые будут включены в ответ

  • offset – количество ресурсов в папке, которые будут пропущены

  • preview_size – размер превью файла

  • preview_crop – bool, обрезает превью согласно размеру, заданному в preview_size

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • WrongResourceTypeError – указанный ресурс не является папкой

Результат:

генератор SyncPublicResourceObject

publish(path: str, /, **kwargs) → SyncResourceLinkObject[исходный код]

Делает ресурс публичным.

Параметры:

  • path – путь к публикуемому ресурсу

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

SyncResourceLinkObject, ссылка на ресурс

refresh_token(refresh_token: str, /, **kwargs) → TokenObject[исходный код]

Обновляет существующий токен.

Параметры:

  • refresh_token – refresh-токен, полученный вместе с токеном

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • InvalidGrantError – неправильный или истекший refresh-токен или он не принадлежит этому приложению

  • InvalidClientError – неправильный идентификатор или пароль приложения

  • BadRequestError – неправильные параметры запроса

Результат:

TokenObject

remove(path: str, /, **kwargs) → SyncOperationLinkObject | None[исходный код]

Удаляет ресурс.

Параметры:

  • path – путь к удаляемому ресурсу

  • permanently – если True, ресурс будет безвозвратно удалён, иначе ресурс будет перемещён в корзину

  • md5 – str, MD5 хэш файла, подлежащего удалению

  • force_async – заставляет выполнять операцию асинхронно

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • BadRequestError – проверка MD5 доступна только для файлов

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

SyncOperationLinkObject, если операция выполняется асинхронно, иначе None

remove_trash(path: str, /, **kwargs) → SyncOperationLinkObject | None[исходный код]

Удаляет ресурс корзины.

Параметры:

  • path – путь к ресурсу корзины, подлежащий удалению

  • force_async – заставляет выполнять операцию асинхронно

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

SyncOperationLinkObject, если операция выполняется асинхронно, иначе None

rename(src_path: str, new_name: str, /, **kwargs) → SyncResourceLinkObject | SyncOperationLinkObject[исходный код]

Переименовывает src_path в new_name. Делает то же самое, что и move(), за исключением того, что меняет только имя файла.

Параметры:

  • src_path – исходный путь, подлежащий перемещению

  • new_name – новое имя файла, в которое следует переименовать ресурс

  • overwrite – bool, определяет, перезаписывать путь назначения или нет

  • force_async – заставляет выполнять операцию асинхронно

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • PathExistsError – путь назначения уже существует

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

  • ValueError – new_name не является допустимым именем файла

Результат:

SyncResourceLinkObject или SyncOperationLinkObject

restore_trash(path: str, /, dst_path: str | None = None, **kwargs) → SyncResourceLinkObject | SyncOperationLinkObject[исходный код]

Восстанавливает ресурс корзины. Возвращает ссылку на новый ресурс или ссылку на асинхронную операцию.

Параметры:

  • path – путь к восстанавливаему ресурсу

  • dst_path – путь назначения

  • overwrite – bool, определяет может ли путь назначения быть перезаписан

  • force_async – заставляет выполнять операцию асинхронно

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • PathExistsError – путь назначения уже существует

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

SyncResourceLinkObject или SyncOperationLinkObject

revoke_token(token: str | None = None, /, **kwargs) → TokenRevokeStatusObject[исходный код]

Отзывает токен.

Параметры:

  • token – токен, подлежащий отзыву

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • InvalidGrantError – указанный токен не принадлежит данному приложению

  • InvalidClientError – неправильный идентификатор или пароль приложения

  • UnsupportedTokenTypeError – не удалось отозвать токен, потому что у него нет device_id

  • BadRequestError – неправильные параметры запроса

Результат:

TokenRevokeStatusObject

save_to_disk(public_key: str, /, **kwargs) → SyncResourceLinkObject | SyncOperationLinkObject[исходный код]

Сохраняет публичный ресурс на диск. Возвращает ссылку на операцию, если сохранение выполняется асинхронно, или возвращает ссылку на ресурс.

Параметры:

  • public_key – публичный ключ или URL к публичному ресурсу

  • name – имя файла/папки, под которым будет сохранён ресурс

  • path – путь к копируемому ресурсу в публичной папке

  • save_path – путь к папке назначения (загрузки по умолчанию)

  • force_async – заставляет выполнять операцию асинхронно

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

  • InsufficientStorageError – невозможно загрузить файл из-за нехватки места на Диске

  • UploadTrafficLimitExceededError – достигнут лимит на загрузку файлов

Результат:

SyncResourceLinkObject или SyncOperationLinkObject

trash_exists(path: str, /, **kwargs) → bool[исходный код]

Проверяет, существует ли path в корзине.

Параметры:

  • path – путь к ресурсу корзины

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

Результат:

bool

trash_listdir(path: str, /, **kwargs) → Generator[SyncTrashResourceObject, None, None][исходный код]

Получает содержимое папки в корзине.

Параметры:

  • path – путь к папке в корзине

  • limit – количество ресурсов в папке, которые будут включены в ответ

  • offset – количество ресурсов в папке, которые будут пропущены

  • preview_size – размер превью файла

  • preview_crop – bool, обрезает превью согласно размеру, заданному в preview_size

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • WrongResourceTypeError – указанный ресурс не является папкой

Результат:

генератор SyncTrashResourceObject

unpublish(path: str, /, **kwargs) → SyncResourceLinkObject[исходный код]

Делает публичный ресурс приватным.

Параметры:

  • path – путь к ресурсу, подлежащему депубликации

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • PathNotFoundError – ресурс не был найден на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

Результат:

SyncResourceLinkObject

upload(file_or_path: str | bytes | BinaryIO | Callable[[], Iterator[bytes]], dst_path: str, /, **kwargs) → SyncResourceLinkObject[исходный код]

Загружает файл на диск.

Параметры:

  • file_or_path – путь, файл-подобный объект, который нужно загрузить, или функция, которая возвращает итератор (или генератор)

  • dst_path – путь назначения

  • overwrite – если True, путь назначения может быть перезаписан, иначе будет вызвана ошибка

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • ParentNotFoundError – родительская папка не существует

  • PathExistsError – путь назначения уже существует

  • InsufficientStorageError – невозможно загрузить файл из-за нехватки места на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

  • UploadTrafficLimitExceededError – достигнут лимит на загрузку файлов

Результат:

SyncResourceLinkObject, ссылка на загруженный ресурс

Загружает файл на диск по уже полученной ссылке.

Параметры:

  • file_or_path – путь, файл-подобный объект, который нужно загрузить, или функция, которая возвращает итератор (или генератор)

  • link – ссылка для загрузки файла

  • overwrite – если True, путь назначения может быть перезаписан, иначе будет вызвана ошибка

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

InsufficientStorageError – невозможно загрузить файл из-за нехватки места на Диске

upload_url(url: str, path: str, /, **kwargs) → SyncOperationLinkObject[исходный код]

Загружает файл на диск по URL.

Параметры:

  • url – исходный URL

  • path – путь назначения

  • disable_redirects – bool, запретить делать перенаправления

  • fields – список ключей, которые будут включены в ответ

  • timeout – float или tuple, таймаут запроса

  • headers – dict или None, дополнительные заголовки запроса

  • n_retries – int, максимальное число повторных попыток запроса

  • retry_interval – задержка между повторными попытками в секундах

Исключение:

  • ParentNotFoundError – родительская папка не существует

  • PathExistsError – путь назначения уже существует

  • InsufficientStorageError – невозможно загрузить файл из-за нехватки места на Диске

  • ForbiddenError – у приложения не хватает прав, чтобы выполнить данный запрос

  • ResourceIsLockedError – запрашиваемый ресурс заблокирован другой операцией

  • UploadTrafficLimitExceededError – достигнут лимит на загрузку файлов

Результат:

SyncOperationLinkObject, ссылка на асинхронную операцию

yadisk.YaDisk

alias of Client