deezer-python-gql 0.17.0__tar.gz → 0.17.2__tar.gz

{deezer_python_gql-0.17.0/deezer_python_gql.egg-info → deezer_python_gql-0.17.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deezer-python-gql
-Version: 0.17.0
+Version: 0.17.2
 Summary: Async typed Python client for Deezer's Pipe GraphQL API.
 Author-email: Julian Daberkow <jdaberkow@users.noreply.github.com>
 License: Apache-2.0
@@ -13,15 +13,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp>=3.13.5
 Requires-Dist: pydantic>=2.0.0
+Requires-Dist: yarl>=1.22.0
 Provides-Extra: test
-Requires-Dist: codespell==2.4.2; extra == "test"
-Requires-Dist: mypy==2.1.0; extra == "test"
-Requires-Dist: pre-commit==4.6.0; extra == "test"
+Requires-Dist: codespell==2.4.3; extra == "test"
+Requires-Dist: mypy==2.3.1; extra == "test"
+Requires-Dist: pre-commit==4.6.2; extra == "test"
 Requires-Dist: pre-commit-hooks==6.0.0; extra == "test"
-Requires-Dist: pytest==9.0.3; extra == "test"
-Requires-Dist: pytest-asyncio==1.3.0; extra == "test"
+Requires-Dist: pytest==9.1.1; extra == "test"
+Requires-Dist: pytest-asyncio==1.4.0; extra == "test"
 Requires-Dist: pytest-cov==7.1.0; extra == "test"
-Requires-Dist: ruff==0.15.13; extra == "test"
+Requires-Dist: ruff==0.16.5; extra == "test"
 Provides-Extra: dev
 Requires-Dist: ariadne-codegen[subscriptions]; extra == "dev"
 Dynamic: license-file
@@ -47,6 +48,7 @@ import asyncio
 
 from deezer_python_gql import DeezerGQLClient
 
+
 async def main():
     client = DeezerGQLClient(arl="YOUR_ARL_COOKIE")
 
@@ -74,6 +76,7 @@ async def main():
     results = await client.search(query="Daft Punk")
     print(len(results.tracks.edges), "tracks found")
 
+
 asyncio.run(main())
 ```
 
@@ -189,7 +192,7 @@ asyncio.run(main())
 
 | Method                           | Description                                                      |
 | -------------------------------- | ---------------------------------------------------------------- |
-| `check_audiobook_ids(album_ids)` | Batch-check which album IDs are audiobooks (single GraphQL call) |
+| `check_audiobook_ids(album_ids)` | Batch-check which album IDs are audiobooks (aliased queries, chunked at 50 IDs) |
 
 All methods return fully-typed Pydantic models generated from the GraphQL schema.
 
@@ -252,6 +255,14 @@ The Pipe API uses short-lived JWTs obtained from an ARL cookie. The base client
 handles token acquisition and refresh automatically — you only need to supply a
 valid ARL value.
 
+An external `aiohttp.ClientSession` may be shared by clients for different Deezer
+accounts. Each client keeps Deezer's response cookies locally and masks cookies from
+the shared session jar, so authentication state cannot cross between those accounts.
+
+If the ARL is rejected (bad or expired), the client raises
+`GraphQLClientAuthError` — catch it to prompt for a new ARL instead of retrying.
+Transient server errors raise `GraphQLClientHttpError` instead.
+
 ## License
 
 Apache-2.0

{deezer_python_gql-0.17.0 → deezer_python_gql-0.17.2}/README.md

@@ -19,6 +19,7 @@ import asyncio
 
 from deezer_python_gql import DeezerGQLClient
 
+
 async def main():
     client = DeezerGQLClient(arl="YOUR_ARL_COOKIE")
 
@@ -46,6 +47,7 @@ async def main():
     results = await client.search(query="Daft Punk")
     print(len(results.tracks.edges), "tracks found")
 
+
 asyncio.run(main())
 ```
 
@@ -161,7 +163,7 @@ asyncio.run(main())
 
 | Method                           | Description                                                      |
 | -------------------------------- | ---------------------------------------------------------------- |
-| `check_audiobook_ids(album_ids)` | Batch-check which album IDs are audiobooks (single GraphQL call) |
+| `check_audiobook_ids(album_ids)` | Batch-check which album IDs are audiobooks (aliased queries, chunked at 50 IDs) |
 
 All methods return fully-typed Pydantic models generated from the GraphQL schema.
 
@@ -224,6 +226,14 @@ The Pipe API uses short-lived JWTs obtained from an ARL cookie. The base client
 handles token acquisition and refresh automatically — you only need to supply a
 valid ARL value.
 
+An external `aiohttp.ClientSession` may be shared by clients for different Deezer
+accounts. Each client keeps Deezer's response cookies locally and masks cookies from
+the shared session jar, so authentication state cannot cross between those accounts.
+
+If the ARL is rejected (bad or expired), the client raises
+`GraphQLClientAuthError` — catch it to prompt for a new ARL instead of retrying.
+Transient server errors raise `GraphQLClientHttpError` instead.
+
 ## License
 
 Apache-2.0

{deezer_python_gql-0.17.0 → deezer_python_gql-0.17.2}/deezer_python_gql/__init__.py

@@ -2,6 +2,7 @@
 
 from deezer_python_gql.generated.base_client import (
     GQLResponse,
+    GraphQLClientAuthError,
     GraphQLClientError,
     GraphQLClientGraphQLError,
     GraphQLClientGraphQLMultiError,
@@ -13,6 +14,7 @@ from deezer_python_gql.generated.client import DeezerGQLClient
 __all__ = [
     "DeezerGQLClient",
     "GQLResponse",
+    "GraphQLClientAuthError",
     "GraphQLClientError",
     "GraphQLClientGraphQLError",
     "GraphQLClientGraphQLMultiError",

{deezer_python_gql-0.17.0 → deezer_python_gql-0.17.2}/deezer_python_gql/base_client.py

@@ -2,14 +2,19 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
 import logging
 import time
 from base64 import urlsafe_b64decode
 from dataclasses import dataclass
-from typing import Any, ClassVar, Self, cast
+from typing import TYPE_CHECKING, Any, ClassVar, Self, cast
 
 from aiohttp import ClientSession, ClientTimeout
+from yarl import URL
+
+if TYPE_CHECKING:
+    from aiohttp import ClientResponse
 
 logger = logging.getLogger(__name__)
 
@@ -21,17 +26,31 @@ class GQLResponse:
 
     aiohttp responses cannot escape their context manager, so we capture
     the essential fields inside the ``async with`` block and return this.
+    Carries the originating operation name and variables so error handling
+    and logging stay correct under concurrent requests.
     """
 
     status: int
     data: bytes
     is_success: bool
+    operation_name: str | None = None
+    variables: dict[str, Any] | None = None
 
 
 class GraphQLClientError(Exception):
     """Base exception for GraphQL client errors."""
 
 
+class GraphQLClientAuthError(GraphQLClientError):
+    """
+    Raised when ARL → JWT authentication definitively fails.
+
+    Indicates a bad or expired ARL cookie (or an unexpected auth response),
+    not a transient network/server problem — consumers should treat this as
+    "re-check your ARL token" rather than retry.
+    """
+
+
 class GraphQLClientHttpError(GraphQLClientError):
     """Raised when the HTTP response indicates an error."""
 
@@ -109,6 +128,8 @@ class DeezerBaseClient:
     PIPE_URL = "https://pipe.deezer.com/api"
     AUTH_URL = "https://auth.deezer.com/login/arl"
     JWT_REFRESH_MARGIN_SECONDS = 30
+    REQUEST_TIMEOUT_SECONDS = 30
+    AUDIOBOOK_CHECK_CHUNK_SIZE = 50
 
     def __init__(
         self,
@@ -120,10 +141,12 @@ class DeezerBaseClient:
         self._arl = arl
         self._session = session
         self._owns_session = session is None
+        # An external session may be shared by clients for different Deezer accounts.
+        # Keep Deezer's response cookies per client instead of trusting that shared jar.
+        self._cookies: dict[str, str] = {}
         self._jwt: str | None = None
         self._jwt_expires_at: float = 0
-        self._last_operation_name: str | None = None
-        self._last_variables: dict[str, Any] | None = None
+        self._jwt_lock = asyncio.Lock()
 
     def _get_session(self) -> ClientSession:
         """Return the HTTP session, creating an internal one if needed."""
@@ -151,6 +174,21 @@ class DeezerBaseClient:
         """Exit the async context manager, closing internal resources."""
         await self.close()
 
+    def _request_cookies(self, url: str, *, include_arl: bool = False) -> dict[str, str]:
+        """Return account-local cookies while neutralizing a shared session's jar."""
+        session = self._get_session()
+        blanked = dict.fromkeys(session.cookie_jar.filter_cookies(URL(url)), "")
+        cookies = blanked | self._cookies
+        if include_arl:
+            cookies["arl"] = self._arl
+        return cookies
+
+    def _store_cookies(self, response: ClientResponse) -> None:
+        """Remember response cookies for this client instead of relying on the session jar."""
+        self._cookies.update(
+            {name: morsel.value for name, morsel in response.cookies.items() if name != "arl"}
+        )
+
     async def execute(
         self,
         query: str,
@@ -167,13 +205,14 @@ class DeezerBaseClient:
         :param kwargs: Additional keyword arguments passed to the session request.
         """
         logger.debug("GQL execute: %s (variables=%s)", operation_name or "<unnamed>", variables)
-        self._last_operation_name = operation_name
-        self._last_variables = variables
         jwt = await self._ensure_jwt()
 
         headers: dict[str, str] = kwargs.pop("headers", None) or {}
         headers["Authorization"] = f"Bearer {jwt}"
         headers["Content-Type"] = "application/json"
+        kwargs.setdefault("timeout", ClientTimeout(total=self.REQUEST_TIMEOUT_SECONDS))
+        request_cookies = self._request_cookies(self.url)
+        request_cookies.update(kwargs.pop("cookies", None) or {})
 
         payload: dict[str, Any] = {"query": query}
         if operation_name:
@@ -188,12 +227,21 @@ class DeezerBaseClient:
             }
 
         session = self._get_session()
-        async with session.post(self.url, json=payload, headers=headers, **kwargs) as resp:
+        async with session.post(
+            self.url,
+            json=payload,
+            headers=headers,
+            cookies=request_cookies,
+            **kwargs,
+        ) as resp:
+            self._store_cookies(resp)
             body = await resp.read()
             gql_response = GQLResponse(
                 status=resp.status,
                 data=body,
                 is_success=resp.ok,
+                operation_name=operation_name,
+                variables=variables,
             )
 
         logger.debug(
@@ -227,8 +275,8 @@ class DeezerBaseClient:
         errors = response_json.get("errors")
 
         if errors:
-            op = self._last_operation_name or "<unknown>"
-            variables = self._last_variables
+            op = response.operation_name or "<unknown>"
+            variables = response.variables
             if data:
                 # Partial success — some items failed (e.g. deleted albums in favorites).
                 # Log the errors but return the valid data.
@@ -280,65 +328,106 @@ class DeezerBaseClient:
             for item in obj:
                 cls._inject_missing_typenames(item)
 
+    def _jwt_is_valid(self) -> bool:
+        """Return True if the current JWT exists and is not about to expire."""
+        return self._jwt is not None and time.time() < (
+            self._jwt_expires_at - self.JWT_REFRESH_MARGIN_SECONDS
+        )
+
     async def _ensure_jwt(self) -> str:
         """Acquire or refresh the JWT token from ARL cookie."""
-        now = time.time()
-        if self._jwt and now < (self._jwt_expires_at - self.JWT_REFRESH_MARGIN_SECONDS):
+        if self._jwt is not None and self._jwt_is_valid():
             return self._jwt
 
-        logger.debug("JWT expired or missing, refreshing from ARL")
-        params = {"jo": "p", "rto": "c", "i": "c"}
-
-        session = self._get_session()
-        async with session.post(
-            self.AUTH_URL,
-            params=params,
-            cookies={"arl": self._arl},
-            timeout=ClientTimeout(total=10),
-        ) as resp:
-            resp.raise_for_status()
-            # Response body is text/plain containing JSON
-            text = await resp.text()
-
-        data = json.loads(text)
-        self._jwt = data["jwt"]
-
-        # Decode expiration from JWT payload (second segment, base64url-encoded)
-        payload_segment = self._jwt.split(".")[1]
-        # Add padding for base64 decoding
-        padded = payload_segment + "=" * (-len(payload_segment) % 4)
-        payload = json.loads(urlsafe_b64decode(padded))
-        self._jwt_expires_at = float(payload["exp"])
-        logger.debug("JWT acquired, expires at %s", self._jwt_expires_at)
+        # Serialize refreshes so concurrent expired-JWT requests trigger
+        # exactly one auth call.
+        async with self._jwt_lock:
+            if self._jwt is not None and self._jwt_is_valid():
+                return self._jwt
+
+            logger.debug("JWT expired or missing, refreshing from ARL")
+            params = {"jo": "p", "rto": "c", "i": "c"}
+
+            session = self._get_session()
+            async with session.post(
+                self.AUTH_URL,
+                params=params,
+                cookies=self._request_cookies(self.AUTH_URL, include_arl=True),
+                timeout=ClientTimeout(total=10),
+            ) as resp:
+                self._store_cookies(resp)
+                status = resp.status
+                is_success = resp.ok
+                # Response body is text/plain containing JSON
+                text = await resp.text()
+
+            if not is_success:
+                if 400 <= status < 500:
+                    msg = f"ARL authentication rejected by auth.deezer.com (HTTP {status})"
+                    raise GraphQLClientAuthError(msg)
+                raise GraphQLClientHttpError(
+                    status_code=status,
+                    response=GQLResponse(status=status, data=text.encode(), is_success=False),
+                )
 
-        return self._jwt
+            try:
+                data = json.loads(text)
+                jwt: str = data["jwt"]
+                # Decode expiration from JWT payload (second segment, base64url-encoded)
+                payload_segment = jwt.split(".")[1]
+                # Add padding for base64 decoding
+                padded = payload_segment + "=" * (-len(payload_segment) % 4)
+                payload = json.loads(urlsafe_b64decode(padded))
+                expires_at = float(payload["exp"])
+            except (ValueError, KeyError, IndexError, TypeError, AttributeError) as exc:
+                msg = "Unexpected response from auth.deezer.com (invalid or missing JWT)"
+                raise GraphQLClientAuthError(msg) from exc
+
+            self._jwt = jwt
+            self._jwt_expires_at = expires_at
+            logger.debug("JWT acquired, expires at %s", self._jwt_expires_at)
+
+            return jwt
 
     async def check_audiobook_ids(self, album_ids: list[str]) -> set[str]:
         """
         Check which album IDs are also valid audiobooks on Deezer.
 
+        Queries are chunked to stay below the API's query complexity limit.
+
         :param album_ids: List of Deezer album/audiobook IDs to check.
         """
-        if not album_ids:
-            return set()
+        audiobook_ids: set[str] = set()
+        for start in range(0, len(album_ids), self.AUDIOBOOK_CHECK_CHUNK_SIZE):
+            chunk = album_ids[start : start + self.AUDIOBOOK_CHECK_CHUNK_SIZE]
+            audiobook_ids |= await self._check_audiobook_ids_chunk(chunk)
+        return audiobook_ids
 
+    async def _check_audiobook_ids_chunk(self, album_ids: list[str]) -> set[str]:
+        """Check a single chunk of album IDs via one aliased query."""
         # Query displayTitle alongside id — querying only { id } echoes back the
         # input without validating that the ID is actually an audiobook.
+        # json.dumps escapes the IDs so they cannot break out of the string
+        # literal (this is a public library API — IDs may come from anywhere).
         parts = [
-            f'a{i}: audiobook(audiobookId: "{aid}") {{ id displayTitle }}'
+            f"a{i}: audiobook(audiobookId: {json.dumps(aid)}) {{ id displayTitle }}"
             for i, aid in enumerate(album_ids)
         ]
         query = "query CheckAudiobookIds { " + " ".join(parts) + " }"
 
         resp = await self.execute(query, operation_name="CheckAudiobookIds")
-        self._last_variables = {"album_ids": album_ids}
         try:
             data = self.get_data(resp)
-        except GraphQLClientGraphQLMultiError:
-            # Expected when none of the IDs are audiobooks (every alias errors).
-            # Also handles transient API errors — return empty rather than crash.
-            logger.debug("CheckAudiobookIds: all %d IDs returned errors", len(album_ids))
-            return set()
+        except GraphQLClientGraphQLMultiError as err:
+            # Only swallow errors scoped to our aliased audiobook fields —
+            # that is the legitimate "these IDs are not audiobooks" case.
+            # Anything else (complexity limit, transient API failure) must
+            # surface, otherwise audiobooks silently degrade to albums.
+            aliases = {f"a{i}" for i in range(len(album_ids))}
+            if all(e.path and e.path[0] in aliases for e in err.errors):
+                logger.debug("CheckAudiobookIds: all %d IDs returned errors", len(album_ids))
+                return set()
+            raise
 
         audiobook_ids: set[str] = set()
         for i, aid in enumerate(album_ids):