YaDisk

YaDisk is a Yandex.Disk REST API client library.

Documentation is available at Read the Docs (EN) and Read the Docs (RU).

Installation

yadisk supports multiple HTTP client libraries and has both synchronous and asynchronous API.

The following HTTP client libraries are currently supported:

requests (used by default for synchronous API)
httpx (both synchronous and asynchronous, used by default for asynchronous API)
aiohttp (asynchronous only)
pycurl (synchronous only)

For synchronous API (installs requests):

pip install yadisk[sync_defaults]

For asynchronous API (installs aiofiles and httpx):

pip install yadisk[async_defaults]

Alternatively, you can manually choose which optional libraries to install:

# For use with pycurl
pip install yadisk[pycurl]

# For use with aiohttp, will also install aiofiles
pip install yadisk[async_files,aiofiles]

Examples

Synchronous API

import yadisk

client = yadisk.Client(token="<token>")
# or
# client = yadisk.Client("<application-id>", "<application-secret>", "<token>")

# You can either use the with statement or manually call client.close() later
with client:
    # Check if the token is valid
    print(client.check_token())

    # Get disk information
    print(client.get_disk_info())

    # Print files and directories at "/some/path"
    print(list(client.listdir("/some/path")))

    # Upload "file_to_upload.txt" to "/destination.txt"
    client.upload("file_to_upload.txt", "/destination.txt")

    # Same thing
    with open("file_to_upload.txt", "rb") as f:
        client.upload(f, "/destination.txt")

    # Download "/some-file-to-download.txt" to "downloaded.txt"
    client.download("/some-file-to-download.txt", "downloaded.txt")

    # Permanently remove "/file-to-remove"
    client.remove("/file-to-remove", permanently=True)

    # Create a new directory at "/test-dir"
    print(client.mkdir("/test-dir"))

Asynchronous API

import yadisk
import aiofiles

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

# You can either use the with statement or manually call client.close() later
async with client:
    # Check if the token is valid
    print(await client.check_token())

    # Get disk information
    print(await client.get_disk_info())

    # Print files and directories at "/some/path"
    print([i async for i in client.listdir("/some/path")])

    # Upload "file_to_upload.txt" to "/destination.txt"
    await client.upload("file_to_upload.txt", "/destination.txt")

    # Same thing
    async with aiofiles.open("file_to_upload.txt", "rb") as f:
        await client.upload(f, "/destination.txt")

    # Same thing but with regular files
    with open("file_to_upload.txt", "rb") as f:
        await client.upload(f, "/destination.txt")

    # Download "/some-file-to-download.txt" to "downloaded.txt"
    await client.download("/some-file-to-download.txt", "downloaded.txt")

    # Same thing
    async with aiofiles.open("downloaded.txt", "wb") as f:
        await client.download("/some-file-to-download.txt", f)

    # Permanently remove "/file-to-remove"
    await client.remove("/file-to-remove", permanently=True)

    # Create a new directory at "/test-dir"
    print(await client.mkdir("/test-dir"))

Changelog

Release 3.1.0 (2024-07-12)
- New features:
  - Added new exception classes: GoneError and ResourceDownloadLimitExceededError
  - Added a new method: Client.get_all_public_resources() and AsyncClient.get_all_public_resources()
- Bug fixes:
  - Fixed setting headers and session arguments to None causing errors
  - Fixed incorrect handling of empty filename in Client.rename() and AsyncClient.rename()
  - Fixed several typos in async convenience method implementations (listdir() and related)
  - Fixed PublicResourceListObject having the wrong type for its items member
  - Fixed API requests not working with PycURLSession when stream=True is set
  - No data will be written to the output file by Client.download(), Client.download_by_link(), AsyncClient.download() and AsyncClient.download_by_link() if the server returns a bad status code
