deezer-python 7.2.0__py3-none-any.whl → 7.4.0__py3-none-any.whl

deezer/asyncio/pagination.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, TypeVar
+from urllib.parse import parse_qs, urlparse
+
+if TYPE_CHECKING:
+    from deezer.asyncio.client import AsyncClient
+    from deezer.asyncio.resources.resource import AsyncResource
+
+ResourceType = TypeVar("ResourceType")
+
+
+class AsyncPaginatedList(Generic[ResourceType]):
+    """
+    Async paginated response from the API, supporting async iteration.
+
+    Instances should be created via the :meth:`create` classmethod,
+    which fetches the first page of results eagerly.
+    """
+
+    def __init__(
+        self,
+        client: AsyncClient,
+        base_path: str,
+        parent: AsyncResource | None = None,
+        params: dict | None = None,
+    ):
+        self.__elements: list[ResourceType] = []
+        self.__client = client
+        self.__base_path = base_path
+        self.__base_params = params or {}
+        self.__next_path: str | None = base_path
+        self.__next_params = params or {}
+        self.__parent = parent
+        self.__total: int | None = None
+        self.__iter_index = 0
+
+    @classmethod
+    async def create(
+        cls,
+        client: AsyncClient,
+        base_path: str,
+        parent: AsyncResource | None = None,
+        params: dict | None = None,
+    ) -> AsyncPaginatedList[ResourceType]:
+        """Create an AsyncPaginatedList and fetch the first page."""
+        instance = cls(client=client, base_path=base_path, parent=parent, params=params)
+        await instance._grow()
+        return instance
+
+    def __repr__(self) -> str:
+        """Convenient representation giving a preview of the content."""
+        repr_size = 5
+        data: list[ResourceType | str] = list(self.__elements[: repr_size + 1])
+        if len(data) > repr_size:
+            data[-1] = "..."
+        return f"<{self.__class__.__name__} {data!r}>"
+
+    def __aiter__(self):
+        """Return the async iterator."""
+        return self._async_iter()
+
+    async def _async_iter(self):
+        """Iterate over elements, fetching new pages as needed."""
+        yield_index = 0
+        while True:
+            if yield_index < len(self.__elements):
+                yield self.__elements[yield_index]
+                yield_index += 1
+            elif self._could_grow():
+                await self._grow()
+            else:
+                break
+
+    async def __anext__(self) -> ResourceType:
+        """Get the next item from the list."""
+        if self.__iter_index < len(self.__elements):
+            item = self.__elements[self.__iter_index]
+            self.__iter_index += 1
+            return item
+        if self._could_grow():
+            new_elements = await self._grow()
+            if new_elements and self.__iter_index < len(self.__elements):
+                item = self.__elements[self.__iter_index]
+                self.__iter_index += 1
+                return item
+        raise StopAsyncIteration
+
+    @property
+    def total(self) -> int:
+        """The total number of items in the list, mirroring what Deezer returns."""
+        assert self.__total is not None  # noqa S101
+        return self.__total
+
+    def __len__(self) -> int:
+        """Get the total number of items across all pages."""
+        return self.total
+
+    async def get(self, index: int) -> ResourceType:
+        """Get an item by index."""
+        if index < 0:
+            raise IndexError(f"Negative indexing is not supported: {index}")
+        await self._fetch_to_index(index)
+        if index >= len(self.__elements):
+            raise IndexError(f"list index out of range: {index}")
+        return self.__elements[index]
+
+    async def collect(self) -> list[ResourceType]:
+        """Fetch all pages and return the full list of items."""
+        while self._could_grow():
+            await self._grow()
+        return list(self.__elements)
+
+    def _could_grow(self) -> bool:
+        return self.__next_path is not None
+
+    async def _grow(self) -> list[ResourceType]:
+        new_elements = await self._fetch_next_page()
+        self.__elements.extend(new_elements)
+        return new_elements
+
+    async def _fetch_next_page(self) -> list[ResourceType]:
+        assert self.__next_path is not None  # noqa S101
+        response_payload = await self.__client.request(
+            "GET",
+            self.__next_path,
+            parent=self.__parent,
+            paginate_list=True,
+            params=self.__next_params,
+        )
+        self.__next_path = None
+        self.__total = response_payload.get("total")
+        next_url = response_payload.get("next", None)
+        if next_url:
+            url_bits = urlparse(next_url)
+            self.__next_path = url_bits.path.lstrip("/")
+            self.__next_params = parse_qs(url_bits.query)
+        return response_payload["data"]
+
+    async def _fetch_to_index(self, index: int):
+        while len(self.__elements) <= index and self._could_grow():
+            await self._grow()

