spotifyify 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spotifyify
-Version: 0.2.0
+Version: 0.4.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,38 @@ 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`.
+
+Use a request-context retry hook when retries should be reported to a caller.
+The hook is isolated per async task, so one shared `Spotifyify` instance can be
+used by concurrent conversations. `retry_number` is one-based and `retry_at`
+contains the planned retry time in UTC:
+
+```python
+from spotifyify import RetryEvent
+
+async def on_retry(event: RetryEvent) -> None:
+    await sse_bus.emit(
+        conversation_id,
+        {
+            "status_code": event.status_code,
+            "retry_number": event.retry_number,
+            "max_retries": event.max_retries,
+            "retry_in_seconds": event.retry_in_seconds,
+            "retry_at": event.retry_at.isoformat(),
+        },
+    )
+
+with spotify.retry_hook(on_retry):
+    track = await spotify.tracks.get(track_id)
+```
+
 ## Scopes
 
 Use `SpotifyScope` to declare the OAuth scopes your app requires:

spotifyify-0.2.0/PKG-INFO → spotifyify-0.4.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,38 @@ 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`.
+
+Use a request-context retry hook when retries should be reported to a caller.
+The hook is isolated per async task, so one shared `Spotifyify` instance can be
+used by concurrent conversations. `retry_number` is one-based and `retry_at`
+contains the planned retry time in UTC:
+
+```python
+from spotifyify import RetryEvent
+
+async def on_retry(event: RetryEvent) -> None:
+    await sse_bus.emit(
+        conversation_id,
+        {
+            "status_code": event.status_code,
+            "retry_number": event.retry_number,
+            "max_retries": event.max_retries,
+            "retry_in_seconds": event.retry_in_seconds,
+            "retry_at": event.retry_at.isoformat(),
+        },
+    )
+
+with spotify.retry_hook(on_retry):
+    track = await spotify.tracks.get(track_id)
+```
+
 ## Scopes
 
 Use `SpotifyScope` to declare the OAuth scopes your app requires:

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

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

{spotifyify-0.2.0 → spotifyify-0.4.0}/spotifyify/__init__.py

