spotifyify 0.2.0__tar.gz → 0.3.0__tar.gz

{spotifyify-0.2.0/spotifyify.egg-info → spotifyify-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spotifyify
-Version: 0.2.0
+Version: 0.3.0
 Summary: Async wrapper for spotipy with a focus on integration with MCP agents.
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
@@ -10,7 +10,7 @@ Requires-Dist: pydantic-settings>=2.12.0
 
 # spotifyify
 
-An async-first Spotify client with a namespaced API and fully typed response models generated from the [official Spotify OpenAPI specification](https://developer.spotify.com/reference/web-api/open-api-schema.yaml).
+An async-first Spotify client with a namespaced API and fully typed response models maintained in the codebase and aligned with the [official Spotify OpenAPI specification](https://developer.spotify.com/reference/web-api/open-api-schema.yaml).
 
 ## Requirements
 
@@ -130,11 +130,12 @@ Spotifyify
 | `find(query, *, limit, offset)`                                                  | Search for playlists                         |
 | `get(playlist_id, *, market)`                                                    | Get a single playlist                        |
 | `list(*, user_id, limit, offset)`                                                | Current user's (or another user's) playlists |
+| `tracks(playlist_id, *, market, fields, limit, offset, additional_types)`        | Get playlist tracks                          |
 | `create(name, *, public, collaborative, description, user_id)`                   | Create a playlist                            |
 | `update(playlist_id, *, name, public, collaborative, description)`               | Update playlist details                      |
-| `add(playlist_id, uris, *, position)`                                            | Add tracks to a playlist                     |
-| `remove(playlist_id, uris)`                                                      | Remove tracks from a playlist                |
-| `reorder(playlist_id, *, range_start, insert_before, range_length, snapshot_id)` | Reorder tracks                               |
+| `add(playlist_id, uris, *, position)`                                            | Add items to a playlist                      |
+| `remove(playlist_id, uris)`                                                      | Remove items from a playlist                 |
+| `reorder(playlist_id, *, range_start, insert_before, range_length, snapshot_id)` | Reorder items                                |
 | `cover_image(playlist_id)`                                                       | Get playlist cover images                    |
 
 ### Player — `sp.player`
@@ -209,6 +210,14 @@ Spotifyify
 | `unfollow(type, ids)`              | Unfollow artists or users              |
 | `check_following(type, ids)`       | Check if following artists or users    |
 
+## Retries
+
+Spotify API requests automatically retry rate limits (`429`) and temporary server
+errors (`500`, `502`, `503`, `504`). Rate limits honor Spotify's `Retry-After`
+header. Server errors are only retried for idempotent HTTP methods to avoid
+duplicating mutations. Configure the defaults with `max_retries` and
+`retry_backoff_seconds` when constructing `Spotifyify`.
+
 ## Scopes
 
 Use `SpotifyScope` to declare the OAuth scopes your app requires:

spotifyify-0.2.0/PKG-INFO → spotifyify-0.3.0/README.md

@@ -1,16 +1,6 @@
-Metadata-Version: 2.4
-Name: spotifyify
-Version: 0.2.0
-Summary: Async wrapper for spotipy with a focus on integration with MCP agents.
-Requires-Python: >=3.13
-Description-Content-Type: text/markdown
-Requires-Dist: httpx>=0.28.0
-Requires-Dist: pydantic>=2.12.0
-Requires-Dist: pydantic-settings>=2.12.0
-
 # spotifyify
 
-An async-first Spotify client with a namespaced API and fully typed response models generated from the [official Spotify OpenAPI specification](https://developer.spotify.com/reference/web-api/open-api-schema.yaml).
+An async-first Spotify client with a namespaced API and fully typed response models maintained in the codebase and aligned with the [official Spotify OpenAPI specification](https://developer.spotify.com/reference/web-api/open-api-schema.yaml).
 
 ## Requirements
 
@@ -130,11 +120,12 @@ Spotifyify
 | `find(query, *, limit, offset)`                                                  | Search for playlists                         |
 | `get(playlist_id, *, market)`                                                    | Get a single playlist                        |
 | `list(*, user_id, limit, offset)`                                                | Current user's (or another user's) playlists |
+| `tracks(playlist_id, *, market, fields, limit, offset, additional_types)`        | Get playlist tracks                          |
 | `create(name, *, public, collaborative, description, user_id)`                   | Create a playlist                            |
 | `update(playlist_id, *, name, public, collaborative, description)`               | Update playlist details                      |
-| `add(playlist_id, uris, *, position)`                                            | Add tracks to a playlist                     |
-| `remove(playlist_id, uris)`                                                      | Remove tracks from a playlist                |
-| `reorder(playlist_id, *, range_start, insert_before, range_length, snapshot_id)` | Reorder tracks                               |
+| `add(playlist_id, uris, *, position)`                                            | Add items to a playlist                      |
+| `remove(playlist_id, uris)`                                                      | Remove items from a playlist                 |
+| `reorder(playlist_id, *, range_start, insert_before, range_length, snapshot_id)` | Reorder items                                |
 | `cover_image(playlist_id)`                                                       | Get playlist cover images                    |
 
 ### Player — `sp.player`
@@ -209,6 +200,14 @@ Spotifyify
 | `unfollow(type, ids)`              | Unfollow artists or users              |
 | `check_following(type, ids)`       | Check if following artists or users    |
 
+## Retries
+
+Spotify API requests automatically retry rate limits (`429`) and temporary server
+errors (`500`, `502`, `503`, `504`). Rate limits honor Spotify's `Retry-After`
+header. Server errors are only retried for idempotent HTTP methods to avoid
+duplicating mutations. Configure the defaults with `max_retries` and
+`retry_backoff_seconds` when constructing `Spotifyify`.
+
 ## Scopes
 
 Use `SpotifyScope` to declare the OAuth scopes your app requires:

{spotifyify-0.2.0 → spotifyify-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spotifyify"
-version = "0.2.0"
+version = "0.3.0"
 description = "Async wrapper for spotipy with a focus on integration with MCP agents."
 readme = "README.md"
 requires-python = ">=3.13"

spotifyify-0.3.0/spotifyify/auth.py

@@ -0,0 +1,9 @@
+from typing import Protocol
+
+
+class AccessTokenProvider(Protocol):
+    async def get_access_token(
+        self,
+        require_user: bool,
+        scope: str | list[str] | tuple[str, ...] | None = None,
+    ) -> str: ...

spotifyify-0.3.0/spotifyify/client.py

@@ -0,0 +1,189 @@
+from typing import Any, Self
+
+from collections.abc import Iterable
+
+from pydantic import BaseModel
+
+from spotifyify.auth import AccessTokenProvider
+from spotifyify.http import (
+    HttpMethod,
+    HttpTransport,
+    JsonPayload,
+    QueryParams,
+    RetryPolicy,
+    dump_params,
+    dump_payload,
+    parse_response,
+    validate_response_model,
+)
+
+
+class SpotifyClient:
+    def __init__(
+        self,
+        token_provider: AccessTokenProvider,
+        scopes: Iterable[str] | None,
+        *,
+        base_url: str,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        retry_backoff_seconds: float = 1.0,
+    ) -> None:
+        self._token_provider = token_provider
+        self._scopes = list(scopes or [])
+        self._transport = HttpTransport(
+            base_url=base_url,
+            timeout=timeout,
+            retry_policy=RetryPolicy(
+                max_retries=max_retries,
+                backoff_seconds=retry_backoff_seconds,
+            ),
+        )
+
+    async def open(self) -> None:
+        await self._transport.open()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._transport.close()
+
+    async def _request_json(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        params: QueryParams | BaseModel | dict[str, Any] | None = None,
+        payload: JsonPayload = None,
+        content: str | bytes | None = None,
+        require_user: bool = True,
+        headers: dict[str, str] | None = None,
+        response_model: type[BaseModel] | None = None,
+    ) -> Any:
+        token = await self._token_provider.get_access_token(
+            require_user=require_user,
+            scope=self._scopes,
+        )
+        request_headers = {"Authorization": f"Bearer {token}"}
+        if headers:
+            request_headers.update(headers)
+
+        response = await self._transport.request(
+            method,
+            path,
+            headers=request_headers,
+            params=dump_params(params),
+            json=None if content is not None else dump_payload(payload),
+            content=content,
+        )
+        return validate_response_model(parse_response(response), response_model)
+
+    async def get(
+        self,
+        path: str,
+        *,
+        params: QueryParams | BaseModel | dict[str, Any] | None = None,
+        require_user: bool = True,
+        headers: dict[str, str] | None = None,
+        response_model: type[BaseModel] | None = None,
+    ) -> Any:
+        return await self._request_json(
+            HttpMethod.GET,
+            path,
+            params=params,
+            require_user=require_user,
+            headers=headers,
+            response_model=response_model,
+        )
+
+    async def post(
+        self,
+        path: str,
+        *,
+        params: QueryParams | BaseModel | dict[str, Any] | None = None,
+        payload: JsonPayload = None,
+        content: str | bytes | None = None,
+        require_user: bool = True,
+        headers: dict[str, str] | None = None,
+        response_model: type[BaseModel] | None = None,
+    ) -> Any:
+        return await self._request_json(
+            HttpMethod.POST,
+            path,
+            params=params,
+            payload=payload,
+            content=content,
+            require_user=require_user,
+            headers=headers,
+            response_model=response_model,
+        )
+
+    async def put(
+        self,
+        path: str,
+        *,
+        params: QueryParams | BaseModel | dict[str, Any] | None = None,
+        payload: JsonPayload = None,
+        content: str | bytes | None = None,
+        require_user: bool = True,
+        headers: dict[str, str] | None = None,
+        response_model: type[BaseModel] | None = None,
+    ) -> Any:
+        return await self._request_json(
+            HttpMethod.PUT,
+            path,
+            params=params,
+            payload=payload,
+            content=content,
+            require_user=require_user,
+            headers=headers,
+            response_model=response_model,
+        )
+
+    async def patch(
+        self,
+        path: str,
+        *,
+        params: QueryParams | BaseModel | dict[str, Any] | None = None,
+        payload: JsonPayload = None,
+        content: str | bytes | None = None,
+        require_user: bool = True,
+        headers: dict[str, str] | None = None,
+        response_model: type[BaseModel] | None = None,
+    ) -> Any:
+        return await self._request_json(
+            HttpMethod.PATCH,
+            path,
+            params=params,
+            payload=payload,
+            content=content,
+            require_user=require_user,
+            headers=headers,
+            response_model=response_model,
+        )
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        params: QueryParams | BaseModel | dict[str, Any] | None = None,
+        payload: JsonPayload = None,
+        content: str | bytes | None = None,
+        require_user: bool = True,
+        headers: dict[str, str] | None = None,
+        response_model: type[BaseModel] | None = None,
+    ) -> Any:
+        return await self._request_json(
+            HttpMethod.DELETE,
+            path,
+            params=params,
+            payload=payload,
+            content=content,
+            require_user=require_user,
+            headers=headers,
+            response_model=response_model,
+        )

spotifyify-0.3.0/spotifyify/http/__init__.py

@@ -0,0 +1,21 @@
+from spotifyify.http.response import parse_response, validate_response_model
+from spotifyify.http.retry_policy import HttpMethod, RetryPolicy
+from spotifyify.http.serialization import (
+    JsonPayload,
+    QueryParams,
+    dump_params,
+    dump_payload,
+)
+from spotifyify.http.transport import HttpTransport
+
+__all__ = [
+    "HttpMethod",
+    "HttpTransport",
+    "JsonPayload",
+    "QueryParams",
+    "RetryPolicy",
+    "dump_params",
+    "dump_payload",
+    "parse_response",
+    "validate_response_model",
+]

spotifyify-0.3.0/spotifyify/http/response.py

@@ -0,0 +1,47 @@
+from typing import Any
+
+import httpx
+from pydantic import BaseModel
+
+from spotifyify.exceptions import SpotifyAPIError
+
+JsonResponse = dict[str, Any] | list[Any] | None
+
+
+def parse_response(response: httpx.Response) -> JsonResponse:
+    if response.status_code == 204:
+        return None
+
+    if response.status_code >= 400:
+        try:
+            data = response.json()
+            error = data.get("error", data) if isinstance(data, dict) else data
+            message = (
+                error.get("message", response.text)
+                if isinstance(error, dict)
+                else str(error)
+            )
+        except ValueError:
+            data = None
+            message = response.text
+        raise SpotifyAPIError(
+            response.status_code,
+            message,
+            data if isinstance(data, dict) else None,
+        )
+
+    if not response.content:
+        return None
+
+    return response.json()
+
+
+def validate_response_model(
+    parsed: JsonResponse,
+    response_model: type[BaseModel] | None,
+) -> Any:
+    if response_model is None or parsed is None:
+        return parsed
+    if isinstance(parsed, list):
+        raise SpotifyAPIError(500, "Expected object response but got list")
+    return response_model.model_validate(parsed)

spotifyify-0.3.0/spotifyify/http/retry_policy.py

@@ -0,0 +1,54 @@
+from enum import StrEnum
+
+_RETRYABLE_SERVER_ERROR_STATUS_CODES = frozenset({500, 502, 503, 504})
+
+
+class HttpMethod(StrEnum):
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    PATCH = "PATCH"
+    DELETE = "DELETE"
+    HEAD = "HEAD"
+    OPTIONS = "OPTIONS"
+
+
+_IDEMPOTENT_METHODS = frozenset(
+    {
+        HttpMethod.GET,
+        HttpMethod.PUT,
+        HttpMethod.DELETE,
+        HttpMethod.HEAD,
+        HttpMethod.OPTIONS,
+    }
+)
+
+
+class RetryPolicy:
+    def __init__(
+        self,
+        max_retries: int = 3,
+        backoff_seconds: float = 1.0,
+    ) -> None:
+        if max_retries < 0:
+            raise ValueError("max_retries must be greater than or equal to 0")
+        if backoff_seconds < 0:
+            raise ValueError("backoff_seconds must be greater than or equal to 0")
+        self.max_retries = max_retries
+        self.backoff_seconds = backoff_seconds
+
+    def should_retry(self, method: HttpMethod, status_code: int) -> bool:
+        if status_code == 429:
+            return True
+        return (
+            method in _IDEMPOTENT_METHODS
+            and status_code in _RETRYABLE_SERVER_ERROR_STATUS_CODES
+        )
+
+    def retry_delay(self, attempt: int, *, retry_after: str | None = None) -> float:
+        if retry_after is not None:
+            try:
+                return max(0.0, float(retry_after))
+            except ValueError:
+                pass
+        return self.backoff_seconds * (2**attempt)

spotifyify-0.3.0/spotifyify/http/serialization.py

@@ -0,0 +1,26 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+type JsonPayload = BaseModel | dict[str, Any] | list[Any] | str | None
+type SerializedJsonPayload = dict[str, Any] | list[Any] | str | None
+
+
+class QueryParams(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+def dump_params(
+    params: QueryParams | BaseModel | dict[str, Any] | None,
+) -> dict[str, Any] | None:
+    if params is None:
+        return None
+    if isinstance(params, BaseModel):
+        return params.model_dump(mode="json", exclude_none=True)
+    return QueryParams.model_validate(params).model_dump(mode="json", exclude_none=True)
+
+
+def dump_payload(payload: JsonPayload) -> SerializedJsonPayload:
+    if isinstance(payload, BaseModel):
+        return payload.model_dump(mode="json", exclude_none=True)
+    return payload

spotifyify-0.3.0/spotifyify/http/transport.py

@@ -0,0 +1,70 @@
+from typing import Any
+
+import asyncio
+import httpx
+
+from spotifyify.http.retry_policy import HttpMethod, RetryPolicy
+from spotifyify.http.serialization import SerializedJsonPayload
+
+
+class HttpTransport:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        timeout: float,
+        retry_policy: RetryPolicy,
+    ) -> None:
+        self._base_url = base_url
+        self._timeout = timeout
+        self._retry_policy = retry_policy
+        self._client: httpx.AsyncClient | None = None
+
+    async def open(self) -> None:
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self._base_url,
+                timeout=self._timeout,
+            )
+
+    async def close(self) -> None:
+        if self._client is None:
+            return
+        await self._client.aclose()
+        self._client = None
+
+    async def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        headers: dict[str, str],
+        params: dict[str, Any] | None,
+        json: SerializedJsonPayload,
+        content: str | bytes | None,
+    ) -> httpx.Response:
+        await self.open()
+        if self._client is None:
+            raise RuntimeError("HTTP client was not initialized")
+
+        for attempt in range(self._retry_policy.max_retries + 1):
+            response = await self._client.request(
+                method.value,
+                path,
+                headers=headers,
+                params=params,
+                json=json,
+                content=content,
+            )
+            if attempt == self._retry_policy.max_retries or not (
+                self._retry_policy.should_retry(method, response.status_code)
+            ):
+                return response
+            await asyncio.sleep(
+                self._retry_policy.retry_delay(
+                    attempt,
+                    retry_after=response.headers.get("Retry-After"),
+                )
+            )
+
+        raise RuntimeError("unreachable")

{spotifyify-0.2.0 → spotifyify-0.3.0}/spotifyify/namespaces/playlists.py

@@ -2,8 +2,8 @@ from typing import TYPE_CHECKING, Any
 
 from collections.abc import Iterable
 
-from spotifyify.schemas import Image, PagingPlaylist, Playlist
-from spotifyify.utils import coalesce_items
+from spotifyify.schemas import Image, PagingPlaylist, PagingPlaylistTrack, Playlist
+from spotifyify.utils import coalesce_csv, coalesce_items
 
 if TYPE_CHECKING:
     from spotifyify.spotifyify import Spotifyify
@@ -58,6 +58,31 @@ class Playlists:
         data = await self._http.get(path, params=params) or {}
         return PagingPlaylist.model_validate(data)
 
+    async def tracks(
+        self,
+        playlist_id: str,
+        *,
+        market: str | None = None,
+        fields: str | None = None,
+        limit: int = 20,
+        offset: int = 0,
+        additional_types: Iterable[str] | None = None,
+    ) -> PagingPlaylistTrack:
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if market:
+            params["market"] = market
+        if fields:
+            params["fields"] = fields
+        if additional_types is not None:
+            params["additional_types"] = coalesce_csv(additional_types)
+        # The legacy read route still exposes public playlists to app-only tokens.
+        data = await self._http.get(
+            f"/playlists/{playlist_id}/tracks",
+            params=params,
+            require_user=False,
+        )
+        return PagingPlaylistTrack.model_validate(data or {})
+
     async def create(
         self,
         name: str,
@@ -116,15 +141,15 @@ class Playlists:
         if position is not None:
             payload["position"] = position
         data = (
-            await self._http.post(f"/playlists/{playlist_id}/tracks", payload=payload)
+            await self._http.post(f"/playlists/{playlist_id}/items", payload=payload)
             or {}
         )
         return data.get("snapshot_id") if isinstance(data, dict) else None
 
     async def remove(self, playlist_id: str, uris: Iterable[str]) -> str | None:
-        payload = {"tracks": [{"uri": uri} for uri in coalesce_items(uris)]}
+        payload = {"items": [{"uri": uri} for uri in coalesce_items(uris)]}
         data = (
-            await self._http.delete(f"/playlists/{playlist_id}/tracks", payload=payload)
+            await self._http.delete(f"/playlists/{playlist_id}/items", payload=payload)
             or {}
         )
         return data.get("snapshot_id") if isinstance(data, dict) else None
@@ -146,7 +171,7 @@ class Playlists:
         if snapshot_id:
             payload["snapshot_id"] = snapshot_id
         data = (
-            await self._http.put(f"/playlists/{playlist_id}/tracks", payload=payload)
+            await self._http.put(f"/playlists/{playlist_id}/items", payload=payload)
             or {}
         )
         return data.get("snapshot_id") if isinstance(data, dict) else None

{spotifyify-0.2.0 → spotifyify-0.3.0}/spotifyify/oauth2/oauth2.py

@@ -14,8 +14,8 @@ import httpx
 
 from spotifyify.credentials import SpotifyCredentials
 from spotifyify.exceptions import SpotifyAuthError
-from spotifyify.client import parse_response
 from spotifyify.oauth2.views import TokenFormPayload
+from spotifyify.http import parse_response
 
 
 class SpotifyifyOAuth:

{spotifyify-0.2.0 → spotifyify-0.3.0}/spotifyify/spotifyify.py

@@ -31,6 +31,8 @@ class Spotifyify:
         scopes: Iterable[SpotifyScope] | None = None,
         cache_handler: CacheHandler | None = None,
         timeout: float = 10.0,
+        max_retries: int = 3,
+        retry_backoff_seconds: float = 1.0,
     ) -> None:
         self._credentials = credentials or SpotifyCredentials()
         self._scopes = [scope for scope in (scopes or ())]
@@ -44,6 +46,8 @@ class Spotifyify:
             scopes=self._scopes,
             base_url=self._SPOTIFY_API_BASE_URL,
             timeout=timeout,
+            max_retries=max_retries,
+            retry_backoff_seconds=retry_backoff_seconds,
         )
 
         self._tracks: Tracks | None = None