deezer/asyncio/resources/__init__.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from .album import AsyncAlbum
+from .artist import AsyncArtist
+from .chart import AsyncChart
+from .editorial import AsyncEditorial
+from .episode import AsyncEpisode
+from .genre import AsyncGenre
+from .playlist import AsyncPlaylist
+from .podcast import AsyncPodcast
+from .radio import AsyncRadio
+from .resource import AsyncResource
+from .track import AsyncTrack
+from .user import AsyncUser
+
+__all__ = [
+    "AsyncAlbum",
+    "AsyncArtist",
+    "AsyncChart",
+    "AsyncEditorial",
+    "AsyncEpisode",
+    "AsyncGenre",
+    "AsyncPlaylist",
+    "AsyncPodcast",
+    "AsyncRadio",
+    "AsyncResource",
+    "AsyncTrack",
+    "AsyncUser",
+]

deezer/asyncio/resources/album.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import datetime as dt
+from typing import TYPE_CHECKING
+
+from deezer.dates import parse_date
+
+from .artist import AsyncArtist
+from .resource import AsyncResource
+
+if TYPE_CHECKING:
+    from deezer.asyncio.pagination import AsyncPaginatedList
+
+
+class AsyncAlbum(AsyncResource):
+    """
+    Async album resource.
+
+    Mirrors the sync Album but with async methods for
+    traversing relations.
+    """
+
+    id: int
+    title: str
+    upc: str
+    link: str
+    share: str
+    cover: str
+    cover_small: str
+    cover_medium: str
+    cover_big: str
+    cover_xl: str
+    md5_image: str
+
+    genre_id: int
+    label: str
+    nb_tracks: int
+    duration: int
+    fans: int
+    release_date: dt.date
+    record_type: str
+    available: bool
+
+    tracklist: str
+    explicit_lyrics: bool
+
+    explicit_content_lyrics: int
+    explicit_content_cover: int
+    contributors: list[AsyncArtist]
+
+    artist: AsyncArtist
+
+    _parse_release_date = staticmethod(parse_date)
+
+    def _parse_contributors(self, raw_value):
+        return [AsyncArtist(client=self.client, json=val) for val in raw_value]
+
+    async def get_artist(self) -> AsyncArtist:
+        """
+        Get the artist of the Album.
+
+        :returns: an :class:`AsyncArtist` object
+        """
+        return await self.client.request("GET", f"artist/{self.artist.id}")
+
+    async def get_tracks(self, **kwargs) -> AsyncPaginatedList:
+        """
+        Get a list of album's tracks.
+
+        :returns: an :class:`AsyncPaginatedList` of track resources.
+        """
+        return await self.get_paginated_list("tracks", **kwargs)

