yadisk 3.4.0

Библиотека-клиент REST API Яндекс.Диска / Yandex.Disk REST API client library

English version of this document

YaDisk - это библиотека-клиент REST API Яндекс.Диска.

Документация доступна на Read the Docs (RU) и Read the Docs (EN).

Содержание:

• Установка

• Примеры

  • Синхронный API

  • Асинхронный API

• Участие в разработке

• История изменений

Установка

yadisk поддерживает несколько HTTP библиотек и реализует одновременно как синхронный, так и асинхронный API.

На данный момент поддерживаются следующие HTTP библиотеки:

• requests (используется по умолчанию для синхронного API)

• httpx (синхронный и асинхронный API, используется по умолчанию для асинхронного API)

• aiohttp (асинхронный API)

• pycurl (синхронный API)

Для синхронного API (устанавливает requests):

pip install yadisk[sync-defaults]

Для асинхронного API (устанавливает httpx и aiofiles):

pip install yadisk[async-defaults]

Вы можете также вручную установить нужные библиотеки:

# Для использования совместно с pycurl
pip install yadisk[pycurl]

# Для использования совместно с aiohttp, также установит aiofiles
pip install yadisk[async-files,aiohttp]

Примеры

Синхронный API

import yadisk

client = yadisk.Client(token="<токен>")
# или
# client = yadisk.Client("<id-приложения>", "<secret-приложения>", "<токен>")

# Вы можете использовать либо конструкцию with, либо вручную вызвать client.close() в конце
with client:
    # Проверяет, валиден ли токен
    print(client.check_token())

    # Получает общую информацию о диске
    print(client.get_disk_info())

    # Выводит содержимое "/some/path"
    print(list(client.listdir("/some/path")))

    # Загружает "file_to_upload.txt" в "/destination.txt"
    client.upload("file_to_upload.txt", "/destination.txt")

    # То же самое
    with open("file_to_upload.txt", "rb") as f:
        client.upload(f, "/destination.txt")

    # Скачивает "/some-file-to-download.txt" в "downloaded.txt"
    client.download("/some-file-to-download.txt", "downloaded.txt")

    # Безвозвратно удаляет "/file-to-remove"
    client.remove("/file-to-remove", permanently=True)

    # Создаёт новую папку "/test-dir"
    print(client.mkdir("/test-dir"))

Асинхронный API

import yadisk
import aiofiles

client = yadisk.AsyncClient(token="<token>")
# или
# client = yadisk.AsyncClient("<application-id>", "<application-secret>", "<token>")

# Вы можете использовать либо конструкцию with, либо вручную вызвать client.close() в конце
async with client:
    # Проверяет, валиден ли токен
    print(await client.check_token())

    # Получает общую информацию о диске
    print(await client.get_disk_info())

    # Выводит содержимое "/some/path"
    print([i async for i in client.listdir("/some/path")])

    # Загружает "file_to_upload.txt" в "/destination.txt"
    await client.upload("file_to_upload.txt", "/destination.txt")

    # То же самое
    async with aiofiles.open("file_to_upload.txt", "rb") as f:
        await client.upload(f, "/destination.txt")

    # То же самое, но с обычными файлами
    with open("file_to_upload.txt", "rb") as f:
        await client.upload(f, "/destination.txt")

    # Скачивает "/some-file-to-download.txt" в "downloaded.txt"
    await client.download("/some-file-to-download.txt", "downloaded.txt")

    # То же самое
    async with aiofiles.open("downloaded.txt", "wb") as f:
        await client.download("/some-file-to-download.txt", f)

    # Безвозвратно удаляет "/file-to-remove"
    await client.remove("/file-to-remove", permanently=True)

    # Создаёт новую папку "/test-dir"
    print(await client.mkdir("/test-dir"))

Участие в разработке

Если вы хотите поучаствовать в разработке, см. CONTRIBUTING.rst.

История изменений