spotifyify-0.2.0/README.md → spotifyify-0.3.0/spotifyify.egg-info/PKG-INFO

@@ -1,6 +1,16 @@
+Metadata-Version: 2.4
+Name: spotifyify
+Version: 0.3.0
+Summary: Async wrapper for spotipy with a focus on integration with MCP agents.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: pydantic-settings>=2.12.0
+
 # spotifyify
 
-An async-first Spotify client with a namespaced API and fully typed response models generated from the [official Spotify OpenAPI specification](https://developer.spotify.com/reference/web-api/open-api-schema.yaml).
+An async-first Spotify client with a namespaced API and fully typed response models maintained in the codebase and aligned with the [official Spotify OpenAPI specification](https://developer.spotify.com/reference/web-api/open-api-schema.yaml).
 
 ## Requirements
 
@@ -120,11 +130,12 @@ Spotifyify
 | `find(query, *, limit, offset)`                                                  | Search for playlists                         |
 | `get(playlist_id, *, market)`                                                    | Get a single playlist                        |
 | `list(*, user_id, limit, offset)`                                                | Current user's (or another user's) playlists |
+| `tracks(playlist_id, *, market, fields, limit, offset, additional_types)`        | Get playlist tracks                          |
 | `create(name, *, public, collaborative, description, user_id)`                   | Create a playlist                            |
 | `update(playlist_id, *, name, public, collaborative, description)`               | Update playlist details                      |
-| `add(playlist_id, uris, *, position)`                                            | Add tracks to a playlist                     |
-| `remove(playlist_id, uris)`                                                      | Remove tracks from a playlist                |
-| `reorder(playlist_id, *, range_start, insert_before, range_length, snapshot_id)` | Reorder tracks                               |
+| `add(playlist_id, uris, *, position)`                                            | Add items to a playlist                      |
+| `remove(playlist_id, uris)`                                                      | Remove items from a playlist                 |
+| `reorder(playlist_id, *, range_start, insert_before, range_length, snapshot_id)` | Reorder items                                |
 | `cover_image(playlist_id)`                                                       | Get playlist cover images                    |
 
 ### Player — `sp.player`
@@ -199,6 +210,14 @@ Spotifyify
 | `unfollow(type, ids)`              | Unfollow artists or users              |
 | `check_following(type, ids)`       | Check if following artists or users    |
 
+## Retries
+
+Spotify API requests automatically retry rate limits (`429`) and temporary server
+errors (`500`, `502`, `503`, `504`). Rate limits honor Spotify's `Retry-After`
+header. Server errors are only retried for idempotent HTTP methods to avoid
+duplicating mutations. Configure the defaults with `max_retries` and
+`retry_backoff_seconds` when constructing `Spotifyify`.
+
 ## Scopes
 
 Use `SpotifyScope` to declare the OAuth scopes your app requires:

{spotifyify-0.2.0 → spotifyify-0.3.0}/spotifyify.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 README.md
 pyproject.toml
 spotifyify/__init__.py
+spotifyify/auth.py
 spotifyify/cache_handler.py
 spotifyify/client.py
 spotifyify/credentials.py
@@ -13,6 +14,11 @@ spotifyify.egg-info/SOURCES.txt
 spotifyify.egg-info/dependency_links.txt
 spotifyify.egg-info/requires.txt
 spotifyify.egg-info/top_level.txt
+spotifyify/http/__init__.py
+spotifyify/http/response.py
+spotifyify/http/retry_policy.py
+spotifyify/http/serialization.py
+spotifyify/http/transport.py
 spotifyify/namespaces/__init__.py
 spotifyify/namespaces/albums.py
 spotifyify/namespaces/artists.py

spotifyify-0.3.0/tests/test_client.py

@@ -0,0 +1,90 @@
+import unittest
+from unittest.mock import AsyncMock
+
+import httpx
+from pydantic import BaseModel
+
+from spotifyify.client import SpotifyClient
+from spotifyify.http.retry_policy import HttpMethod
+from spotifyify.http.transport import HttpTransport
+
+
+class TestSpotifyClient(unittest.IsolatedAsyncioTestCase):
+    def _make_client(self):
+        token_provider = AsyncMock()
+        token_provider.get_access_token.return_value = "fake-token"
+        client = SpotifyClient(
+            token_provider=token_provider,
+            scopes=["user-read-playback-state"],
+            base_url="https://api.spotify.com/v1",
+        )
+        client._transport = AsyncMock(spec=HttpTransport)
+        return client, token_provider
+
+    async def test_open_delegates_to_transport(self):
+        client, _ = self._make_client()
+
+        await client.open()
+
+        client._transport.open.assert_awaited_once()
+
+    async def test_close_delegates_to_transport(self):
+        client, _ = self._make_client()
+
+        await client.close()
+
+        client._transport.close.assert_awaited_once()
+
+    async def test_context_manager_closes_transport(self):
+        client, _ = self._make_client()
+
+        async with client:
+            pass
+
+        client._transport.close.assert_awaited_once()
+
+    async def test_get_adds_token_serializes_params_and_parses_response(self):
+        client, token_provider = self._make_client()
+        client._transport.request.return_value = httpx.Response(
+            200, json={"tracks": []}
+        )
+
+        result = await client.get(
+            "/tracks",
+            params={"offset": None},
+            require_user=False,
+            headers={"X-Test": "value"},
+        )
+
+        self.assertEqual(result, {"tracks": []})
+        token_provider.get_access_token.assert_awaited_once_with(
+            require_user=False,
+            scope=["user-read-playback-state"],
+        )
+        client._transport.request.assert_awaited_once_with(
+            HttpMethod.GET,
+            "/tracks",
+            headers={"Authorization": "Bearer fake-token", "X-Test": "value"},
+            params={},
+            json=None,
+            content=None,
+        )
+
+    async def test_post_sends_serialized_payload(self):
+        class Payload(BaseModel):
+            name: str
+            description: str | None = None
+
+        client, _ = self._make_client()
+        client._transport.request.return_value = httpx.Response(204)
+
+        await client.post("/playlists", payload=Payload(name="test"))
+
+        client._transport.request.assert_awaited_once_with(
+            HttpMethod.POST,
+            "/playlists",
+            headers={"Authorization": "Bearer fake-token"},
+            params=None,
+            json={"name": "test"},
+            content=None,
+        )

spotifyify-0.2.0/spotifyify/client.py

@@ -1,279 +0,0 @@
-from typing import Any, Protocol, Self
-
-from collections.abc import Iterable
-
-import httpx
-from pydantic import BaseModel, ConfigDict
-
-from spotifyify.exceptions import SpotifyAPIError
-
-
-class QueryParams(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class RequestPayload(BaseModel):
-    model_config = ConfigDict(extra="allow")
-
-
-class AccessTokenProvider(Protocol):
-    async def get_access_token(
-        self,
-        require_user: bool,
-        scope: str | list[str] | tuple[str, ...] | None = None,
-    ) -> str: ...
-
-
-def parse_response(response: httpx.Response) -> dict[str, Any] | list[Any] | None:
-    if response.status_code == 204:
-        return None
-
-    if response.status_code >= 400:
-        try:
-            data = response.json()
-            err = data.get("error", data) if isinstance(data, dict) else data
-            message = (
-                err.get("message", response.text) if isinstance(err, dict) else str(err)
-            )
-        except ValueError:
-            data = None
-            message = response.text
-        raise SpotifyAPIError(
-            response.status_code,
-            message,
-            data if isinstance(data, dict) else None,
-        )
-
-    if not response.content:
-        return None
-
-    return response.json()
-
-
-class SpotifyClient:
-    def __init__(
-        self,
-        token_provider: AccessTokenProvider,
-        scopes: Iterable[str] | None,
-        *,
-        base_url: str,
-        timeout: float = 10.0,
-    ) -> None:
-        self._token_provider = token_provider
-        self._scopes = list(scopes or [])
-        self._base_url = base_url
-        self._timeout = timeout
-        self._client: httpx.AsyncClient | None = None
-
-    async def open(self) -> None:
-        if self._client is None:
-            self._client = httpx.AsyncClient(
-                base_url=self._base_url, timeout=self._timeout
-            )
-
-    async def __aenter__(self) -> Self:
-        return self
-
-    async def __aexit__(self, exc_type, exc, tb) -> None:
-        await self.close()
-
-    async def close(self) -> None:
-        if self._client is None:
-            return
-        await self._client.aclose()
-        self._client = None
-
-    @staticmethod
-    def _dump_params(
-        params: QueryParams | BaseModel | dict[str, Any] | None,
-    ) -> dict[str, Any] | None:
-        if params is None:
-            return None
-        if isinstance(params, BaseModel):
-            return params.model_dump(mode="json", exclude_none=True)
-        return QueryParams.model_validate(params).model_dump(
-            mode="json", exclude_none=True
-        )
-
-    @staticmethod
-    def _dump_payload(
-        payload: RequestPayload | BaseModel | dict[str, Any] | list[Any] | str | None,
-    ) -> dict[str, Any] | list[Any] | str | None:
-        if payload is None:
-            return None
-        if isinstance(payload, BaseModel):
-            return payload.model_dump(mode="json", exclude_none=True)
-        if isinstance(payload, (dict, list, str)):
-            return payload
-        raise TypeError("payload must be a Pydantic model, dict, list, str, or None")
-
-    async def request_json(
-        self,
-        method: str,
-        path: str,
-        *,
-        params: QueryParams | BaseModel | dict[str, Any] | None = None,
-        payload: RequestPayload
-        | BaseModel
-        | dict[str, Any]
-        | list[Any]
-        | str
-        | None = None,
-        content: str | bytes | None = None,
-        require_user: bool = True,
-        headers: dict[str, str] | None = None,
-        response_model: type[BaseModel] | None = None,
-    ) -> Any:
-        await self.open()
-        token = await self._token_provider.get_access_token(
-            require_user=require_user,
-            scope=self._scopes,
-        )
-        request_headers = {"Authorization": f"Bearer {token}"}
-        if headers:
-            request_headers.update(headers)
-        if self._client is None:
-            raise RuntimeError("HTTP client was not initialized")
-
-        json_payload = None if content is not None else self._dump_payload(payload)
-        response = await self._client.request(
-            method,
-            path,
-            headers=request_headers,
-            params=self._dump_params(params),
-            json=json_payload,
-            content=content,
-        )
-        parsed = parse_response(response)
-
-        if response_model is None or parsed is None:
-            return parsed
-        if isinstance(parsed, list):
-            raise SpotifyAPIError(500, "Expected object response but got list")
-        return response_model.model_validate(parsed)
-
-    async def get(
-        self,
-        path: str,
-        *,
-        params: QueryParams | BaseModel | dict[str, Any] | None = None,
-        require_user: bool = True,
-        headers: dict[str, str] | None = None,
-        response_model: type[BaseModel] | None = None,
-    ) -> Any:
-        return await self.request_json(
-            "GET",
-            path,
-            params=params,
-            require_user=require_user,
-            headers=headers,
-            response_model=response_model,
-        )
-
-    async def post(
-        self,
-        path: str,
-        *,
-        params: QueryParams | BaseModel | dict[str, Any] | None = None,
-        payload: RequestPayload
-        | BaseModel
-        | dict[str, Any]
-        | list[Any]
-        | str
-        | None = None,
-        content: str | bytes | None = None,
-        require_user: bool = True,
-        headers: dict[str, str] | None = None,
-        response_model: type[BaseModel] | None = None,
-    ) -> Any:
-        return await self.request_json(
-            "POST",
-            path,
-            params=params,
-            payload=payload,
-            content=content,
-            require_user=require_user,
-            headers=headers,
-            response_model=response_model,
-        )
-
-    async def put(
-        self,
-        path: str,
-        *,
-        params: QueryParams | BaseModel | dict[str, Any] | None = None,
-        payload: RequestPayload
-        | BaseModel
-        | dict[str, Any]
-        | list[Any]
-        | str
-        | None = None,
-        content: str | bytes | None = None,
-        require_user: bool = True,
-        headers: dict[str, str] | None = None,
-        response_model: type[BaseModel] | None = None,
-    ) -> Any:
-        return await self.request_json(
-            "PUT",
-            path,
-            params=params,
-            payload=payload,
-            content=content,
-            require_user=require_user,
-            headers=headers,
-            response_model=response_model,
-        )
-
-    async def patch(
-        self,
-        path: str,
-        *,
-        params: QueryParams | BaseModel | dict[str, Any] | None = None,
-        payload: RequestPayload
-        | BaseModel
-        | dict[str, Any]
-        | list[Any]
-        | str
-        | None = None,
-        content: str | bytes | None = None,
-        require_user: bool = True,
-        headers: dict[str, str] | None = None,
-        response_model: type[BaseModel] | None = None,
-    ) -> Any:
-        return await self.request_json(
-            "PATCH",
-            path,
-            params=params,
-            payload=payload,
-            content=content,
-            require_user=require_user,
-            headers=headers,
-            response_model=response_model,
-        )
-
-    async def delete(
-        self,
-        path: str,
-        *,
-        params: QueryParams | BaseModel | dict[str, Any] | None = None,
-        payload: RequestPayload
-        | BaseModel
-        | dict[str, Any]
-        | list[Any]
-        | str
-        | None = None,
-        content: str | bytes | None = None,
-        require_user: bool = True,
-        headers: dict[str, str] | None = None,
-        response_model: type[BaseModel] | None = None,
-    ) -> Any:
-        return await self.request_json(
-            "DELETE",
-            path,
-            params=params,
-            payload=payload,
-            content=content,
-            require_user=require_user,
-            headers=headers,
-            response_model=response_model,
-        )

spotifyify-0.2.0/tests/test_client.py

@@ -1,131 +0,0 @@
-import unittest
-from unittest.mock import AsyncMock, MagicMock
-
-import httpx
-
-from spotifyify.client import SpotifyClient, QueryParams, RequestPayload, parse_response
-from spotifyify.exceptions import SpotifyAPIError
-
-
-class TestParseResponse(unittest.TestCase):
-    def _make_response(self, status_code, json_data=None, content=b"", text=""):
-        resp = MagicMock(spec=httpx.Response)
-        resp.status_code = status_code
-        resp.content = content
-        resp.text = text
-        if json_data is not None:
-            resp.json.return_value = json_data
-            resp.content = b'{"data": true}'
-        else:
-            resp.json.side_effect = ValueError("No JSON")
-        return resp
-
-    def test_204_returns_none(self):
-        resp = self._make_response(204)
-        self.assertIsNone(parse_response(resp))
-
-    def test_empty_content_returns_none(self):
-        resp = self._make_response(200, content=b"")
-        resp.json.side_effect = ValueError
-        self.assertIsNone(parse_response(resp))
-
-    def test_200_with_json(self):
-        resp = self._make_response(200, json_data={"tracks": []})
-        result = parse_response(resp)
-        self.assertEqual(result, {"tracks": []})
-
-    def test_400_raises_spotify_api_error_with_error_object(self):
-        resp = self._make_response(
-            400,
-            json_data={"error": {"message": "bad request"}},
-        )
-        with self.assertRaises(SpotifyAPIError) as ctx:
-            parse_response(resp)
-        self.assertEqual(ctx.exception.status_code, 400)
-        self.assertEqual(ctx.exception.message, "bad request")
-
-    def test_400_raises_with_plain_message(self):
-        resp = self._make_response(400)
-        resp.text = "server error"
-        with self.assertRaises(SpotifyAPIError) as ctx:
-            parse_response(resp)
-        self.assertEqual(ctx.exception.message, "server error")
-
-    def test_400_with_non_dict_error(self):
-        resp = self._make_response(400, json_data={"error": "simple string"})
-        with self.assertRaises(SpotifyAPIError) as ctx:
-            parse_response(resp)
-        self.assertEqual(ctx.exception.message, "simple string")
-
-
-class TestDumpParams(unittest.TestCase):
-    def test_none_returns_none(self):
-        self.assertIsNone(SpotifyClient._dump_params(None))
-
-    def test_dict_input(self):
-        result = SpotifyClient._dump_params({"limit": 10, "offset": None})
-        self.assertEqual(result, {"limit": 10})
-
-    def test_pydantic_model_input(self):
-        params = QueryParams(limit=5)
-        result = SpotifyClient._dump_params(params)
-        self.assertEqual(result, {"limit": 5})
-
-
-class TestDumpPayload(unittest.TestCase):
-    def test_none_returns_none(self):
-        self.assertIsNone(SpotifyClient._dump_payload(None))
-
-    def test_dict_passthrough(self):
-        d = {"name": "test"}
-        self.assertIs(SpotifyClient._dump_payload(d), d)
-
-    def test_list_passthrough(self):
-        lst = [1, 2, 3]
-        self.assertIs(SpotifyClient._dump_payload(lst), lst)
-
-    def test_string_passthrough(self):
-        self.assertIs(SpotifyClient._dump_payload("hello"), "hello")
-
-    def test_pydantic_model(self):
-        payload = RequestPayload(name="test")
-        result = SpotifyClient._dump_payload(payload)
-        self.assertEqual(result, {"name": "test"})
-
-    def test_invalid_type_raises(self):
-        with self.assertRaises(TypeError):
-            SpotifyClient._dump_payload(42)
-
-
-class TestSpotifyClientLifecycle(unittest.IsolatedAsyncioTestCase):
-    def _make_client(self):
-        token_provider = AsyncMock()
-        token_provider.get_access_token.return_value = "fake-token"
-        return SpotifyClient(
-            token_provider=token_provider,
-            scopes=["user-read-playback-state"],
-            base_url="https://api.spotify.com/v1",
-        )
-
-    async def test_open_creates_httpx_client(self):
-        client = self._make_client()
-        self.assertIsNone(client._client)
-        await client.open()
-        self.assertIsNotNone(client._client)
-        await client.close()
-
-    async def test_close_sets_client_to_none(self):
-        client = self._make_client()
-        await client.open()
-        await client.close()
-        self.assertIsNone(client._client)
-
-    async def test_close_idempotent(self):
-        client = self._make_client()
-        await client.close()  # should not raise
-
-    async def test_context_manager(self):
-        client = self._make_client()
-        async with client:
-            pass
-        self.assertIsNone(client._client)