Async Client¶

If you are working with an async framework like aiohttp or FastAPI, you can use the async client from the deezer.asyncio sub-package. It provides the same functionality as the synchronous Client, but with async/await support.

Getting started¶

The async client should be used as an async context manager:

from deezer.asyncio import AsyncClient

async with AsyncClient() as client:
    album = await client.get_album(302127)
    print(album.title)

As with the sync client, you can pass an access_token for authenticated requests:

async with AsyncClient(access_token="your-token") as client:
    user = await client.get_user()
    print(user.name)

Fetching resources¶

All the methods that fetch resources from the Deezer API are coroutines and need to be awaited:

async with AsyncClient() as client:
    artist = await client.get_artist(27)
    album = await client.get_album(302127)
    track = await client.get_track(3135556)

The returned objects are async resource classes (e.g. AsyncArtist, AsyncAlbum), which mirror their sync counterparts.

Navigating relationships¶

Relationship methods that return a single resource or a plain list need to be awaited:

async with AsyncClient() as client:
    track = await client.get_track(3135556)

    # These return a single resource
    artist = await track.get_artist()
    album = await track.get_album()

    # This returns a plain list
    radio = await artist.get_radio()

Methods that return paginated responses also need to be awaited. The first page of results is fetched eagerly, making the returned AsyncPaginatedList immediately usable:

async with AsyncClient() as client:
    artist = await client.get_artist(27)

    # Await to get the paginated list (first page is fetched)
    albums = await artist.get_albums()

Async Pagination¶

For endpoints returning paginated responses, items are wrapped in an AsyncPaginatedList. This works similarly to the synchronous PaginatedList described in the pagination guide, but uses async iteration and awaitable methods.

Iterating over elements¶

Use async for to iterate over all elements, transparently fetching additional pages as needed:

albums = await artist.get_albums()

async for album in albums:
    print(album.title)

Total number¶

The total number of items is available via the total property. Since the first page is fetched eagerly, the total is already available without any extra API call:

total = albums.total
# Or using len():
total = len(albums)

Accessing elements by index¶

Use the get() method to access an element by index:

first_album = await albums.get(0)
fifth_album = await albums.get(4)

As with the sync version, accessing a large index may trigger extra API calls to fetch preceding pages.

Note

Unlike the synchronous PaginatedList, the async version does not support the [] syntax for indexing or slicing. Use the get() method for index-based access, or collect() to get a plain list that supports regular slicing.

Collecting all elements¶

To fetch all pages and get a plain list, use collect():

all_albums = await albums.collect()

Search¶

Search methods also return AsyncPaginatedList and need to be awaited:

async with AsyncClient() as client:
    results = await client.search("Daft Punk")

    async for track in results:
        print(track.title)

Variant search methods are also available: search_albums(), search_artists(), and search_playlists().