@@ -1,123 +1,130 @@
-from .spotifyify import Spotifyify
-from .credentials import SpotifyCredentials
-from .oauth2 import SpotifyScope
-from .schemas import (
-    # Core models
-    Track,
-    Album,
-    Artist,
-    Playlist,
-    Episode,
-    Show,
-    Device,
-    PlaybackState,
-    PlayerQueue,
-    AudioFeatures,
-    AudioAnalysis,
-    User,
-    PublicUser,
-    Image,
-    ExternalUrl,
-    Followers,
-    Context,
-    Category,
-    PlaylistTrack,
-    # Simplified models
-    SimplifiedTrack,
-    SimplifiedAlbum,
-    SimplifiedArtist,
-    SimplifiedPlaylist,
-    SimplifiedEpisode,
-    SimplifiedShow,
-    ArtistDiscographyAlbum,
-    # Saved-item wrappers
-    SavedTrack,
-    SavedAlbum,
-    SavedShow,
-    SavedEpisode,
-    # Compound models
-    PlayHistory,
-    Recommendations,
-    # Paging bases
-    Paging,
-    CursorPaging,
-    # Typed paging
-    PagingTrack,
-    PagingArtist,
-    PagingPlaylist,
-    PagingPlaylistTrack,
-    PagingSimplifiedTrack,
-    PagingSimplifiedAlbum,
-    PagingSimplifiedEpisode,
-    PagingSimplifiedShow,
-    PagingArtistDiscographyAlbum,
-    PagingSavedTrack,
-    PagingSavedAlbum,
-    PagingSavedShow,
-    PagingSavedEpisode,
-    CursorPagingPlayHistory,
-    CursorPagingSimplifiedArtist,
-)
-
-
-__all__ = [
-    # Client & config
-    "Spotifyify",
-    "SpotifyCredentials",
-    "SpotifyScope",
-    # Core models
-    "Track",
-    "Album",
-    "Artist",
-    "Playlist",
-    "Episode",
-    "Show",
-    "Device",
-    "PlaybackState",
-    "PlayerQueue",
-    "AudioFeatures",
-    "AudioAnalysis",
-    "User",
-    "PublicUser",
-    "Image",
-    "ExternalUrl",
-    "Followers",
-    "Context",
-    "Category",
-    "PlaylistTrack",
-    # Simplified models
-    "SimplifiedTrack",
-    "SimplifiedAlbum",
-    "SimplifiedArtist",
-    "SimplifiedPlaylist",
-    "SimplifiedEpisode",
-    "SimplifiedShow",
-    "ArtistDiscographyAlbum",
-    # Saved-item wrappers
-    "SavedTrack",
-    "SavedAlbum",
-    "SavedShow",
-    "SavedEpisode",
-    # Compound models
-    "PlayHistory",
-    "Recommendations",
-    # Paging bases
-    "Paging",
-    "CursorPaging",
-    # Typed paging
-    "PagingTrack",
-    "PagingArtist",
-    "PagingPlaylist",
-    "PagingPlaylistTrack",
-    "PagingSimplifiedTrack",
-    "PagingSimplifiedAlbum",
-    "PagingSimplifiedEpisode",
-    "PagingSimplifiedShow",
-    "PagingArtistDiscographyAlbum",
-    "PagingSavedTrack",
-    "PagingSavedAlbum",
-    "PagingSavedShow",
-    "PagingSavedEpisode",
-    "CursorPagingPlayHistory",
-    "CursorPagingSimplifiedArtist",
-]
+import logging
+
+from .spotifyify import Spotifyify
+from .credentials import SpotifyCredentials
+from .oauth2 import SpotifyScope
+from .http import OnRetryHook, RetryEvent
+from .schemas import (
+    # Core models
+    Track,
+    Album,
+    Artist,
+    Playlist,
+    Episode,
+    Show,
+    Device,
+    PlaybackState,
+    PlayerQueue,
+    AudioFeatures,
+    AudioAnalysis,
+    User,
+    PublicUser,
+    Image,
+    ExternalUrl,
+    Followers,
+    Context,
+    Category,
+    PlaylistTrack,
+    # Simplified models
+    SimplifiedTrack,
+    SimplifiedAlbum,
+    SimplifiedArtist,
+    SimplifiedPlaylist,
+    SimplifiedEpisode,
+    SimplifiedShow,
+    ArtistDiscographyAlbum,
+    # Saved-item wrappers
+    SavedTrack,
+    SavedAlbum,
+    SavedShow,
+    SavedEpisode,
+    # Compound models
+    PlayHistory,
+    Recommendations,
+    # Paging bases
+    Paging,
+    CursorPaging,
+    # Typed paging
+    PagingTrack,
+    PagingArtist,
+    PagingPlaylist,
+    PagingPlaylistTrack,
+    PagingSimplifiedTrack,
+    PagingSimplifiedAlbum,
+    PagingSimplifiedEpisode,
+    PagingSimplifiedShow,
+    PagingArtistDiscographyAlbum,
+    PagingSavedTrack,
+    PagingSavedAlbum,
+    PagingSavedShow,
+    PagingSavedEpisode,
+    CursorPagingPlayHistory,
+    CursorPagingSimplifiedArtist,
+)
+
+
+__all__ = [
+    # Client & config
+    "Spotifyify",
+    "SpotifyCredentials",
+    "SpotifyScope",
+    "OnRetryHook",
+    "RetryEvent",
+    # Core models
+    "Track",
+    "Album",
+    "Artist",
+    "Playlist",
+    "Episode",
+    "Show",
+    "Device",
+    "PlaybackState",
+    "PlayerQueue",
+    "AudioFeatures",
+    "AudioAnalysis",
+    "User",
+    "PublicUser",
+    "Image",
+    "ExternalUrl",
+    "Followers",
+    "Context",
+    "Category",
+    "PlaylistTrack",
+    # Simplified models
+    "SimplifiedTrack",
+    "SimplifiedAlbum",
+    "SimplifiedArtist",
+    "SimplifiedPlaylist",
+    "SimplifiedEpisode",
+    "SimplifiedShow",
+    "ArtistDiscographyAlbum",
+    # Saved-item wrappers
+    "SavedTrack",
+    "SavedAlbum",
+    "SavedShow",
+    "SavedEpisode",
+    # Compound models
+    "PlayHistory",
+    "Recommendations",
+    # Paging bases
+    "Paging",
+    "CursorPaging",
+    # Typed paging
+    "PagingTrack",
+    "PagingArtist",
+    "PagingPlaylist",
+    "PagingPlaylistTrack",
+    "PagingSimplifiedTrack",
+    "PagingSimplifiedAlbum",
+    "PagingSimplifiedEpisode",
+    "PagingSimplifiedShow",
+    "PagingArtistDiscographyAlbum",
+    "PagingSavedTrack",
+    "PagingSavedAlbum",
+    "PagingSavedShow",
+    "PagingSavedEpisode",
+    "CursorPagingPlayHistory",
+    "CursorPagingSimplifiedArtist",
+]
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())

