Skip to main content

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

Project description

Read the Docs GitHub Actions Workflow Status PyPI PyPI - Python Version Coverage

English version of this document

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

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

Установка

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"))

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

  • 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)

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

yadisk-3.1.0.tar.gz (120.4 kB view hashes)

Uploaded Source

Built Distribution

yadisk-3.1.0-py3-none-any.whl (129.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page