Migration Guide

Migrating From 2.x to 3.x

Waiting for asynchronous operations to complete

Starting with the version 3.0.0, the following methods will automatically wait for the asynchronous operation to complete:

• Client.copy(), AsyncClient.copy()

• Client.move(), AsyncClient.move()

• Client.remove(), AsyncClient.remove()

• Client.remove_trash(), AsyncClient.remove_trash()

• Client.rename(), AsyncClient.rename()

• Client.restore_trash(), AsyncClient.restore_trash()

• Client.save_to_disk(), AsyncClient.save_to_disk()

• Client.upload_url(), AsyncClient.upload_url().

This new behavior is controlled by the wait parameter, which defaults to True. Waiting is performed by repeatedly checking the operation status (see Client.get_operation_status() and Client.wait_for_operation()) and calling time.sleep / asyncio.sleep. If this parameter is explicitly set to False, no additional waiting is performed, this matches the old behavior.

Note

If wait=True is set, there is a possibility of getting an AsyncOperationFailedError, though this is very unlikely in practice.

For more details, see documentation for any of the above-mentioned methods.

Iterating over AsyncClient.listdir()

Iterating over the result of AsyncClient.listdir() no longer requires the additional await keyword:

async with yadisk.AsyncClient(token=...) as client:
    # yadisk 3.x
    async for resource in client.listdir():
        do_something(resource)

    # yadisk 2.x, no longer valid, will not work
    async for resource in await client.listdir():
        do_something(resource)

Changes with get_files()

Before the version 3.0.0, Client.get_files() / AsyncClient.get_files() would return up to limit files, unless it was set to None, in which case it would return all of them.

Starting with the version 3.0.0, to control the number of returned files, a new parameter max_items is introduced. limit only affects the number of files queried by a single request (requests are sent until max_items files are obtained or end of the list is reached). This new behavior is consistent with Client.listdir() / AsyncClient.listdir().

get_last_uploaded() returns a list instead of a generator

Starting with the version 3.0.0, Client.get_last_uploaded() / AsyncClient.get_last_uploaded() return a list of files instead of a generator.

Changes with the Session interface

In version 3.0.0, the following methods were removed:

• Session.set_token(), AsyncSession.set_token()

• Session.set_headers(), AsyncSession.set_headers().

Starting with the version 3.0.0, all HTTP headers (including the Authorization header) are explicitly passed to Session.send_request() / AsyncSession.send_request().

Some methods no longer accept the fields parameter

Prior to version 3.0.0, the following methods used to accept the optional fields parameter:

• Client.get_operation_status(), AsyncClient.get_operation_status()

• Client.get_download_link(), AsyncClient.get_download_link()

• Client.get_public_download_link(), AsyncClient.get_public_download_link()

• Client.get_upload_link(), AsyncClient.get_upload_link().

Migrating From 1.x to 2.x

Merge with yadisk-async

Starting with version 2.0.0, the library provides both synchronous and asynchronous APIs.

Changes to exception handling

Starting with version 2.0.0, all exceptions raised by Client and AsyncClient are derived from YaDiskError. Exceptions from underlying dependencies (e.g. requests or aiohttp) are converted to RequestError. A non-exhaustive list of possible exceptions is provided by the documentation for Client and AsyncClient. More details about exceptions are available in documentation for each specific API method.

requests and aiohttp are optional dependencies

Prior to version 2.0.0, requests was listed as a dependency (and aiohttp was listed as a dependency for yadisk-async). requests is still used by default but must be explicitly installed. As for the asynchronous API, httpx is used by default, instead of aiohttp. There are now multiple supported HTTP client libraries.

See Available Session Implementations for a full list of supported HTTP client libraries and Introduction for installation instructions.