deezer-python 6.1.0__py3-none-any.whl → 6.2.0__py3-none-any.whl

deezer/__init__.py

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

deezer/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Any
+import warnings
+from typing import Any, ClassVar
 
 import requests
 
@@ -25,6 +26,8 @@ from deezer.resources import (
     User,
 )
 
+_UNSET = object()
+
 
 class Client:
     """
@@ -34,10 +37,10 @@ class Client:
     be passed in to the constructor as kwargs.
 
         >>> import deezer
-        >>> client = deezer.Client(app_id='foo', app_secret='bar')
+        >>> client = deezer.Client()
 
-    This client provides several method to retrieve the content of most
-    sort of Deezer objects, based on their json structure.
+    This client provides several methods to retrieve the content most
+    kinds of Deezer objects, based on their json structure.
 
     Headers can be forced by using the ``headers`` kwarg.
     For example, use ``Accept-Language`` header to force the output language.
@@ -45,13 +48,20 @@ class Client:
         >>> import deezer
         >>> client = deezer.Client(headers={'Accept-Language': 'fr'})
 
-    :param app_id: application ID.
-    :param app_secret: application secret.
     :param access_token: user access token.
     :param headers: a dictionary of headers to be used.
+
+    .. deprecated:: 6.2.0
+
+        The following parameters will be removed in the next major version:
+
+            * **app_id**
+            * **app_secret**
+
+        They were never actively used by the package.
     """
 
