deezer-python 7.2.0__tar.gz → 7.3.0__tar.gz

{deezer_python-7.2.0 → deezer_python-7.3.0}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## v7.3.0 (2026-04-06)
+
+### Features
+
+- Add async deezer client and resources in `deezer.asyncio` ([`cf30c7c`](https://github.com/browniebroke/deezer-python/commit/cf30c7cf7f9d58d0815456d49fd9095d1d364154))
+
 ## v7.2.0 (2025-09-18)
 
 ### Features

{deezer_python-7.2.0 → deezer_python-7.3.0}/CONTRIBUTING.md

@@ -65,7 +65,13 @@ Ready to contribute? Here's how to set up `deezer-python` for local development.
    $ uv run pytest
    ```
 
-6. Linting is done through [pre-commit](https://pre-commit.com). Provided you have the tool installed globally, you can run them all as one-off:
+6. Type checking is done with [ty](https://docs.astral.sh/ty/), and is run with:
+
+   ```shell
+   uv run ty check
+   ```
+
+7. Linting is done through [pre-commit](https://pre-commit.com). Provided you have the tool installed globally, you can run them all as one-off:
 
    ```shell
    $ pre-commit run -a
@@ -77,7 +83,7 @@ Ready to contribute? Here's how to set up `deezer-python` for local development.
    $ pre-commit install
    ```
 
-7. Commit your changes, quoting GitHub issue in the commit message, if applicable, and push your branch to GitHub:
+8. Commit your changes, quoting GitHub issue in the commit message, if applicable, and push your branch to GitHub:
 
    ```shell
    $ git add .
@@ -87,7 +93,7 @@ Ready to contribute? Here's how to set up `deezer-python` for local development.
 
    Note: the commit message should follow [the conventional commits](https://www.conventionalcommits.org). We run [`commitlint` on CI](https://github.com/marketplace/actions/commit-linter) to validate it, and if you've installed pre-commit hooks at the previous step, the message will be checked at commit time.
 
-8. Submit a pull request on GitHub.
+9. Submit a pull request on GitHub.
 
 ## Obtain an API token
 

{deezer_python-7.2.0 → deezer_python-7.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deezer-python
-Version: 7.2.0
+Version: 7.3.0
 Summary: A friendly wrapper library for the Deezer API
 Author-email: Bruno Alla <alla.brunoo@gmail.com>
 License-Expression: MIT

{deezer_python-7.2.0 → deezer_python-7.3.0}/docs/Makefile

@@ -12,6 +12,10 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+# Build, watch and serve docs with live reload
+watch:
+	sphinx-autobuild -b html -c . $(SOURCEDIR) $(BUILDDIR)/html
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

deezer_python-7.3.0/docs/api_reference/async_client.rst

@@ -0,0 +1,7 @@
+Async Client
+------------
+
+The async client class is the main entry point to start querying the `Deezer API <https://developers.deezer.com/api>`_ using ``async``/``await``.
+
+.. autoclass:: deezer.asyncio.AsyncClient
+    :members:

deezer_python-7.3.0/docs/api_reference/async_pagination.rst

@@ -0,0 +1,7 @@
+.. _async-pagination-reference:
+
+Async Pagination
+----------------
+
+.. autoclass:: deezer.asyncio.AsyncPaginatedList
+    :members:

deezer_python-7.3.0/docs/api_reference/async_resources/album.rst

@@ -0,0 +1,6 @@
+AsyncAlbum
+----------
+
+.. autoclass:: deezer.asyncio.AsyncAlbum
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/artist.rst

@@ -0,0 +1,6 @@
+AsyncArtist
+-----------
+
+.. autoclass:: deezer.asyncio.AsyncArtist
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/chart.rst

@@ -0,0 +1,6 @@
+AsyncChart
+----------
+
+.. autoclass:: deezer.asyncio.AsyncChart
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/editorial.rst

@@ -0,0 +1,6 @@
+AsyncEditorial
+--------------
+
+.. autoclass:: deezer.asyncio.AsyncEditorial
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/episode.rst

@@ -0,0 +1,6 @@
+AsyncEpisode
+------------
+
+.. autoclass:: deezer.asyncio.AsyncEpisode
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/genre.rst

@@ -0,0 +1,6 @@
+AsyncGenre
+----------
+
+.. autoclass:: deezer.asyncio.AsyncGenre
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/playlist.rst

@@ -0,0 +1,6 @@
+AsyncPlaylist
+-------------
+
+.. autoclass:: deezer.asyncio.AsyncPlaylist
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/podcast.rst

@@ -0,0 +1,6 @@
+AsyncPodcast
+------------
+
+.. autoclass:: deezer.asyncio.AsyncPodcast
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/radio.rst

@@ -0,0 +1,6 @@
+AsyncRadio
+----------
+
+.. autoclass:: deezer.asyncio.AsyncRadio
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/track.rst

@@ -0,0 +1,6 @@
+AsyncTrack
+----------
+
+.. autoclass:: deezer.asyncio.AsyncTrack
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources/user.rst

@@ -0,0 +1,6 @@
+AsyncUser
+---------
+
+.. autoclass:: deezer.asyncio.AsyncUser
+    :members:
+    :undoc-members:

deezer_python-7.3.0/docs/api_reference/async_resources.md

@@ -0,0 +1,21 @@
+(async-resources-reference)=
+
+# Async Resources
+
+A collection of async Python classes modelling each type of content that is returned by the Deezer API when using the {class}`~deezer.asyncio.AsyncClient`.
+
+```{toctree}
+:maxdepth: 1
+
+async_resources/album
+async_resources/artist
+async_resources/chart
+async_resources/editorial
+async_resources/episode
+async_resources/genre
+async_resources/playlist
+async_resources/podcast
+async_resources/radio
+async_resources/track
+async_resources/user
+```

{deezer_python-7.2.0 → deezer_python-7.3.0}/docs/api_reference/toc.rst

@@ -12,3 +12,6 @@ This is the auto-generated documentation for all the main modules in the library
     client
     pagination
     resources
+    async_client
+    async_pagination
+    async_resources

deezer_python-7.3.0/docs/async.md

@@ -0,0 +1,126 @@
+(async-guide)=
+
+# Async Client
+
+If you are working with an async framework like [aiohttp](https://docs.aiohttp.org/) or [FastAPI](https://fastapi.tiangolo.com/), you can use the async client from the {mod}`deezer.asyncio` sub-package. It provides the same functionality as the synchronous {class}`Client <deezer.Client>`, but with `async`/`await` support.
+
+## Getting started
+
+The async client should be used as an async context manager:
+
+```python
+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:
+
+```python
+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:
+
+```python
+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. {class}`~deezer.asyncio.AsyncArtist`, {class}`~deezer.asyncio.AsyncAlbum`), which mirror their sync counterparts.
+
+## Navigating relationships
+
+Relationship methods that return a single resource or a plain list need to be awaited:
+
+```python
+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 {class}`~deezer.asyncio.AsyncPaginatedList` immediately usable:
+
+```python
+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 {class}`~deezer.asyncio.AsyncPaginatedList`. This works similarly to the synchronous {class}`~deezer.PaginatedList` described in the {ref}`pagination guide <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:
+
+```python
+albums = await artist.get_albums()
+
+async for album in albums:
+    print(album.title)
+```
+
+### Total number
+
+The total number of items is available via the {attr}`~deezer.asyncio.AsyncPaginatedList.total` property. Since the first page is fetched eagerly, the total is already available without any extra API call:
+
+```python
+total = albums.total
+# Or using len():
+total = len(albums)
+```
+
+### Accessing elements by index
+
+Use the {meth}`~deezer.asyncio.AsyncPaginatedList.get` method to access an element by index:
+
+```python
+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 {class}`~deezer.PaginatedList`, the async version does not support the `[]` syntax for indexing or slicing. Use the {meth}`~deezer.asyncio.AsyncPaginatedList.get` method for index-based access, or {meth}`~deezer.asyncio.AsyncPaginatedList.collect` to get a plain list that supports regular slicing.
+```
+
+### Collecting all elements
+
+To fetch all pages and get a plain list, use {meth}`~deezer.asyncio.AsyncPaginatedList.collect`:
+
+```python
+all_albums = await albums.collect()
+```
+
+### Search
+
+Search methods also return {class}`~deezer.asyncio.AsyncPaginatedList` and need to be awaited:
+
+```python
+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: {meth}`~deezer.asyncio.AsyncClient.search_albums`, {meth}`~deezer.asyncio.AsyncClient.search_artists`, and {meth}`~deezer.asyncio.AsyncClient.search_playlists`.

{deezer_python-7.2.0 → deezer_python-7.3.0}/docs/index.md

@@ -15,6 +15,7 @@ Deezer-Python: a friendly wrapper around the [Deezer API](http://developers.deez
 installation
 usage
 pagination
+async
 ```
 
 ```{toctree}

{deezer_python-7.2.0 → deezer_python-7.3.0}/pyproject.toml

@@ -1,11 +1,10 @@
 [build-system]
 build-backend = "setuptools.build_meta"
-
 requires = [ "setuptools>=77.0.3" ]
 
 [project]
 name = "deezer-python"
-version = "7.2.0"
+version = "7.3.0"
 description = "A friendly wrapper library for the Deezer API"
 readme = "README.md"
 keywords = [
@@ -32,7 +31,6 @@ classifiers = [
   "Programming Language :: Python :: 3.14",
   "Topic :: Software Development :: Libraries",
 ]
-
 dependencies = [
   "httpx>=0.23",
 ]
@@ -47,14 +45,15 @@ urls.Twitter = "https://twitter.com/_BrunoAlla"
 dev = [
   "coverage>=7,<8",
   "deezer-oauth-cli>=1,<2",
-  "environs>=14,<15",
-  "pytest>=8,<9",
+  "environs>=15,<16",
+  "pytest>=9,<10",
+  "pytest-asyncio",
   "pytest-cov>=7,<8",
   "pytest-mock>=3.6,<4",
   "pytest-vcr>=1,<2",
-  "vcrpy>=7,<8",
+  "ty>=0.0.6,<0.1",
+  "vcrpy>=8,<9",
 ]
-
 docs = [
   "furo>=2023.5.20; python_version>='3.11'",
   "myst-parser>=0.16; python_version>='3.11'",
@@ -64,7 +63,6 @@ docs = [
 
 [tool.ruff]
 line-length = 120
-
 lint.select = [
   "B",   # flake8-bugbear
   "C4",  # flake8-comprehensions
@@ -101,33 +99,21 @@ lint.isort.known-first-party = [ "deezer" ]
 [tool.pyproject-fmt]
 max_supported_python = "3.14"
 
-[tool.pytest.ini_options]
-addopts = "-v -Wdefault --cov=deezer"
+[tool.pytest]
+minversion = "9.0"
+addopts = [ "-v", "-Wdefault", "--cov=deezer" ]
 pythonpath = [ "src" ]
 
-[tool.coverage.run]
-branch = true
-source = [ "deezer" ]
-
-[tool.coverage.report]
-ignore_errors = true
-exclude_lines = [
-  "pragma: no cover",
+[tool.coverage]
+run.branch = true
+run.source = [ "deezer" ]
+report.exclude_lines = [
   "@overload",
   "if TYPE_CHECKING",
+  "pragma: no cover",
   "raise NotImplementedError",
 ]
-
-[tool.mypy]
-# suppress errors about unsatisfied imports
-ignore_missing_imports = true
-
-no_implicit_optional = true
-
-# ensure all execution paths are returning
-warn_no_return = true
-
-show_error_codes = true
+report.ignore_errors = true
 
 [tool.semantic_release]
 version_toml = [ "pyproject.toml:project.version" ]
@@ -140,23 +126,13 @@ uv lock
 git add uv.lock
 uv build
 """
-
-[tool.semantic_release.changelog]
-exclude_commit_patterns = [
+branches.main.match = "main"
+branches.noop.match = "(?!main$)"
+branches.noop.prerelease = true
+branches.stable.match = "(?!stable/*$)"
+changelog.exclude_commit_patterns = [
   "chore.*",
   "ci.*",
   "Merge pull request .*",
 ]
-
-[tool.semantic_release.changelog.environment]
-keep_trailing_newline = true
-
-[tool.semantic_release.branches.main]
-match = "main"
-
-[tool.semantic_release.branches.stable]
-match = "(?!stable/*$)"
-
-[tool.semantic_release.branches.noop]
-match = "(?!main$)"
-prerelease = true
+changelog.environment.keep_trailing_newline = true

{deezer_python-7.2.0 → deezer_python-7.3.0}/src/deezer/__init__.py

@@ -15,7 +15,7 @@ from deezer.resources import (
     User,
 )
 
-__version__ = "7.2.0"
+__version__ = "7.3.0"
 __all__ = [
     "Album",
     "Artist",

deezer_python-7.3.0/src/deezer/_mixin.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from deezer.exceptions import DeezerUnknownResource
+from deezer.resources import (
+    Album,
+    Artist,
+    Chart,
+    Editorial,
+    Episode,
+    Genre,
+    Playlist,
+    Podcast,
+    Radio,
+    Resource,
+    Track,
+    User,
+)
+
+
+class DeezerMixin:
+    """Mixin providing shared logic for both sync and async Deezer clients."""
+
+    _resource_base_class: ClassVar[type[Resource]] = Resource
+
+    objects_types: ClassVar[dict[str, type[Resource] | None]] = {
+        "album": Album,
+        "artist": Artist,
+        "chart": Chart,
+        "editorial": Editorial,
+        "episode": Episode,
+        "genre": Genre,
+        "playlist": Playlist,
+        "podcast": Podcast,
+        "radio": Radio,
+        "search": None,
+        "track": Track,
+        "user": User,
+    }
+
+    def _process_json(
+        self,
+        item: dict[str, Any],
+        parent: Any = None,
+        resource_type: type[Any] | None = None,
+        resource_id: int | None = None,
+        paginate_list=False,
+    ):
+        """
+        Recursively convert dictionary to :class:`~deezer.Resource` object.
+
+        :param item: the JSON response as dict.
+        :param parent: A reference to the parent resource, to avoid fetching again.
+        :param resource_type: The resource class to use as top level.
+        :param resource_id: The resource id to use as top level.
+        :param paginate_list: Whether to wrap list into a pagination object.
+        :returns: instance of :class:`~deezer.Resource`
+        """
+        if "data" in item:
+            parsed_data = [self._process_json(i, parent, paginate_list=False) for i in item["data"]]
+            if not paginate_list:
+                return parsed_data
+            item["data"] = parsed_data
+            return item
+
+        result = {}
+        for key, value in item.items():
+            if isinstance(value, dict) and ("type" in value or "data" in value):
+                value = self._process_json(value, parent)
+            result[key] = value
+        if parent is not None:
+            result[parent.type] = parent
+
+        if "id" not in result and resource_id is not None:
+            result["id"] = resource_id
+
+        if "type" in result and result["type"] in self.objects_types:
+            object_class = self.objects_types[result["type"]]
+        elif "type" in result or (not resource_type and "id" in result):
+            object_class = self._resource_base_class
+        elif resource_type:
+            object_class = resource_type
+        elif item.get("results") is True:
+            return True
+        else:
+            raise DeezerUnknownResource(f"Unable to find resource type for {result!r}")
+        assert object_class is not None  # noqa S101
+        return object_class(self, result)

deezer_python-7.3.0/src/deezer/asyncio/__init__.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from .client import AsyncClient
+from .pagination import AsyncPaginatedList
+from .resources import (
+    AsyncAlbum,
+    AsyncArtist,
+    AsyncChart,
+    AsyncEditorial,
+    AsyncEpisode,
+    AsyncGenre,
+    AsyncPlaylist,
+    AsyncPodcast,
+    AsyncRadio,
+    AsyncResource,
+    AsyncTrack,
+    AsyncUser,
+)
+
+__all__ = [
+    "AsyncAlbum",
+    "AsyncArtist",
+    "AsyncChart",
+    "AsyncClient",
+    "AsyncEditorial",
+    "AsyncEpisode",
+    "AsyncGenre",
+    "AsyncPaginatedList",
+    "AsyncPlaylist",
+    "AsyncPodcast",
+    "AsyncRadio",
+    "AsyncResource",
+    "AsyncTrack",
+    "AsyncUser",
+]