• Release 3.4.0 (2025-07-10)

  • Нововведения:

    • Добавлены методы для управления настройками публичного доступа к ресурсам:

      • Client.update_public_settings()

      • Client.get_public_settings()

      • Client.get_public_available_settings()

      Внимание: похоже, что эти эндпоинты не полностью соответствуют официальной документации REST API, их функциональность на практике ограничена.

    • Добавлен новый класс исключений PasswordRequiredError

    • Добавлено несколько новых полей DiskInfoObject:

      • deletion_restricion_days

      • hide_screenshots_in_photoslice

      • is_legal_entity

    • Реализован метод __dir__() для объектов ответов сервера

  • Улучшения:

    • repr() объектов ответов API теперь показывает только те ключи, которые фактически присутствуют (вместо отображения их значений как None, как раньше)

• Release 3.3.0 (2025-04-29)

  • Нововведения:

    • Спуфинг User-Agent для обхода ограничения скорости загрузки файлов на Диск (см. PR #57). Client.upload() и связанные с ним методы (включая AsyncClient) имеют новый опциональный параметр spoof_user_agent, который по умолчанию имеет значение True. Этот параметр можно использовать для отключения спуфинга, если это необходимо.

    • Добавлена поддержка pretty-printing в IPython для YaDiskObject и производных классов

  • Исправления:

    • Client.wait_for_operation() теперь использует time.monotonic() вместо time.time()

  • Улучшения:

    • Сообщения об ошибках REST API теперь чётко разделены на четыре части (сообщение, описание, код ошибки и код состояния HTTP)

• Release 3.2.0 (2025-02-03)

  • Нововведения:

    • Добавлен новый метод: Client.makedirs() и AsyncClient.makedirs() (см. issue #53)

    • Добавлено несколько недостающих полей DiskInfoObject

      • photounlim_size

      • will_be_overdrawn

      • free_photounlim_end_date

      • payment_flow

    • Добавлено недостающее поле sizes для ResourceObject и связанных с ним объектов

  • Исправления:

    • Client.rename() / AsyncClient.rename() теперь вызывает ValueError при попытке переименовать корневую папку

    • Номера автоматических повторных попыток логировались с ошибкой на единицу, теперь они логируются правильно

• Release 3.1.0 (2024-07-12)

  • Нововведения:

    • Добавлены новые исключения: GoneError и ResourceDownloadLimitExceededError

    • Добавлен новый метод: Client.get_all_public_resources() и AsyncClient.get_all_public_resources()

  • Исправления:

    • Задание headers и других опциональных параметров сессии как None больше не вызывает ошибок

    • Исправлено неправильное поведение Client.rename() и AsyncClient.rename() при указании пустого имени файла

    • Исправлено несколько опечаток в асинхронных реализациях convenience-методов (listdir() и аналогичных)

    • Исправлен неправильный тип данных у атрибута items класса PublicResourceListObject

    • Исправлены ошибки при отправке запросов API с помощью PycURLSession при задании stream=True

    • Данные не будут записаны в файл методами Client.download(), Client.download_by_link(), AsyncClient.download() и AsyncClient.download_by_link(), если сервер вернул ошибочный код состояния

• Release 3.0.1 (2024-07-09)

  • Исправлен сломанный pyproject.toml, который не включал в сборку полное содержимое пакета (см. issue #49)

• Release 3.0.0 (2024-07-09)

  • Несовместимые изменения:

    • См. Руководство по миграции для подробностей

    • Все методы теперь ожидают завершения асинхронных операций по умолчанию (см. новый параметр wait=<bool>)

    • Итерация по результату AsyncClient.listdir() больше не требует дополнительного ключевого слова await

    • Число возвращаемых файлов Client.get_files() / AsyncClient.get_files() теперь контролируется параметром max_items, вместо limit

    • Методы set_token(), set_headers() интерфейсов Session и AsyncSession были удалены

    • Некоторые методы больше не принимают параметр fields

    • Client.get_last_uploaded() / AsyncClient.get_last_uploaded() теперь возвращает список вместо генератора

    • yadisk.api - теперь скрытый модуль

    • Все скрытые модули были переименованы, их имена начинаются с _ (например, yadisk._api)

  • Нововведения:

    • Добавлены методы для ожидания завершения асинхронной операции (см. Client.wait_for_operation() / AsyncClient.wait_for_operation())

    • Методы, которые могут запускать асинхронную операцию, теперь принимают дополнительные параметры: wait: bool = True, poll_interval: float = 1.0 и poll_timeout: Optional[float] = None

    • Client.listdir(), Client.get_files() и их асинхронные вариации теперь принимают новый параметр max_items: Optional[int] = None, который может быть использован, чтобы ограничить максимальное число возвращаемых файлов

    • Большинство методов Client и AsyncClient теперь принимает retry_on: Optional[Tuple[Type[Exception], ...]] = None, который позволяет указывать кортеж из дополнительных исключений, которые могут вызвать автоматическую повторную попытку

    • Модуль yadisk.types - теперь публичный

    • Добавлено логирование исходящих запросов к API и автоматических повторных попыток

    • Объект логгера библиотеки доступен как yadisk.settings.logger

    • Добавлен метод YaDiskObject.field() и оператор @ (YaDiskObject.__matmul__()), который удостоверяется, что указанное поле объекта не является None

    • Добавлены методы Client.get_upload_link_object(), AsyncClient.get_upload_link_object(), возвращаемые значения которых дополнительно содержат operation_id

    • utils.auto_retry() теперь принимает больше параметров

    • Добавлено несколько недостающих полей DiskInfoObject

    • EXIFObject теперь содержит GPS-координаты

    • CaseInsensitiveDict - теперь часть yadisk.utils

  • Улучшения:

    • Добавлены полные подсказки типов для Client и AsyncClient с помощью файлов .pyi

    • Строки документации для Client / AsyncClient теперь включают в себя больше параметров

    • Ошибки во время обработки JSON (например, InvalidResponseError) также вызывают автоматические повторные попытки

    • Сообщение об ошибке в случае, когда модуль сессии по умолчанию недоступен, теперь не вводит в заблуждение (см. issue #43)

    • Уменьшено значение limit до 500 (было 10000) для Client.listdir() для избежания таймаутов при больших папках (см. issue #45)

    • Уменьшено значение limit до 200 (было 1000) для Client.get_files() для избежания таймаутов

    • Client.download() и подобные методы больше не задают заголовок Connection: close т.к. в этом нет необходимости (в отличие от Client.upload())

    • UnknownYaDiskError теперь включает код статуса в сообщение об ошибке

  • Исправления:

    • Исправлены реализации на основе httpx и aiohttp: реализации методов Response.json() / AsyncResponse.json() не преобразовывали свои исключения в RequestError

    • Исправлено: параметр stream=True был не задан по умолчанию в AsyncClient.download(), AsyncClient.download_public()

  • Другие изменения:

    • typing_extensions теперь требуется для Python < 3.10

• Release 2.1.0 (2024-01-03)

  • Исправлен баг, из-за которого параметры в теле POST-запроса неправильно кодировались

  • Исправлен баг в PycURLSession.send_request(), из-за которого переданные заголовки игнорировались

  • RequestsSession.close() теперь закрывает сессию для всех потоков

  • Все методы Client и AsyncClient теперь используют существующую сессию

  • Удалены аттрибут session_factory и метод make_session() классов Client и AsyncClient

  • Класс сессии теперь может быть указан в качестве строки (см. Client/AsyncClient)

  • Добавлены методы Client.get_device_code()/AsyncClient.get_device_code()

  • Добавлены методы Client.get_token_from_device_code()/AsyncClient.get_token_from_device_code()

  • Добавлен недостающий параметр redirect_uri для Client.get_auth_url()/AsyncClient.get_auth_url() и Client.get_code_url()/AsyncClient.get_code_url()

  • Добавлена поддержка параметров PKCE для Client.get_auth_url()/AsyncClient.get_auth_url(), Client.get_code_url()/AsyncClient.get_code_url() и Client.get_token()/AsyncClient.get_token()

  • Добавлен аттрибут scope для TokenObject

  • Добавлены новые классы исключений: InvalidClientError, InvalidGrantError, AuthorizationPendingError, BadVerificationCodeError и UnsupportedTokenTypeError

• Release 2.0.0 (2023-12-12)

  • Библиотека теперь предоставляет как синхронный, так и асинхронный API (см. Введение и Справочник API)

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

  • Теперь возможно добавить поддержку любой HTTP библиотеки (см. Интерфейс Session)

  • requests - теперь опциональная зависимость (хотя всё ещё используется по умолчанию для синхронного API)

  • Обратите внимание, что аргументы, специфичные для requests теперь передаются по другому (см. Доступные реализации сессий)

  • Предпочитаемые HTTP библиотеки теперь должны быть установлены явным образом (см. Введение)

  • Client.upload() и Client.upload_by_link() теперь могут принимать функцию, возвращающую итератор (или генератор) в качестве полезной нагрузки

• Release 1.3.4 (2023-10-15)

  • Методы upload() и download() (и связянные с ними) теперь могут загружать/скачивать файлы, не поддерживающие операцию seek() (например, stdin и stdout, при условии, что они открыты в режиме "rb" или "wb"), см. PR #31

• Release 1.3.3 (2023-04-22)

  • Пути вида app:/ теперь работают правильно (см. issue #26)

• Release 1.3.2 (2023-03-20)

  • Исправлено issue #29: TypeError: ‘type’ object is not subscriptable

• Release 1.3.1 (2023-02-28)

  • Исправлено issue #28: TypeError при вызове download_public() с параметром path

  • Исправлено AttributeError при вызове ResourceLinkObject.public_listdir()

• Release 1.3.0 (2023-01-30)

  • Добавлены convenience-методы для объектов ...Object (например, см. ResourceObject)

  • Добавлены подсказки типов (type hints)

  • Улучшены проверки ошибок и проверка ответа

  • Добавлены InvalidResponseError, PayloadTooLargeError, UploadTrafficLimitExceededError

  • Добавлено несколько недостающих полей объектов DiskInfoObject и SystemFoldersObject

  • Добавлены методы rename(), upload_by_link() и download_by_link()

  • Добавлен аттрибут default_args объекта YaDisk

  • download() и upload() теперь возвращают ResourceLinkObject

  • До этого возвращаемые объекты LinkObject были заменены более конкретными подклассами

  • ConnectionError теперь тоже вызывает повторную попытку

• Release 1.2.19 (2023-01-20)

  • Исправлено неправильное поведение фикса из 1.2.18 для путей disk: и trash:.

• Release 1.2.18 (2023-01-20)

  • Исправлено issue #26: символ ‘:’ в именах файлов приводит к BadRequestError. Это поведение вызвано работой самого REST API Яндекс.Диска, но было исправлено на уровне библиотеки.

• Release 1.2.17 (2022-12-11)

  • Исправлен баг, связанный с автоматическим закрытием сессии. Использование метода __del__() приводило в некоторых случаях к ошибке ReferenceError (ошибка игнорировалась, но сообщение выводилось). Баг проявляется по большей части в старых версиях Python (например 3.4).

• Release 1.2.16 (2022-08-17)

  • Исправлен баг в check_token(): функция могла вызвать ForbiddenError, если у приложения недостатчно прав (issue #23).

• Release 1.2.15 (2021-12-31)

  • Исправлено: не распознавались ссылки на асинхронные операции, если они использовали http:// (вместо https://). Иногда Яндекс.Диск может вернуть http:// ссылку на асинхронную операцию. Теперь обе версии ссылок распознаются правильно, при этом, при получении информации об операции (через get_operation_status()) всегда используется https:// версия ссылки, даже если Яндекс.Диск вернул http://.

• Release 1.2.14 (2019-03-26)

  • Исправлена ошибка TypeError в функциях get_public_* при использовании с параметром path (issue #7)

  • Добавлен аттрибут unlimited_autoupload_enabled для DiskInfoObject

• Release 1.2.13 (2019-02-23)

  • Добавлен md5 параметр для remove()

  • Добавлен UserPublicInfoObject

  • Добавлен аттрибут country для UserObject

  • Добавлен аттрибут photoslice_time для ResourceObject, PublicResourceObject и TrashResourceObject

• Release 1.2.12 (2018-10-11)

  • Исправлен баг: не работает параметр fields в listdir() (issue #4)

• Release 1.2.11 (2018-06-30)

  • Добавлен недостающий параметр sort для get_meta()

  • Добавлены аттрибуты file и antivirus_status для ResourceObject, PublicResourceObject и TrashResourceObject

  • Добавлен параметр headers

  • Исправлена опечатка в download() и download_public() (issue #2)

  • Убран параметр *args

• Release 1.2.10 (2018-06-14)

  • Исправлено поведение timeout=None. None должен означать „без таймаута“, но в предыдущих версиях значение None было синонимично со стандартным таймаутом.

• Release 1.2.9 (2018-04-28)

  • Изменена лицензия на LGPLv3 (см. COPYING и COPYING.lesser)

  • Другие изменения информации о пакете

• Release 1.2.8 (2018-04-17)

  • Исправлено несколько опечаток: у PublicResourceListObject.items и TrashResourceListObject.items были неправильные типы данных

  • Псевдонимы полей в параметре fields заменяются при выполнении запросов API (например, embedded -> _embedded)

• Release 1.2.7 (2018-04-15)

  • Исправлен баг перемотки файла при загрузке/скачивании после повторной попытки

• Release 1.2.6 (2018-04-13)

  • Теперь объекты сессий requests кэшируются, чтобы их можно было переиспользовать (иногда может существенно ускорить выполнение запросов)

  • keep-alive отключается при загрузке/скачивании файлов по умолчанию

• Release 1.2.5 (2018-03-31)

  • Исправлен баг (ошибка на единицу) в utils.auto_retry() (иногда мог вызвать AttributeError)

  • Повторные попытки применяются для upload(), download() и download_public() целиком

  • Задано stream=True для download() и download_public()

  • Другие мелкие исправления

• Release 1.2.4 (2018-02-19)

  • Исправлена опечатка (TokenObject.exprires_in -> TokenObject.expires_in)

• Release 1.2.3 (2018-01-20)

  • Исправлено TypeError при вызове WrongResourceTypeError

• Release 1.2.2 (2018-01-19)

  • refresh_token() больше не требует валидный или пустой токен.

• Release 1.2.1 (2018-01-14)

  • Исправлена неработоспособность повторных попыток.

• Release 1.2.0 (2018-01-14)

  • Исправлено использование n_retries=0 в upload(), download() и download_public()

  • upload(), download() и download_public() больше не возвращают ничего (см. документацию)

  • Добавлен модуль utils (см. документацию)

  • Добавлены RetriableYaDiskError, WrongResourceTypeError, BadGatewayError и GatewayTimeoutError

  • listdir() теперь вызывает WrongResourceTypeError вместо NotADirectoryError

• Release 1.1.1 (2017-12-29)

  • Исправлена обработка аргументов в upload(), download() и download_public(). До этого использование n_retries и retry_interval вызывало исключение (TypeError).

• Release 1.1.0 (2017-12-27)

  • Усовершенствованные исключения (см. документацию)

  • Добавлена поддержка параметра force_async

  • Мелкие исправления багов

• Release 1.0.8 (2017-11-29)

  • Исправлен ещё один баг в listdir()

• Release 1.0.7 (2017-11-04)

  • Добавлен install_requires в setup.py

• Release 1.0.6 (2017-11-04)

  • Некоторые функции теперь возвращают OperationLinkObject

• Release 1.0.5 (2017-10-29)

  • Исправлен setup.py, теперь исключает тесты

• Release 1.0.4 (2017-10-23)

  • Исправлены баги в upload, download и listdir

  • Значение по-умолчанию limit в listdir установлено в 10000

• Release 1.0.3 (2017-10-22)

  • Добавлен модуль settings

• Release 1.0.2 (2017-10-19)

  • Исправлена функция get_code_url (добавлены недостающие параметры)

• Release 1.0.1 (2017-10-18)

  • Исправлен серьёзный баг в GetTokenRequest (добавлен недостающий параметр)

• Release 1.0.0 (2017-10-18)

  • Первый релиз