deezer-python-gql 0.7.0__tar.gz → 0.8.1__tar.gz

{deezer_python_gql-0.7.0/deezer_python_gql.egg-info → deezer_python_gql-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deezer-python-gql
-Version: 0.7.0
+Version: 0.8.1
 Summary: Async typed Python client for Deezer's Pipe GraphQL API.
 Author-email: Julian Daberkow <jdaberkow@users.noreply.github.com>
 License: Apache-2.0

deezer_python_gql-0.8.1/deezer_python_gql/base_client.py

@@ -0,0 +1,317 @@
+"""Custom async base client with Deezer ARL → JWT authentication."""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from base64 import urlsafe_b64decode
+from typing import Any, ClassVar, Self, cast
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class GraphQLClientError(Exception):
+    """Base exception for GraphQL client errors."""
+
+
+class GraphQLClientHttpError(GraphQLClientError):
+    """Raised when the HTTP response indicates an error."""
+
+    def __init__(self, status_code: int, response: httpx.Response) -> None:
+        self.status_code = status_code
+        self.response = response
+        super().__init__(f"HTTP status code: {status_code}")
+
+
+class GraphQLClientInvalidResponseError(GraphQLClientError):
+    """Raised when the response cannot be parsed as valid GraphQL."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        self.response = response
+        super().__init__("Invalid response format")
+
+
+class GraphQLClientGraphQLError(GraphQLClientError):
+    """A single GraphQL error from the response."""
+
+    def __init__(self, message: str, locations: Any = None, path: Any = None) -> None:
+        self.message = message
+        self.locations = locations
+        self.path = path
+        super().__init__(message)
+
+
+class GraphQLClientGraphQLMultiError(GraphQLClientError):
+    """Raised when the GraphQL response contains errors."""
+
+    def __init__(self, errors: list[GraphQLClientGraphQLError], data: Any = None) -> None:
+        self.errors = errors
+        self.data = data
+        super().__init__(str(errors))
+
+    @classmethod
+    def from_errors_dicts(
+        cls,
+        errors_dicts: list[dict[str, Any]],
+        data: Any = None,
+    ) -> GraphQLClientGraphQLMultiError:
+        """Create from raw error dicts in a GraphQL response."""
+        errors = [
+            GraphQLClientGraphQLError(
+                message=e.get("message", "Unknown error"),
+                locations=e.get("locations"),
+                path=e.get("path"),
+            )
+            for e in errors_dicts
+        ]
+        return cls(errors=errors, data=data)
+
+
+class DeezerBaseClient:
+    """Async HTTP client for Deezer's Pipe GraphQL API with ARL-based auth.
+
+    Handles the ARL cookie → JWT token exchange and automatic refresh.
+    This class is used as the base client for ariadne-codegen's generated client.
+
+    Manages its own httpx connection pool by default. Pass an external
+    ``http_client`` only if you need to share a pool across multiple clients.
+
+    :param arl: Deezer ARL cookie value for authentication.
+    :param url: GraphQL endpoint URL (defaults to Pipe API).
+    :param http_client: Optional pre-configured httpx.AsyncClient.
+        If provided, the caller is responsible for closing it.
+    """
+
+    PIPE_URL = "https://pipe.deezer.com/api"
+    AUTH_URL = "https://auth.deezer.com/login/arl"
+    JWT_REFRESH_MARGIN_SECONDS = 30
+
+    def __init__(
+        self,
+        arl: str,
+        url: str = PIPE_URL,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.url = url
+        self._arl = arl
+        self._http_client = http_client
+        self._owns_http_client = http_client is None
+        self._jwt: str | None = None
+        self._jwt_expires_at: float = 0
+
+    def _get_http_client(self) -> httpx.AsyncClient:
+        """Return the HTTP client, creating an internal one if needed."""
+        if self._http_client is None:
+            self._http_client = httpx.AsyncClient()
+            self._owns_http_client = True
+        return self._http_client
+
+    async def close(self) -> None:
+        """Close the internal HTTP client if we own it.
+
+        Safe to call multiple times. Does nothing if an external
+        ``http_client`` was provided at construction time.
+        """
+        if self._owns_http_client and self._http_client is not None:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager."""
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Exit the async context manager, closing internal resources."""
+        await self.close()
+
+    async def execute(
+        self,
+        query: str,
+        operation_name: str | None = None,
+        variables: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Execute a GraphQL query against the Pipe API.
+
+        Automatically handles JWT acquisition and refresh from the ARL cookie.
+
+        :param query: The GraphQL query string.
+        :param operation_name: Optional operation name for multi-operation documents.
+        :param variables: Optional query variables.
+        :param kwargs: Additional keyword arguments passed to httpx.
+        """
+        logger.debug("GQL execute: %s (variables=%s)", operation_name or "<unnamed>", 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"
+
+        payload: dict[str, Any] = {"query": query}
+        if operation_name:
+            payload["operationName"] = operation_name
+        if variables:
+            # Filter out UNSET sentinel values that are not JSON-serializable.
+            # Inline import avoids depending on generated code at module level.
+            from deezer_python_gql.generated.base_model import UnsetType  # noqa: PLC0415
+
+            payload["variables"] = {
+                k: v for k, v in variables.items() if not isinstance(v, UnsetType)
+            }
+
+        client = self._get_http_client()
+        resp = await client.post(
+            self.url,
+            json=payload,
+            headers=headers,
+            **kwargs,
+        )
+        logger.debug(
+            "GQL response: %s status=%s length=%s",
+            operation_name or "<unnamed>",
+            resp.status_code,
+            len(resp.content),
+        )
+        return resp
+
+    def get_data(self, response: httpx.Response) -> dict[str, Any]:
+        """Parse a GraphQL response and return the data dict.
+
+        Handles the Pipe API's text/plain content type and standard
+        GraphQL error responses.
+
+        :param response: The HTTP response from execute().
+        """
+        if not response.is_success:
+            raise GraphQLClientHttpError(status_code=response.status_code, response=response)
+
+        try:
+            response_json = response.json()
+        except ValueError as exc:
+            raise GraphQLClientInvalidResponseError(response=response) from exc
+
+        if (not isinstance(response_json, dict)) or (
+            "data" not in response_json and "errors" not in response_json
+        ):
+            raise GraphQLClientInvalidResponseError(response=response)
+
+        data = response_json.get("data")
+        errors = response_json.get("errors")
+
+        if errors:
+            if data:
+                # Partial success — some items failed (e.g. deleted albums in favorites).
+                # Log the errors but return the valid data.
+                logger.warning(
+                    "GraphQL response contained %d error(s): %s",
+                    len(errors),
+                    [e.get("message", "Unknown error") for e in errors],
+                )
+            else:
+                raise GraphQLClientGraphQLMultiError.from_errors_dicts(
+                    errors_dicts=errors, data=data
+                )
+
+        # The Deezer API omits __typename for single-member union types
+        # (e.g. Contributor = Artist). Pydantic discriminated unions require it,
+        # so we inject the missing field before model validation.
+        self._inject_missing_typenames(data)
+
+        return cast("dict[str, Any]", data)
+
+    # Map of parent key → child key → __typename value for single-member unions
+    # where the Deezer API omits the discriminator.
+    _TYPENAME_PATCHES: ClassVar[dict[str, dict[str, str]]] = {
+        "contributors": {"node": "Artist"},
+    }
+
+    @classmethod
+    def _inject_missing_typenames(cls, obj: Any) -> None:
+        """Recursively inject __typename into nodes where the API omits it."""
+        if isinstance(obj, dict):
+            for parent_key, patches in cls._TYPENAME_PATCHES.items():
+                if parent_key in obj:
+                    container = obj[parent_key]
+                    if isinstance(container, dict) and "edges" in container:
+                        for edge in container["edges"]:
+                            if isinstance(edge, dict):
+                                for child_key, typename in patches.items():
+                                    node = edge.get(child_key)
+                                    if isinstance(node, dict) and "__typename" not in node:
+                                        node["__typename"] = typename
+            for value in obj.values():
+                cls._inject_missing_typenames(value)
+        elif isinstance(obj, list):
+            for item in obj:
+                cls._inject_missing_typenames(item)
+
+    async def _ensure_jwt(self) -> str:
+        """Acquire or refresh the JWT token from ARL cookie.
+
+        The Pipe API uses short-lived JWTs (~6 min TTL) obtained by
+        POSTing the ARL cookie to auth.deezer.com. The response is
+        Content-Type: text/plain containing JSON.
+        """
+        now = time.time()
+        if self._jwt and now < (self._jwt_expires_at - self.JWT_REFRESH_MARGIN_SECONDS):
+            return self._jwt
+
+        logger.debug("JWT expired or missing, refreshing from ARL")
+        params = {"jo": "p", "rto": "c", "i": "c"}
+
+        client = self._get_http_client()
+        resp = await client.post(
+            self.AUTH_URL,
+            params=params,
+            cookies={"arl": self._arl},
+        )
+        resp.raise_for_status()
+
+        # Response body is text/plain containing JSON
+        data = json.loads(resp.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)
+
+        return self._jwt
+
+    async def check_audiobook_ids(self, album_ids: list[str]) -> set[str]:
+        """Check which album IDs are also valid audiobooks on Deezer.
+
+        Uses GraphQL aliases to batch-check many IDs in a single request.
+        Returns the subset of IDs that are audiobooks (i.e., the audiobook
+        query returns non-null for them).
+
+        :param album_ids: List of Deezer album/audiobook IDs to check.
+        """
+        if not album_ids:
+            return set()
+
+        # Query displayTitle alongside id — querying only { id } echoes back the
+        # input without validating that the ID is actually an audiobook.
+        parts = [
+            f'a{i}: audiobook(audiobookId: "{aid}") {{ id displayTitle }}'
+            for i, aid in enumerate(album_ids)
+        ]
+        query = "{ " + " ".join(parts) + " }"
+
+        resp = await self.execute(query)
+        data = self.get_data(resp)
+
+        audiobook_ids: set[str] = set()
+        for i, aid in enumerate(album_ids):
+            node = data.get(f"a{i}")
+            # The API echoes back {id} for any valid album, so we must check
+            # a real audiobook field like displayTitle to distinguish.
+            if node is not None and node.get("displayTitle") is not None:
+                audiobook_ids.add(aid)
+        return audiobook_ids