deezer/asyncio/resources/artist.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .resource import AsyncResource
+
+if TYPE_CHECKING:
+    from deezer.asyncio.pagination import AsyncPaginatedList
+
+    from .album import AsyncAlbum
+
+
+class AsyncArtist(AsyncResource):
+    """To work with async Deezer artist objects."""
+
+    id: int
+    name: str
+    link: str
+    share: str
+    picture: str
+    picture_small: str
+    picture_medium: str
+    picture_big: str
+    picture_xl: str
+    nb_album: int
+    nb_fan: int
+    radio: bool
+    tracklist: str
+
+    async def get_top(self, **kwargs) -> AsyncPaginatedList:
+        """Get the top tracks of an artist."""
+        return await self.get_paginated_list("top", **kwargs)
+
+    async def get_related(self, **kwargs) -> AsyncPaginatedList[AsyncArtist]:
+        """Get a list of related artists."""
+        return await self.get_paginated_list("related", **kwargs)
+
+    async def get_radio(self, **kwargs) -> list:
+        """Get a list of tracks."""
+        return await self.get_relation("radio", fwd_parent=False, **kwargs)
+
+    async def get_albums(self, **kwargs) -> AsyncPaginatedList[AsyncAlbum]:
+        """Get a list of artist's albums."""
+        return await self.get_paginated_list("albums", **kwargs)
+
+    async def get_playlists(self, **kwargs) -> AsyncPaginatedList:
+        """Get a list of artist's playlists."""
+        return await self.get_paginated_list("playlists", **kwargs)

deezer/asyncio/resources/chart.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .resource import AsyncResource
+
+if TYPE_CHECKING:
+    from deezer.asyncio.pagination import AsyncPaginatedList
+
+
+class AsyncChart(AsyncResource):
+    """Async chart resource."""
+
+    type = "chart"
+
+    id: int
+
+    async def get_tracks(self, **kwargs) -> AsyncPaginatedList:
+        """Return the chart for tracks."""
+        return await self.get_paginated_list("tracks", **kwargs)
+
+    async def get_albums(self, **kwargs) -> AsyncPaginatedList:
+        """Return the chart for albums."""
+        return await self.get_paginated_list("albums", **kwargs)
+
+    async def get_artists(self, **kwargs) -> AsyncPaginatedList:
+        """Return the chart for artists."""
+        return await self.get_paginated_list("artists", **kwargs)
+
+    async def get_playlists(self, **kwargs) -> AsyncPaginatedList:
+        """Return the chart for playlists."""
+        return await self.get_paginated_list("playlists", **kwargs)
+
+    async def get_podcasts(self, **kwargs) -> AsyncPaginatedList:
+        """Return the chart for podcasts."""
+        return await self.get_paginated_list("podcasts", **kwargs)

deezer/asyncio/resources/editorial.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .chart import AsyncChart
+from .resource import AsyncResource
+
+if TYPE_CHECKING:
+    from deezer.asyncio.pagination import AsyncPaginatedList
+
+
+class AsyncEditorial(AsyncResource):
+    """Async editorial resource."""
+
+    id: int
+    name: str
+    picture: str
+    picture_small: str
+    picture_medium: str
+    picture_big: str
+    picture_xl: str
+
+    async def get_selection(self) -> list:
+        """Get a list of albums selected every week by the Deezer Team."""
+        return await self.get_relation("selection")
+
+    async def get_chart(self):
+        """Get top charts for tracks, albums, artists and playlists."""
+        return await self.get_relation("charts", resource_type=AsyncChart)
+
+    async def get_releases(self, **kwargs) -> AsyncPaginatedList:
+        """Get the new releases per genre for the current country."""
+        return await self.get_paginated_list("releases", **kwargs)

deezer/asyncio/resources/episode.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import datetime as dt
+from typing import TYPE_CHECKING
+
+from deezer.dates import parse_datetime
+
+from .resource import AsyncResource
+
+if TYPE_CHECKING:
+    from .podcast import AsyncPodcast
+
+
+class AsyncEpisode(AsyncResource):
+    """Async episode resource."""
+
+    id: int
+    title: str
+    description: str
+    available: bool
+    release_date: dt.datetime
+    duration: int
+    link: str
+    share: str
+    picture: str
+    picture_small: str
+    picture_medium: str
+    picture_big: str
+    picture_xl: str
+    podcast: AsyncPodcast
+
+    _parse_release_date = staticmethod(parse_datetime)
+
+    async def add_bookmark(self, offset: int) -> bool:
+        """Set a bookmark on the episode."""
+        return await self.client.request(
+            "POST",
+            f"episode/{self.id}/bookmark",
+            params={"offset": offset},
+        )
+
+    async def remove_bookmark(self) -> bool:
+        """Remove the bookmark on the episode."""
+        return await self.client.request("DELETE", f"episode/{self.id}/bookmark")