-    objects_types = {
+    objects_types: ClassVar[dict[str, type[Resource] | None]] = {
         "album": Album,
         "artist": Artist,
         "chart": Chart,
@@ -69,10 +79,29 @@ class Client:
     base_url = "https://api.deezer.com"
 
     def __init__(
-        self, app_id=None, app_secret=None, access_token=None, headers=None, **kwargs
+        self,
+        app_id=_UNSET,
+        app_secret=_UNSET,
+        access_token=None,
+        headers=None,
+        **kwargs,
     ):
-        self.app_id = app_id
-        self.app_secret = app_secret
+        if app_id is not _UNSET:
+            warnings.warn(
+                "The 'app_id' parameter is not actually used and is deprecated. "
+                "It will be removed in the next major release.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            self.app_id = app_id
+        if app_secret is not _UNSET:
+            warnings.warn(
+                "The 'app_secret' parameter is not actually used and is deprecated. "
+                "It will be removed in the next major release.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            self.app_secret = app_secret
         self.access_token = access_token
         self.session = requests.Session()
 
@@ -88,8 +117,7 @@ class Client:
         paginate_list=False,
     ):
         """
-        Recursively convert dictionary
-        to :class:`~deezer.Resource` object
+        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.
@@ -129,7 +157,7 @@ class Client:
             return True
         else:
             raise DeezerUnknownResource(f"Unable to find resource type for {result!r}")
-        assert object_class is not None  # nosec B101
+        assert object_class is not None  # noqa S101
         return object_class(self, result)
 
     def request(
@@ -167,7 +195,7 @@ class Client:
         json_data = response.json()
         if not isinstance(json_data, dict):
             return json_data
-        if "error" in json_data and json_data["error"]:
+        if json_data.get("error"):
             raise DeezerErrorResponse(json_data)
         return self._process_json(
             json_data,
@@ -281,7 +309,7 @@ class Client:
 
     def get_genre(self, genre_id: int) -> Genre:
         """
-        Get the genre with the given ID
+        Get the genre with the given ID.
 
         :returns: a :class:`~deezer.Genre` object
         """
@@ -419,7 +447,7 @@ class Client:
 
     def add_user_album(self, album_id: int) -> bool:
         """
-        Add an album to the user's library
+        Add an album to the user's library.
 
         :param album_id: the ID of the album to add.
         :return: boolean whether the operation succeeded.
@@ -428,7 +456,7 @@ class Client:
 
     def remove_user_album(self, album_id: int) -> bool:
         """
-        Remove an album from the user's library
+        Remove an album from the user's library.
 
         :param album_id: the ID of the album to remove.
         :return: boolean whether the operation succeeded.
@@ -448,7 +476,7 @@ class Client:
 
     def add_user_artist(self, artist_id: int) -> bool:
         """
-        Add an artist to the user's library
+        Add an artist to the user's library.
 
         :param artist_id: the ID of the artist to add.
         :return: boolean whether the operation succeeded.
@@ -457,7 +485,7 @@ class Client:
 
     def remove_user_artist(self, artist_id: int) -> bool:
         """
-        Remove an artist from the user's library
+        Remove an artist from the user's library.
 
         :param artist_id: the ID of the artist to remove.
         :return: boolean whether the operation succeeded.
@@ -526,7 +554,7 @@ class Client:
 
     def add_user_track(self, track_id: int) -> bool:
         """
-        Add a track to the user's library
+        Add a track to the user's library.
 
         :param track_id: the ID of the track to add.
         :return: boolean whether the operation succeeded.
@@ -535,7 +563,7 @@ class Client:
 
     def remove_user_track(self, track_id: int) -> bool:
         """
-        Remove a track from the user's library
+        Remove a track from the user's library.
 
         :param track_id: the ID of the track to remove.
         :return: boolean whether the operation succeeded.
@@ -544,7 +572,7 @@ class Client:
 
     def remove_user_playlist(self, playlist_id: int) -> bool:
         """
-        Remove a playlist from the user's library
+        Remove a playlist from the user's library.
 
         :param playlist_id: the ID of the playlist to remove.
         :return: boolean whether the operation succeeded.
@@ -553,7 +581,7 @@ class Client:
 
     def add_user_playlist(self, playlist_id: int) -> bool:
         """
-        Add a playlist to the user's library
+        Add a playlist to the user's library.
 
         :param playlist_id: the ID of the playlist to add.
         :return: boolean whether the operation succeeded.
@@ -562,7 +590,7 @@ class Client:
 
     def create_playlist(self, playlist_name) -> int:
         """
-        Create a playlist on the user's account
+        Create a playlist on the user's account.
 
         :param playlist_name: the name of the playlist.
         :return: the ID of the playlist that was created
@@ -574,7 +602,7 @@ class Client:
 
     def delete_playlist(self, playlist_id) -> bool:
         """
-        Delete a playlist from the user's account
+        Delete a playlist from the user's account.
 
         :param playlist_id: the ID of the playlist to remove.
         :return: boolean whether the operation succeeded.

deezer/dates.py

@@ -7,6 +7,7 @@ DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S"
 
 
 def parse_date(date_str: str) -> dt.date | None:
+    """Parse a date from a string to a date object."""
     datetime = parse_datetime(date_str, DATE_FORMAT)
     return datetime.date() if datetime else None
 
@@ -15,6 +16,7 @@ def parse_datetime(
     datetime_str: str,
     date_format: str = DATETIME_FORMAT,
 ) -> dt.datetime | None:
+    """Parse a datetime from a string to a datetime object."""
     if not datetime_str or datetime_str.startswith("0000-00-00"):
         return None
     return dt.datetime.strptime(datetime_str, date_format)

deezer/exceptions.py

@@ -25,12 +25,14 @@ class DeezerHTTPError(DeezerAPIException):
 
     @classmethod
     def from_http_error(cls, exc: requests.HTTPError) -> DeezerHTTPError:
-        if exc.response.status_code in {502, 503, 504}:
-            return DeezerRetryableHTTPError(exc)
-        if exc.response.status_code == 403:
-            return DeezerForbiddenError(exc)
-        if exc.response.status_code == 404:
-            return DeezerNotFoundError(exc)
+        """Initialise the appropriate internal exception from a HTTPError."""
+        if exc.response is not None:
+            if exc.response.status_code in {502, 503, 504}:
+                return DeezerRetryableHTTPError(exc)
+            if exc.response.status_code == 403:
+                return DeezerForbiddenError(exc)
+            if exc.response.status_code == 404:
+                return DeezerNotFoundError(exc)
         return DeezerHTTPError(exc)
 
 

deezer/pagination.py

@@ -33,6 +33,7 @@ class PaginatedList(Generic[ResourceType]):
         self.__iter = iter(self)
 
     def __repr__(self) -> str:
+        """Convenient representation giving a preview of the content."""
         repr_size = 5
         data: list[ResourceType | str] = list(self[: repr_size + 1])
         if len(data) > repr_size:
@@ -40,17 +41,16 @@ class PaginatedList(Generic[ResourceType]):
         return f"<{self.__class__.__name__} {data!r}>"
 
     @overload
-    def __getitem__(self, index: int) -> ResourceType:
-        ...
+    def __getitem__(self, index: int) -> ResourceType: ...
 
     @overload
-    def __getitem__(self, index: slice) -> list[ResourceType]:
-        ...
+    def __getitem__(self, index: slice) -> list[ResourceType]: ...
 
     def __getitem__(
         self,
         index: int | slice,
     ) -> ResourceType | list[ResourceType]:
+        """Get an item or a slice of items from the list."""
         if isinstance(index, int):
             self._fetch_to_index(index)
             return self.__elements[index]
@@ -62,14 +62,17 @@ class PaginatedList(Generic[ResourceType]):
         return self.__elements[index]
 
     def __iter__(self) -> Generator[ResourceType, None, None]:
+        """Iterate over the internal, fetching new pages as needed."""
         yield from self.__elements
         while self._could_grow():
             yield from self._grow()
 
     def __next__(self) -> ResourceType:
+        """Get the next item from the list."""
         return next(self.__iter)
 
     def __len__(self) -> int:
+        """Get the total number of items across all pages."""
         return self.total
 
     def _could_grow(self) -> bool:
@@ -81,7 +84,7 @@ class PaginatedList(Generic[ResourceType]):
         return new_elements
 
     def _fetch_next_page(self) -> list[ResourceType]:
-        assert self.__next_path is not None  # nosec B101
+        assert self.__next_path is not None  # noqa S101
         response_payload = self.__client.request(
             "GET",
             self.__next_path,
@@ -116,5 +119,5 @@ class PaginatedList(Generic[ResourceType]):
                 **params,
             )
             self.__total = response_payload["total"]
-        assert self.__total is not None  # nosec B101
+        assert self.__total is not None  # noqa S101
         return self.__total

deezer/resources/chart.py

@@ -32,35 +32,45 @@ class Chart(Resource):
 
     def get_tracks(self, **kwargs) -> PaginatedList[Track]:
         """
+        Return the chart for tracks.
+
         :returns: a :class:`PaginatedList <deezer.PaginatedList>`
-                  of :class:`Track <deezer.Track>` instances
+        of :class:`Track <deezer.Track>` instances
         """
         return self.get_paginated_list("tracks", **kwargs)
 
     def get_albums(self, **kwargs) -> PaginatedList[Album]:
         """
+        Return the chart for albums.
+
         :returns: a :class:`PaginatedList <deezer.PaginatedList>`
-                  of :class:`Album <deezer.Album>` instances
+        of :class:`Album <deezer.Album>` instances
         """
         return self.get_paginated_list("albums", **kwargs)
 
     def get_artists(self, **kwargs) -> PaginatedList[Artist]:
         """
+        Return the chart for artists.
+
         :returns: a :class:`PaginatedList <deezer.PaginatedList>`
-                  of :class:`Artist <deezer.Artist>` instances
+        of :class:`Artist <deezer.Artist>` instances
         """
         return self.get_paginated_list("artists", **kwargs)
 
     def get_playlists(self, **kwargs) -> PaginatedList[Playlist]:
         """
+        Return the chart for playlists.
+
         :returns: a :class:`PaginatedList <deezer.PaginatedList>`
-                  of :class:`Playlist <deezer.Playlist>` instances
+        of :class:`Playlist <deezer.Playlist>` instances
         """
         return self.get_paginated_list("playlists", **kwargs)
 
     def get_podcasts(self, **kwargs) -> PaginatedList[Podcast]:
         """
+        Return the chart for podcasts.
+
         :returns: a :class:`PaginatedList <deezer.PaginatedList>`
-                  of :class:`Podcast <deezer.Podcast>` instances
+        of :class:`Podcast <deezer.Podcast>` instances
         """
         return self.get_paginated_list("podcasts", **kwargs)

deezer/resources/episode.py

@@ -58,7 +58,7 @@ class Episode(Resource):
 
     def remove_bookmark(self, **kwargs) -> bool:
         """
-        Removes the bookmark on the episode
+        Removes the bookmark on the episode.
 
         :returns: a boolean that tells if the operation was successful
         """

deezer/resources/podcast.py

@@ -32,7 +32,7 @@ class Podcast(Resource):
 
     def get_episodes(self, **kwargs) -> PaginatedList[Episode]:
         """
-        Get episodes from a podcast
+        Get episodes from a podcast.
 
         :returns: a :class:`PaginatedList <deezer.PaginatedList>`
                   of :class:`Episode <deezer.Episode>` instances

deezer/resources/resource.py

@@ -34,6 +34,7 @@ class Resource:
             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)
@@ -101,7 +102,8 @@ class Resource:
         self,
         relation: str,
         **kwargs,
-    ):
+    ) -> PaginatedList:
+        """Build the pagination object based on the relation."""
         return PaginatedList(
             client=self.client,
             base_path=f"{self.type}/{self.id}/{relation}",

{deezer_python-6.1.0.dist-info → deezer_python-6.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: deezer-python
-Version: 6.1.0
+Version: 6.2.0
 Summary: A friendly wrapper library for the Deezer API
 Home-page: https://github.com/browniebroke/deezer-python
 License: MIT
@@ -89,7 +89,7 @@ The package is published on
 Easily query the Deezer API from you Python code. The data returned by the Deezer
 API is mapped to python resources:
 
-```python
+```pycon
 >>> client = deezer.Client()
 >>> client.get_album(680407).title
 'Monkey Business'

deezer_python-6.2.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+deezer/__init__.py,sha256=ohzXzQw4o6AhcuubYDivDtiJMIxd_Q69OU2opi4W4Os,556
+deezer/client.py,sha256=Xr_NDiVUT5b-YIkzfresHd76GWrUEgE-MeLYhI7TEKI,25651
+deezer/dates.py,sha256=raTeUAAOkajl0TTzM2cupzieTY0amzTeZCaaT3gp_iU,648
+deezer/exceptions.py,sha256=LmJ9vU_mRQ9o9T26ihD36cIMWMC1lg4sBBLiKta3pQA,2003
+deezer/pagination.py,sha256=MrlUiuKczEHb0bdThwzG9y48M30F4AaobhvReJHzWx8,4041
+deezer/resources/__init__.py,sha256=WLHWGhV5rLyzZe9IjAtVWUsLvNJDWoldgE2JIADC0L4,549
+deezer/resources/album.py,sha256=83PXZNSSkxY7qVVgyvgyHceaV4IMoQxfqcbTR5v-l38,1734
+deezer/resources/artist.py,sha256=A2mZDceh82cQOsMl3cczgm97UCCUHehNeoPYR8IWjds,2150
+deezer/resources/chart.py,sha256=l4l5M7bYcW1-lFKZl874CGWi-gjOVBcskJ-zL5DMcXE,2193
+deezer/resources/editorial.py,sha256=BbYsJeMeGU65dSrO-Wy_oS52zqnVZZni281zdpdb5HQ,1413
+deezer/resources/episode.py,sha256=AuJQZweeu7MMJ89eMPs7RSBoQU4oQeX1O5QMBwDi94E,1762
+deezer/resources/genre.py,sha256=CDWyNyFT3fXQM7jPkz3UtGr8gNtVn9430h11Jl0ZwAc,1355
+deezer/resources/playlist.py,sha256=8pAMmqUG4S9QLZOX5OrEoj4qA8pggDQBVxbG-DNxqgk,3325
+deezer/resources/podcast.py,sha256=FwfOe-m4xI1iRwauZpMjKzXKfLDryDz9Y5cVVzP8wVo,915
+deezer/resources/radio.py,sha256=moOdlSJABqCcluInvgbHSwIzSIhDvBQaVyDGdgeVr_0,805
+deezer/resources/resource.py,sha256=X_65glzz62jHtVB2U-WtuXM8B5E9U2HbjpcRzOdVOiY,4978
+deezer/resources/track.py,sha256=e3DPTsYWq5yNCjMRQhGTrFQHfQUe3xn0mEVYbpL3O_0,1546
+deezer/resources/user.py,sha256=6-46PX80xEgtCY2FecwzzgbvYu1aL1WShFXcCOaVGlU,6752
+deezer/utils.py,sha256=Z4QA5Ud5KPiGGv5buTdUidixmkEF9UhwCoYZiGXE-cE,583
+deezer_python-6.2.0.dist-info/LICENSE.txt,sha256=lGqKEubFaPBoiJVRoHOxg1LYlte1e5kLoq6zWUSRQzQ,1054
+deezer_python-6.2.0.dist-info/METADATA,sha256=4POY_crEa5ogOvMKiy6cmuSbFqwi2ON6khahRQWFw8Y,14629
+deezer_python-6.2.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+deezer_python-6.2.0.dist-info/RECORD,,

{deezer_python-6.1.0.dist-info → deezer_python-6.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.6.1
+Generator: poetry-core 1.9.0
 Root-Is-Purelib: true
 Tag: py3-none-any

deezer_python-6.1.0.dist-info/RECORD

@@ -1,23 +0,0 @@
-deezer/__init__.py,sha256=0NeTLMTWBprgN9H2xa0pe89alLo8Y9PHixGg7TYDjwc,556
-deezer/client.py,sha256=AgFYYDqe3An7momBuR0JqgkZ-c3JPuRWeO72EWUJQ1k,24840
-deezer/dates.py,sha256=BG8Aj6s0ctiQYmeKXowhNzb9--AeDxpWG82w3gA03NE,530
-deezer/exceptions.py,sha256=gsSYTKfKH8BbLJxptPEZC6yfr4baTQ9_kohIogc_HRo,1864
-deezer/pagination.py,sha256=OWLv_eUHQeLeROVPK9i7GmooUzEQ3nNuP2ID0kv8l9Q,3745
-deezer/resources/__init__.py,sha256=WLHWGhV5rLyzZe9IjAtVWUsLvNJDWoldgE2JIADC0L4,549
-deezer/resources/album.py,sha256=83PXZNSSkxY7qVVgyvgyHceaV4IMoQxfqcbTR5v-l38,1734
-deezer/resources/artist.py,sha256=A2mZDceh82cQOsMl3cczgm97UCCUHehNeoPYR8IWjds,2150
-deezer/resources/chart.py,sha256=vD4M-ztwhoffOhR5q1Jsj3-4Gg317skGDaQdmWRDrFA,2047
-deezer/resources/editorial.py,sha256=BbYsJeMeGU65dSrO-Wy_oS52zqnVZZni281zdpdb5HQ,1413
-deezer/resources/episode.py,sha256=YZ-VRD2yZeXi7z5FKF8xwR-T9QKTt69pYQ0H_i1CxKY,1761
-deezer/resources/genre.py,sha256=CDWyNyFT3fXQM7jPkz3UtGr8gNtVn9430h11Jl0ZwAc,1355
-deezer/resources/playlist.py,sha256=8pAMmqUG4S9QLZOX5OrEoj4qA8pggDQBVxbG-DNxqgk,3325
-deezer/resources/podcast.py,sha256=lipRKhlFSXry97l_0xZJHfIxVeOh6VVdL9LhDIHyZbc,914
-deezer/resources/radio.py,sha256=moOdlSJABqCcluInvgbHSwIzSIhDvBQaVyDGdgeVr_0,805
-deezer/resources/resource.py,sha256=cuPXzvcXrsrHTj-UD3c5drhkjRwQ4Dkghik2icwDPGw,4826
-deezer/resources/track.py,sha256=e3DPTsYWq5yNCjMRQhGTrFQHfQUe3xn0mEVYbpL3O_0,1546
-deezer/resources/user.py,sha256=6-46PX80xEgtCY2FecwzzgbvYu1aL1WShFXcCOaVGlU,6752
-deezer/utils.py,sha256=Z4QA5Ud5KPiGGv5buTdUidixmkEF9UhwCoYZiGXE-cE,583
-deezer_python-6.1.0.dist-info/LICENSE.txt,sha256=lGqKEubFaPBoiJVRoHOxg1LYlte1e5kLoq6zWUSRQzQ,1054
-deezer_python-6.1.0.dist-info/METADATA,sha256=SrKSRvc5J8x1JaoqDfgVmm6dB95bAQ0hIop6aQzI8cE,14630
-deezer_python-6.1.0.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
-deezer_python-6.1.0.dist-info/RECORD,,