deezer-python 6.1.0__tar.gz → 6.2.0__tar.gz

{deezer_python-6.1.0 → deezer_python-6.2.0}/PKG-INFO

@@ -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.1.0 → deezer_python-6.2.0}/README.md

@@ -58,7 +58,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.1.0 → deezer_python-6.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "deezer-python"
-version = "6.1.0"
+version = "6.2.0"
 description = "A friendly wrapper library for the Deezer API"
 authors = ["Bruno Alla <alla.brunoo@gmail.com>"]
 license = "MIT"
@@ -34,25 +34,26 @@ requests = ">=2.18"
 optional = true
 
 [tool.poetry.group.docs.dependencies]
-myst-parser = ">=0.16"
-sphinx = ">=4.0"
-sphinx-autobuild = ">=2021.0"
-furo = ">=2023.5.20"
+myst-parser = { version = ">=0.16", python = ">=3.11" }
+sphinx = { version = ">=4.0", python = ">=3.11" }
+furo = { version = ">=2023.5.20", python = ">=3.11" }
+sphinx-autobuild = { version = ">=2024.0.0", python = ">=3.11" }
 
 [tool.poetry.group.dev.dependencies]
 coverage = "^7.0"
-environs = "^9.3"
-pytest = "^7.0"
-pytest-cov = "^4.0"
+environs = "^11.0.0"
+pytest = "^8.0.0"
+pytest-cov = "^5.0.0"
 pytest-mock = "^3.6"
 pytest-vcr = "^1.0"
-vcrpy = "^5.0.0"
+vcrpy = "^6.0.0"
 deezer-oauth-cli = "^1.0.0"
 
 [tool.semantic_release]
 version_toml = ["pyproject.toml:tool.poetry.version"]
-version_variable = "src/deezer/__init__.py:__version__"
-branch = "main"
+version_variables = [
+    "src/deezer/__init__.py:__version__",
+]
 build_command = "pip install poetry && poetry build"
 
 [tool.semantic_release.changelog]
@@ -64,6 +65,16 @@ exclude_commit_patterns = [
 [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
+
 [tool.pytest.ini_options]
 addopts = "-v -Wdefault --cov=deezer"
 pythonpath = ["src"]
@@ -81,9 +92,47 @@ exclude_lines = [
     "raise NotImplementedError",
 ]
 
-[tool.isort]
-profile = "black"
-known_first_party = "deezer"
+[tool.ruff]
+target-version = "py38"
+line-length = 120
+
+[tool.ruff.lint]
+ignore = [
+    "D203", # 1 blank line required before class docstring
+    "D212", # Multi-line docstring summary should start at the first line
+    "D100", # Missing docstring in public module
+    "D104", # Missing docstring in public package
+    "D107", # Missing docstring in `__init__`
+    "D401", # First line of docstring should be in imperative mood
+]
+select = [
+    "B",   # flake8-bugbear
+    "D",   # flake8-docstrings
+    "C4",  # flake8-comprehensions
+    "S",   # flake8-bandit
+    "F",   # pyflake
+    "E",   # pycodestyle
+    "W",   # pycodestyle
+    "UP",  # pyupgrade
+    "I",   # isort
+    "RUF", # ruff specific
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*" = [
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "S101",
+]
+"setup.py" = ["D100"]
+"conftest.py" = ["D100"]
+"docs/conf.py" = ["D100"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["deezer"]
 
 [tool.mypy]
 # suppress errors about unsatisfied imports

{deezer_python-6.1.0 → deezer_python-6.2.0}/src/deezer/__init__.py

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

{deezer_python-6.1.0 → deezer_python-6.2.0}/src/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_python-6.1.0 → deezer_python-6.2.0}/src/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_python-6.1.0 → deezer_python-6.2.0}/src/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_python-6.1.0 → deezer_python-6.2.0}/src/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_python-6.1.0 → deezer_python-6.2.0}/src/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_python-6.1.0 → deezer_python-6.2.0}/src/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_python-6.1.0 → deezer_python-6.2.0}/src/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_python-6.1.0 → deezer_python-6.2.0}/src/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}",