deezer/asyncio/resources/genre.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .resource import AsyncResource
+
+if TYPE_CHECKING:
+    from deezer.asyncio.pagination import AsyncPaginatedList
+
+
+class AsyncGenre(AsyncResource):
+    """Async genre resource."""
+
+    id: int
+    name: str
+    picture: str
+    picture_small: str
+    picture_medium: str
+    picture_big: str
+    picture_xl: str
+
+    async def get_artists(self, **kwargs) -> list:
+        """Get all artists for a genre."""
+        return await self.get_relation("artists", **kwargs)
+
+    async def get_podcasts(self, **kwargs) -> AsyncPaginatedList:
+        """Get all podcasts for a genre."""
+        return await self.get_paginated_list("podcasts", **kwargs)
+
+    async def get_radios(self, **kwargs) -> list:
+        """Get all radios for a genre."""
+        return await self.get_relation("radios", **kwargs)

deezer/asyncio/resources/playlist.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from deezer.utils import gen_ids
+
+from .resource import AsyncResource
+
+if TYPE_CHECKING:
+    from deezer.asyncio.pagination import AsyncPaginatedList
+
+
+class AsyncPlaylist(AsyncResource):
+    """Async playlist resource."""
+
+    id: int
+    title: str
+    description: str
+    duration: int
+    public: bool
+    is_loved_track: bool
+    collaborative: bool
+    nb_tracks: int
+    unseen_track_count: int
+    fans: int
+    link: str
+    share: str
+    picture: str
+    picture_small: str
+    picture_medium: str
+    picture_big: str
+    picture_xl: str
+    checksum: str
+
+    async def get_tracks(self, **kwargs) -> AsyncPaginatedList:
+        """Get tracks from a playlist."""
+        return await self.get_paginated_list("tracks", **kwargs)
+
+    async def get_fans(self, **kwargs) -> AsyncPaginatedList:
+        """Get fans from a playlist."""
+        return await self.get_paginated_list("fans", **kwargs)
+
+    async def mark_seen(self) -> bool:
+        """Mark the playlist as seen."""
+        return await self.client.request("POST", f"playlist/{self.id}/seen")
+
+    async def add_tracks(self, tracks: Iterable[int]) -> bool:
+        """Add tracks to a playlist."""
+        track_ids_str = ",".join(str(tid) for tid in gen_ids(tracks))
+        return await self.client.request("POST", f"playlist/{self.id}/tracks", params={"songs": track_ids_str})
+
+    async def delete_tracks(self, tracks: Iterable[int]) -> bool:
+        """Delete tracks from a playlist."""
+        track_ids_str = ",".join(map(str, gen_ids(tracks)))
+        return await self.client.request("DELETE", f"playlist/{self.id}/tracks", params={"songs": track_ids_str})
+
+    async def reorder_tracks(self, order: Iterable[int]) -> bool:
+        """Reorder the tracks of a playlist."""
+        order_track_ids_str = ",".join(map(str, gen_ids(order)))
+        return await self.client.request("POST", f"playlist/{self.id}/tracks", params={"order": order_track_ids_str})