spotifyify-0.4.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.2.0 → spotifyify-0.4.0}/spotifyify/cache_handler.py

@@ -1,42 +1,63 @@
-import abc
-import json
-from pathlib import Path
-from typing import Any
-
-
-class CacheHandler(abc.ABC):
-    @abc.abstractmethod
-    def get_cached_token(self) -> dict[str, Any] | None:
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def save_token_to_cache(self, token_info: dict[str, Any]) -> None:
-        raise NotImplementedError
-
-
-class MemoryCacheHandler(CacheHandler):
-    def __init__(self, token_info: dict[str, Any] | None = None) -> None:
-        self._token_info = token_info
-
-    def get_cached_token(self) -> dict[str, Any] | None:
-        return self._token_info
-
-    def save_token_to_cache(self, token_info: dict[str, Any]) -> None:
-        self._token_info = token_info
-
-
-class CacheFileHandler(CacheHandler):
-    def __init__(self, cache_path: str | Path = ".cache") -> None:
-        self.cache_path = Path(cache_path)
-
-    def get_cached_token(self) -> dict[str, Any] | None:
-        if not self.cache_path.exists():
-            return None
-        try:
-            return json.loads(self.cache_path.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
-            return None
-
-    def save_token_to_cache(self, token_info: dict[str, Any]) -> None:
-        self.cache_path.parent.mkdir(parents=True, exist_ok=True)
-        self.cache_path.write_text(json.dumps(token_info), encoding="utf-8")
+import abc
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class CacheHandler(abc.ABC):
+    @abc.abstractmethod
+    def get_cached_token(self) -> dict[str, Any] | None:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def save_token_to_cache(self, token_info: dict[str, Any]) -> None:
+        raise NotImplementedError
+
+
+class MemoryCacheHandler(CacheHandler):
+    def __init__(self, token_info: dict[str, Any] | None = None) -> None:
+        self._token_info = token_info
+
+    def get_cached_token(self) -> dict[str, Any] | None:
+        logger.debug("Reading token from memory cache")
+        return self._token_info
+
+    def save_token_to_cache(self, token_info: dict[str, Any]) -> None:
+        logger.debug("Saving token to memory cache")
+        self._token_info = token_info
+
+
+class CacheFileHandler(CacheHandler):
+    def __init__(self, cache_path: str | Path = ".cache") -> None:
+        self.cache_path = Path(cache_path)
+
+    def get_cached_token(self) -> dict[str, Any] | None:
+        if not self.cache_path.exists():
+            logger.debug("Token cache file does not exist: path=%s", self.cache_path)
+            return None
+        try:
+            token_info = json.loads(self.cache_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            logger.warning(
+                "Unable to read token cache file: path=%s",
+                self.cache_path,
+                exc_info=True,
+            )
+            return None
+        logger.debug("Read token from cache file: path=%s", self.cache_path)
+        return token_info
+
+    def save_token_to_cache(self, token_info: dict[str, Any]) -> None:
+        try:
+            self.cache_path.parent.mkdir(parents=True, exist_ok=True)
+            self.cache_path.write_text(json.dumps(token_info), encoding="utf-8")
+        except OSError:
+            logger.exception(
+                "Unable to save token cache file: path=%s",
+                self.cache_path,
+            )
+            raise
+        logger.debug("Saved token to cache file: path=%s", self.cache_path)