Release 3.0.1 (2024-07-09)
- Fixed broken pyproject.toml that did not include full package contents (see issue #49)
Release 3.0.0 (2024-07-09)
- Breaking changes:
  - See Migration Guide for full details
  - All methods wait for asynchronous operations to complete by default (see the new wait=<bool> parameter)
  - Iterating over the result of AsyncClient.listdir() no longer requires the additional await keyword.
  - Number of returned items of Client.get_files() / AsyncClient.get_files() is now controlled by the max_items parameter, rather than limit
  - Methods set_token(), set_headers() of Session and AsyncSession were removed
  - Some methods no longer accept the fields parameter
  - Client.get_last_uploaded() / AsyncClient.get_last_uploaded() now return a list instead of a generator
  - yadisk.api is now a private module
  - All private modules were renamed to have names that start with _ (e.g, yadisk._api)
- New features:
  - Added methods to wait until an asynchronous operation completes (see Client.wait_for_operation() / AsyncClient.wait_for_operation())
  - Methods that may start an asynchronous operation now accept additional parameters: wait: bool = True, poll_interval: float = 1.0 and poll_timeout: Optional[float] = None
  - Client.listdir(), Client.get_files() and their async variants now accept a new parameter max_items: Optional[int] = None, which can be used to limit the maximum number of returned items
  - Most Client and AsyncClient methods now accept an optional parameter retry_on: Optional[Tuple[Type[Exception], ...]] = None, which lets you specify a tuple of additional exceptions that can trigger an automatic retry
  - yadisk.types module is now public
  - Added basic logging of outgoing API requests and automatic retries
  - The logger instance for the library can be accessed as yadisk.settings.logger
  - Added YaDiskObject.field() and the @ operator (YaDiskObject.__matmul__()) which verify that the given field is not None
  - Added Client.get_upload_link_object(), AsyncClient.get_upload_link_object() whose return values additionally contain operation_id
  - utils.auto_retry() now accepts more parameters
  - Added a few missing fields for DiskInfoObject
  - EXIFObject now contains GPS coordinates
  - CaseInsensitiveDict is now part of yadisk.utils
- Improvements:
  - Added full type hints for Client, AsyncClient through .pyi stub files
  - Docstrings for Client / AsyncClient now include more parameters
  - Errors during JSON processing (e.g. InvalidResponseError) also trigger automatic retries
  - Error message when the default session module is not available is now less confusing (see issue #43)
  - Reduced Client.listdir()'s default limit to 500 from 10000 to avoid timeouts on large directories (see issue #45)
  - Reduced Client.get_files()'s default limit to 200 from 1000 to avoid timeouts
  - Client.download() and similar methods no longer set Connection: close header, since it's not necessary (unlike with Client.upload())
  - UnknownYaDiskError now includes status code in the error message
- Bug fixes:
  - Fixed httpx- and aiohttp-based session implementations not converting their exceptions to RequestError in their Response.json() / AsyncResponse.json() implementations
  - Fixed stream=True not being set by default in AsyncClient.download(), AsyncClient.download_public()
- Other changes:
  - typing_extensions is now required for Python < 3.10
Release 2.1.0 (2024-01-03)
- Fixed a bug where POST request parameters were not encoded correctly
- Fixed a bug in PycURLSession.send_request() that made it ignore passed headers
- RequestsSession.close() now closes all underlying session instances, instead of only the current thread-local one
- All methods of Client and AsyncClient now use existing session
- Removed session_factory attribute and make_session() method of Client and AsyncClient
- Session class can now be specified as a string
- Added Client.get_device_code()/AsyncClient.get_device_code() methods
- Added Client.get_token_from_device_code()/AsyncClient.get_token_from_device_code() methods
- Added missing redirect_uri parameter for Client.get_auth_url()/AsyncClient.get_auth_url() and Client.get_code_url()/AsyncClient.get_code_url()
- Added support for PKCE parameters for Client.get_auth_url()/AsyncClient.get_auth_url(), Client.get_code_url()/AsyncClient.get_code_url() and Client.get_token()/AsyncClient.get_token()
- Added scope attribute for TokenObject
- Added new exception classes: InvalidClientError, InvalidGrantError, AuthorizationPendingError, BadVerificationCodeError and UnsupportedTokenTypeError
Release 2.0.0 (2023-12-12)
- The library now provides both synchronous and asynchronous APIs (see Introduction and API Reference)
- Multiple HTTP libraries are supported by default (see Available Session Implementations for the full list)
- It is now possible to add support for any HTTP library (see Session Interface)
- requests is now an optional dependency (although it's still used by default for synchronous API)
- Note that now requests-specific arguments must be passed differently (see Available Session Implementations)
- Preferred HTTP client libraries must be explicitly installed now (see Introduction)
- Client.upload() and Client.upload_by_link() can now accept a function that returns an iterator (or a generator) as a payload
Release 1.3.4 (2023-10-15)
- upload() and download() (and related) methods can now upload/download non-seekable file-like objects (e.g. stdin or stdout when open in binary mode), see PR #31
Release 1.3.3 (2023-04-22)
- app:/ paths now work correctly (see issue #26)
Release 1.3.2 (2023-03-20)
- Fixed issue #29: TypeError: 'type' object is not subscriptable
Release 1.3.1 (2023-02-28)
- Fixed issue #28: calling download_public() with path keyword argument raises TypeError
- Fixed AttributeError raised when calling ResourceLinkObject.public_listdir()
Release 1.3.0 (2023-01-30)
- Added convenience methods to ...Object objects (e.g. see ResourceObject in docs)
- Added type hints
- Improved error checking and response validation
- Added InvalidResponseError, PayloadTooLargeError, UploadTrafficLimitExceededError
- Added a few missing fields to DiskInfoObject and SystemFoldersObject
- Added rename(), upload_by_link() and download_by_link() methods
- Added default_args field for YaDisk object
- download() and upload() now return ResourceLinkObject
- Returned LinkObject instances have been replaced by more specific subclasses
- ConnectionError now also triggers a retry
Release 1.2.19 (2023-01-20)
- Fixed incorrect behavior of the fix from 1.2.18 for paths disk: and trash: (only these two).
Release 1.2.18 (2023-01-20)
- Fixed issue #26: ':' character in filenames causes BadRequestError. This is due the behavior of Yandex.Disk's REST API itself but is avoided on the library level with this fix.
Release 1.2.17 (2022-12-11)
- Fixed a minor bug which could cause a ReferenceError (which would not cause a crash, but still show an error message). The bug involved using __del__() method in SelfDestructingSession to automatically close the sessions it seems to affect primarily old Python versions (such as 3.4).
Release 1.2.16 (2022-08-17)
- Fixed a bug in check_token(): could throw ForbiddenError if the application lacks necessary permissions (issue #23).
Release 1.2.15 (2021-12-31)
- Fixed an issue where http:// links were not recognized as operation links (they were assumed to always be https://, since all the other requests are always HTTPS). Occasionally, Yandex.Disk can for some reason return an http:// link to an asynchronous operation instead of https://. Both links are now recognized correctly and an https:// version will always be used by get_operation_status(), regardless of which one Yandex.Disk returned.
Release 1.2.14 (2019-03-26)
- Fixed a TypeError in get_public_* functions when passing path parameter (see issue #7)
- Added unlimited_autoupload_enabled attribute for DiskInfoObject
Release 1.2.13 (2019-02-23)
- Added md5 parameter for remove()
- Added UserPublicInfoObject
- Added country attribute for UserObject
- Added photoslice_time attribute for ResourceObject, PublicResourceObject and TrashResourceObject
Release 1.2.13 (2019-02-23)
- Added md5 parameter for remove()
- Added UserPublicInfoObject
- Added country attribute for UserObject
- Added photoslice_time attribute for ResourceObject, PublicResourceObject and TrashResourceObject
Release 1.2.12 (2018-10-11)
- Fixed fields parameter not working properly in listdir() (issue #4)
Release 1.2.11 (2018-06-30)
- Added the missing parameter sort for get_meta()
- Added file and antivirus_status attributes for ResourceObject, PublicResourceObject and TrashResourceObject
- Added headers parameter
- Fixed a typo in download() and download_public() (issue #2)
- Removed *args parameter everywhere
Release 1.2.10 (2018-06-14)
- Fixed timeout=None behavior. None is supposed to mean 'no timeout' but in the older versions it was synonymous with the default timeout.
Release 1.2.9 (2018-04-28)
- Changed the license to LGPLv3 (see COPYING and COPYING.lesser)
- Other package info updates
Release 1.2.8 (2018-04-17)
- Fixed a couple of typos: PublicResourceListObject.items and TrashResourceListObject.items had wrong types
- Substitute field aliases in fields parameter when performing API requests (e.g. embedded -> _embedded)
Release 1.2.7 (2018-04-15)
- Fixed a file rewinding bug when uploading/downloading files after a retry
Release 1.2.6 (2018-04-13)
- Now caching requests sessions so that open connections can be reused (which can significantly speed things up sometimes)
- Disable keep-alive when uploading/downloading files by default
Release 1.2.5 (2018-03-31)
- Fixed an off-by-one bug in utils.auto_retry() (which could sometimes result in AttributeError)
- Retry the whole request for upload(), download() and download_public()
- Set stream=True for download() and download_public()
- Other minor fixes
Release 1.2.4 (2018-02-19)
- Fixed TokenObject having exprires_in instead of expires_in (fixed a typo)
Release 1.2.3 (2018-01-20)
- Fixed a TypeError when WrongResourceTypeError is raised
Release 1.2.2 (2018-01-19)
- refresh_token() no longer requires a valid or empty token.
Release 1.2.1 (2018-01-14)
- Fixed auto retries not working. Whoops.
Release 1.2.0 (2018-01-14)
- Fixed passing n_retries=0 to upload(), download() and download_public()
- upload(), download() and download_public() no longer return anything (see the docs)
- Added utils module (see the docs)
- Added RetriableYaDiskError, WrongResourceTypeError, BadGatewayError and GatewayTimeoutError
- listdir() now raises WrongResourceTypeError instead of NotADirectoryError
Release 1.1.1 (2017-12-29)
- Fixed argument handling in upload(), download() and download_public(). Previously, passing n_retries and retry_interval would raise an exception (TypeError).
Release 1.1.0 (2017-12-27)
- Better exceptions (see the docs)
- Added support for force_async parameter
- Minor bug fixes
Release 1.0.8 (2017-11-29)
- Fixed yet another listdir() bug
Release 1.0.7 (2017-11-04)
- Added install_requires argument to setup.py
Release 1.0.6 (2017-11-04)
- Return OperationLinkObject in some functions
Release 1.0.5 (2017-10-29)
- Fixed setup.py to exclude tests
Release 1.0.4 (2017-10-23)
- Fixed bugs in upload, download and listdir functions
- Set default listdir limit to 10000
Release 1.0.3 (2017-10-22)
- Added settings
Release 1.0.2 (2017-10-19)
- Fixed get_code_url function (added missing parameters)
Release 1.0.1 (2017-10-18)
- Fixed a major bug in GetTokenRequest (added missing parameter)
Release 1.0.0 (2017-10-18)
- Initial release

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.en.rst

README.en.rst

YaDisk

Installation

Examples

Synchronous API

Asynchronous API

Changelog

Files

README.en.rst

Latest commit

History

README.en.rst

File metadata and controls

YaDisk

Installation

Examples

Synchronous API

Asynchronous API

Changelog