deezer/asyncio/resources/podcast.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .resource import AsyncResource
+
+if TYPE_CHECKING:
+    from deezer.asyncio.pagination import AsyncPaginatedList
+
+
+class AsyncPodcast(AsyncResource):
+    """Async podcast resource."""
+
+    id: int
+    title: str
+    description: str
+    available: bool
+    fans: int
+    link: str
+    share: str
+    picture: str
+    picture_small: str
+    picture_medium: str
+    picture_big: str
+    picture_xl: str
+
+    async def get_episodes(self, **kwargs) -> AsyncPaginatedList:
+        """Get episodes from a podcast."""
+        return await self.get_paginated_list("episodes", **kwargs)

deezer/asyncio/resources/radio.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from .resource import AsyncResource
+
+
+class AsyncRadio(AsyncResource):
+    """Async radio resource."""
+
+    id: int
+    title: str
+    description: str
+    share: str
+    picture: str
+    picture_small: str
+    picture_medium: str
+    picture_big: str
+    picture_xl: str
+    tracklist: str
+    md5_image: str
+
+    async def get_tracks(self) -> list:
+        """Get first 40 tracks in the radio."""
+        return await self.get_relation("tracks")

deezer/asyncio/resources/resource.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any
+
+from deezer.asyncio.pagination import AsyncPaginatedList
+
+
+class AsyncResource:
+    """
+    Base class for async resources.
+
+    Mirrors the sync Resource but with async methods for
+    traversing relations via the async client.
+    """
+
+    id: int
+    type: str
+
+    _fields: tuple[str, ...]
+
+    def __init__(self, client, json):
+        self.client = client
+        for field_name in json.keys():
+            parse_func = getattr(self, f"_parse_{field_name}", None)
+            if callable(parse_func):
+                json[field_name] = parse_func(json[field_name])
+        self._fields = tuple(json.keys())
+        for key in json:
+            setattr(self, key, json[key])
+
+    def __repr__(self):
+        """Convenient representation giving a preview of the item."""
+        name = getattr(self, "name", None)
+        title = getattr(self, "title", None)
+        id_ = getattr(self, "id", None)
+        return f"<{self.__class__.__name__}: {name or title or id_}>"
+
+    def as_dict(self) -> dict[str, Any]:
+        """Convert resource to dictionary."""
+        result = {}
+        for key in self._fields:
+            value = getattr(self, key)
+            if isinstance(value, list):
+                value = [i.as_dict() if isinstance(i, AsyncResource) else i for i in value]
+            elif isinstance(value, AsyncResource):
+                value = value.as_dict()
+            elif isinstance(value, dt.datetime):
+                value = f"{value:%Y-%m-%d %H:%M:%S}"
+            elif isinstance(value, dt.date):
+                value = value.isoformat()
+            result[key] = value
+        return result
+
+    async def get_relation(
+        self,
+        relation: str,
+        resource_type: type[AsyncResource] | None = None,
+        params: dict | None = None,
+        fwd_parent: bool = True,
+    ):
+        """
+        Generic async method to load the relation from any resource.
+
+        Query the client with the object's known parameters
+        and try to retrieve the provided relation type.
+        """
+        return await self.client.request(
+            "GET",
+            f"{self.type}/{self.id}/{relation}",
+            parent=self if fwd_parent else None,
+            resource_type=resource_type,
+            params=params,
+        )
+
+    async def post_relation(self, relation: str, params: dict):
+        """Generic async method to make a POST request to a relation."""
+        return await self.client.request(
+            "POST",
+            f"{self.type}/{self.id}/{relation}",
+            params=params,
+        )
+
+    async def delete_relation(self, relation: str, params: dict | None = None):
+        """Generic async method to make a DELETE request to a relation."""
+        return await self.client.request(
+            "DELETE",
+            f"{self.type}/{self.id}/{relation}",
+            params=params,
+        )
+
+    async def get_paginated_list(
+        self,
+        relation: str,
+        params: dict | None = None,
+    ) -> AsyncPaginatedList:
+        """Build the pagination object based on the relation."""
+        return await AsyncPaginatedList.create(
+            client=self.client,
+            base_path=f"{self.type}/{self.id}/{relation}",
+            parent=self,
+            params=params,
+        )