Библиотека-клиент REST API Яндекс.Диска / Yandex.Disk REST API client library
Project description
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 await 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 2.1.0 (2024-01-03)
Исправлен баг, из-за которого параметры в теле POST-запроса неправильно кодировались
Исправлен баг в
PycURLSession.send_request()
, из-за которого переданные заголовки игнорировалисьRequestsSession.close()
теперь закрывает сессию для всех потоковВсе методы
Client
иAsyncClient
теперь используют существующую сессиюУдалены аттрибут
session_factory
и методmake_session()
классовClient
иAsyncClient
Класс сессии теперь может быть указан в качестве строки (см.
Client
/AsyncClient
)Добавлены методы :code”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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.