innerspot 0.0.1.dev2__py3-none-any.whl

innerspot/__init__.py

@@ -0,0 +1,515 @@
+import logging
+import re
+from collections import deque
+from typing import Generator
+
+import httpx
+
+from ._auth import SpotifyAuthBase, SpotifyEmbed, SpotifyPKCE, SpotifyWeb
+from ._cache import CacheFileHandler, CacheHandler, MemoryCacheHandler, TokenInfo
+from ._utils import (
+    api_href,
+    id_from_uri,
+    parse_spotify_id,
+    resolve_image_url,
+    web_url,
+)
+from ._version import __version__
+from .errors import (
+    AccessDeniedError,
+    AuthError,
+    GraphQLError,
+    InnerSpotError,
+    NotFoundError,
+)
+from .models import (
+    Album,
+    AlbumStub,
+    Artist,
+    ArtistWithAlbums,
+    Copyright,
+    ExternalIDs,
+    ExternalURLs,
+    Followers,
+    HomeItem,
+    HomeSection,
+    Lyrics,
+    LyricsLine,
+    PaginatedResult,
+    Playlist,
+    PlaylistOwner,
+    PlaylistTrack,
+    RadioStation,
+    SearchResults,
+    SimplifiedAlbum,
+    SimplifiedArtist,
+    SpotifyImage,
+    Track,
+    TrackStub,
+    User,
+)
+from .providers import PartnerProvider, ScrapingProvider, SpClientProvider
+
+__all__ = [
+    "__version__",
+    "SpotifyClient",
+    "SpotifyAuthBase",
+    "SpotifyWeb",
+    "SpotifyEmbed",
+    "SpotifyPKCE",
+    "InnerSpotError",
+    "AuthError",
+    "AccessDeniedError",
+    "NotFoundError",
+    "GraphQLError",
+    "SpClientProvider",
+    "PartnerProvider",
+    "ScrapingProvider",
+    "CacheHandler",
+    "CacheFileHandler",
+    "MemoryCacheHandler",
+    "TokenInfo",
+    "Album",
+    "AlbumStub",
+    "ArtistWithAlbums",
+    "Artist",
+    "Copyright",
+    "ExternalIDs",
+    "ExternalURLs",
+    "Followers",
+    "HomeItem",
+    "HomeSection",
+    "Lyrics",
+    "LyricsLine",
+    "PaginatedResult",
+    "Playlist",
+    "PlaylistOwner",
+    "PlaylistTrack",
+    "RadioStation",
+    "SearchResults",
+    "SimplifiedAlbum",
+    "SimplifiedArtist",
+    "SpotifyImage",
+    "Track",
+    "TrackStub",
+    "User",
+]
+
+logger = logging.getLogger(__name__)
+
+_BOT_UA = "Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)"
+
+
+class SpotifyClient:
+    """High-level Spotify client with direct provider access and convenience methods.
+
+    Providers are accessible directly:
+        client.spclient   — SpClientProvider (protobuf/JSON internal API)
+        client.partner    — PartnerProvider (GraphQL partner API)
+        client.scraping   — ScrapingProvider (HTML page scraping)
+
+    Convenience methods (get_track, get_album, etc.) try providers in order
+    with automatic fallback.
+    """
+
+    def __init__(self, auth: SpotifyAuthBase | None = None) -> None:
+        self._http = httpx.Client(
+            headers={"User-Agent": _BOT_UA},
+            follow_redirects=True,
+            timeout=15,
+        )
+
+        self._auth = auth or SpotifyWeb()
+
+        self.spclient = SpClientProvider(self._http, self._auth)
+        self.partner = PartnerProvider(self._http, self._auth)
+        self.scraping = ScrapingProvider(self._http, self._auth)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "SpotifyClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    # ── Convenience methods with fallback ──
+
+    def get_track(self, track_id: str) -> Track:
+        """Get track metadata. Tries: spclient → partner → scraping."""
+        return self._fallback(
+            track_id,
+            self.spclient.get_track,
+            self.partner.get_track,
+            self.scraping.get_track,
+        )
+
+    def get_album(
+        self, album_id: str, offset: int = 0, limit: int = 300, **kwargs
+    ) -> Album:
+        """Get album metadata. Tries: spclient → partner.
+
+        When using spclient, all tracks are returned (offset/limit ignored).
+        When using partner, tracks are paginated.
+        """
+        return self._fallback(
+            album_id,
+            self.spclient.get_album,
+            lambda aid: self.partner.get_album(
+                aid, offset=offset, limit=limit, **kwargs
+            ),
+        )
+
+    def get_artist(self, artist_id: str) -> Artist:
+        """Get artist metadata. Tries: spclient → partner."""
+        return self._fallback(
+            artist_id,
+            self.spclient.get_artist,
+            self.partner.get_artist,
+        )
+
+    def get_playlist(
+        self, playlist_id: str, offset: int = 0, limit: int = 400, **kwargs
+    ) -> Playlist:
+        """Get playlist via partner GraphQL API. Tracks are paginated."""
+        return self.partner.get_playlist(
+            playlist_id, offset=offset, limit=limit, **kwargs
+        )
+
+    def get_user(self, user_id: str) -> User:
+        """Get user profile. Falls back to stub User on failure."""
+        try:
+            return self.spclient.user_profile(user_id)
+        except Exception:
+            pass
+        return User(
+            id=user_id,
+            display_name=user_id,
+            uri=f"spotify:user:{user_id}",
+            external_urls=ExternalURLs(
+                spotify=f"https://open.spotify.com/user/{user_id}"
+            ),
+        )
+
+    def get_lyrics(self, track_id: str) -> Lyrics:
+        """Get lyrics for a track (synced or unsynced).
+
+        Requires authenticated token — use SpotifyWeb(sp_dc=...) or SpotifyPKCE().
+        """
+        return self.spclient.color_lyrics(track_id)
+
+    def get_artists(self, artist_ids: list[str]) -> dict[str, Artist]:
+        """Fetch multiple artists in a single protobuf call."""
+        return self.spclient.get_artists(artist_ids)
+
+    def get_artist_discography(
+        self, artist_id: str, include_groups: str = "album,single"
+    ) -> ArtistWithAlbums:
+        """Get artist with full discography."""
+        return self.spclient.get_artist_discography(artist_id, include_groups)
+
+    def get_artist_top_tracks(self, artist_id: str, **kwargs) -> list[TrackStub]:
+        """Get artist's top tracks via partner GraphQL."""
+        return self.partner.get_artist_top_tracks(artist_id, **kwargs)
+
+    def get_artist_albums(
+        self, artist_id: str, offset: int = 0, limit: int = 50, **kwargs
+    ) -> list[AlbumStub]:
+        """Get artist's albums via partner GraphQL. Paginated."""
+        return self.partner.get_artist_albums(
+            artist_id, offset=offset, limit=limit, **kwargs
+        )
+
+    def search(self, query: str, limit: int = 20, **kwargs) -> SearchResults:
+        """Search for tracks, albums, artists, playlists. Works anonymously."""
+        return self._fallback(
+            None,
+            lambda _: self.partner.search(query, limit=limit, **kwargs),
+            lambda _: self._search_results_from_spclient(
+                self.spclient.search(query, limit=limit)
+            ),
+        )
+
+    def get_isrc_track(self, isrc: str) -> Track:
+        results = self.search(query=f"isrc:{isrc}")
+        items = results.tracks.items
+        if not items:
+            raise ValueError(f"No track found for ISRC: {isrc}")
+        best = max(
+            items, key=lambda x: x.get("popularity", 0) if isinstance(x, dict) else 0
+        )
+        return self.get_track(self._extract_id(best))
+
+    def get_radio(
+        self,
+        seed_uri: str,
+        count: int = 200,
+        prev_tracks: str | None = None,
+    ) -> RadioStation:
+        """Get a full radio station from a seed URI."""
+        return self.spclient.radio(seed_uri, count=count, prev_tracks=prev_tracks)
+
+    def get_chart(self, playlist_id: str) -> dict:
+        """Get chart playlist with track rankings via context-resolve."""
+        return self.spclient.context_resolve(f"spotify:playlist:{playlist_id}")
+
+    def get_inspired_playlist(self, seed_uri: str) -> list[str]:
+        """Get Spotify-generated playlist URIs from a seed."""
+        return self.spclient.inspired_playlist(seed_uri)
+
+    def search_genre(self, genre: str, limit: int = 50) -> SearchResults:
+        """Search for popular tracks and artists in a genre."""
+        return self.search(f"genre:{genre}", limit=limit)
+
+    def get_charts(self) -> list[HomeItem]:
+        """Get all available chart playlists from the home feed."""
+        charts: dict[str, HomeItem] = {}
+        for section in self.get_home_sections(limit=50):
+            if not section.title or "chart" not in section.title.lower():
+                continue
+            for item in section.items:
+                if item.uri and ":playlist:" in item.uri:
+                    pid = item.uri.split(":")[-1]
+                    if pid not in charts:
+                        charts[pid] = item
+        return list(charts.values())
+
+    def get_home_sections(self, limit: int = 20) -> list[HomeSection]:
+        """Get all home page sections with their items."""
+        return self.partner.get_home_sections(limit=limit)
+
+    def get_playlist_with_tracks(self, playlist_id: str) -> Playlist:
+        """Get a playlist with ALL tracks via context-resolve."""
+        data = self.spclient.context_resolve(f"spotify:playlist:{playlist_id}")
+        meta = data.get("metadata", {})
+        tracks = [
+            PlaylistTrack(
+                added_at=t.raw.get("added_at") if t.raw else None,
+                track=t,
+            )
+            for t in self._iter_context_tracks(data)
+        ]
+        return Playlist(
+            id=playlist_id,
+            name=meta.get("context_description")
+            or meta.get("context_long_description"),
+            uri=data.get("uri") or f"spotify:playlist:{playlist_id}",
+            href=api_href("playlists", playlist_id),
+            external_urls=ExternalURLs(spotify=web_url("playlist", playlist_id)),
+            images=[SpotifyImage(url=meta["image_url"])]
+            if meta.get("image_url")
+            else [],
+            owner=PlaylistOwner(display_name=meta.get("context_owner")),
+            tracks=tracks,
+            total_tracks=len(tracks),
+            raw=data,
+        )
+
+    def iter_user_playlists(
+        self,
+        user_id: str,
+    ) -> Generator[Playlist, None, None]:
+        try:
+            resp = self._http.get(
+                f"https://open.spotify.com/user/{user_id}",
+                headers={"User-Agent": _BOT_UA},
+            )
+            resp.raise_for_status()
+            pids = list(
+                dict.fromkeys(
+                    re.findall(
+                        r"open\.spotify\.com/playlist/([a-zA-Z0-9]{22})", resp.text
+                    )
+                )
+            )
+            for pid in pids:
+                try:
+                    yield self.get_playlist(pid)
+                except Exception:
+                    pass
+        except Exception as exc:
+            logger.warning("iter_user_playlists failed: %s", exc)
+
+    def get_featured_playlists(self) -> list[HomeItem]:
+        """Get featured/popular playlists from the home feed."""
+        return [
+            item
+            for section in self.get_home_sections(limit=50)
+            for item in section.items
+            if item.uri and ":playlist:" in item.uri
+        ]
+
+    def get_new_releases(self) -> list[AlbumStub]:
+        """Get new release albums via spclient search (tag:new)."""
+        data = self.spclient.search("tag:new", limit=50)
+        releases = []
+        for hit in data.get("results", {}).get("albums", {}).get("hits", []):
+            album_id = id_from_uri(hit.get("uri", ""))
+            image_url = resolve_image_url(hit.get("image", ""))
+            artists = [
+                SimplifiedArtist(
+                    id=id_from_uri(a["uri"]),
+                    uri=a["uri"],
+                    name=a.get("name", ""),
+                )
+                for a in hit.get("artists", [])
+                if a.get("uri")
+            ]
+            releases.append(
+                AlbumStub(
+                    id=album_id,
+                    name=hit.get("name"),
+                    uri=hit.get("uri"),
+                    href=api_href("albums", album_id),
+                    external_urls=ExternalURLs(spotify=web_url("album", album_id)),
+                    images=[SpotifyImage(url=image_url)] if image_url else [],
+                    artists=artists,
+                )
+            )
+        return releases
+
+    def iter_genre_tracks(
+        self, genre: str, count: int = 200
+    ) -> Generator[TrackStub, None, None]:
+        """Yield tracks for a genre via radio-apollo."""
+        yield from self._iter_radio(f"spotify:genre:{genre}", count)
+
+    def iter_artist_radio(
+        self, artist_id: str, count: int = 200
+    ) -> Generator[TrackStub, None, None]:
+        """Yield recommended tracks similar to an artist."""
+        yield from self._iter_radio(f"spotify:artist:{artist_id}", count)
+
+    def iter_track_radio(
+        self, track_id: str, count: int = 200
+    ) -> Generator[TrackStub, None, None]:
+        """Yield recommended tracks similar to a track."""
+        yield from self._iter_radio(f"spotify:track:{track_id}", count)
+
+    def get_chart_tracks(self, chart_playlist_id: str) -> list[TrackStub]:
+        """Get all tracks from a chart playlist."""
+        playlist = self.get_playlist_with_tracks(chart_playlist_id)
+        return [pt.track for pt in playlist.tracks if pt.track]
+
+    @staticmethod
+    def parse_id(value: str) -> tuple[str, str]:
+        """Parse a Spotify URI, URL, or raw ID. Returns (id, type)."""
+        return parse_spotify_id(value)
+
+    # ── Private helpers ──
+
+    def _fallback(self, arg, *providers):
+        """Try providers in order, return first success."""
+        last_exc: Exception | None = None
+        for fn in providers:
+            try:
+                return fn(arg)
+            except Exception as exc:
+                logger.warning("%s failed: %s", fn.__qualname__, exc)
+                last_exc = exc
+        raise last_exc or RuntimeError("All providers failed")
+
+    def _iter_radio(
+        self, seed_uri: str, count: int
+    ) -> Generator[TrackStub, None, None]:
+        yielded = 0
+        prev_ids: deque[str] = deque(maxlen=100)
+        while yielded < count:
+            page_size = min(count - yielded, 200)
+            station = self.get_radio(
+                seed_uri,
+                count=page_size,
+                prev_tracks=",".join(prev_ids) if prev_ids else None,
+            )
+            if not station.tracks:
+                break
+            for t in station.tracks:
+                yield self._parse_radio_track(t)
+                prev_ids.append(t.original_gid or t.id or "")
+                yielded += 1
+                if yielded >= count:
+                    break
+
+    def _iter_context_tracks(self, data: dict) -> Generator[TrackStub, None, None]:
+        for page in data.get("pages", []):
+            for t in page.get("tracks", []):
+                track_id = id_from_uri(t.get("uri", ""))
+                if track_id:
+                    yield TrackStub(
+                        id=track_id,
+                        uri=t.get("uri"),
+                        href=api_href("tracks", track_id),
+                        external_urls=ExternalURLs(spotify=web_url("track", track_id)),
+                        raw=t.get("metadata", {}),
+                    )
+
+    def _parse_radio_track(self, t) -> TrackStub:
+        meta = t.metadata
+        artists = []
+        i = 0
+        while True:
+            key = "artist_name" if i == 0 else f"artist_name:{i}"
+            uri_key = "artist_uri" if i == 0 else f"artist_uri:{i}"
+            name = meta.get(key)
+            if name is None:
+                break
+            a_uri = meta.get(uri_key)
+            if not a_uri:
+                i += 1
+                continue
+            a_id = id_from_uri(a_uri)
+            artists.append(
+                SimplifiedArtist(
+                    id=a_id,
+                    uri=a_uri,
+                    name=name,
+                    href=api_href("artists", a_id),
+                    external_urls=ExternalURLs(spotify=web_url("artist", a_id)),
+                )
+            )
+            i += 1
+
+        track_id = t.id
+        album_uri = t.album_uri
+        album_id = id_from_uri(album_uri) if album_uri else None
+        image_url = resolve_image_url(meta.get("image_url", ""))
+
+        return TrackStub(
+            id=track_id,
+            name=meta.get("title"),
+            uri=t.uri,
+            href=api_href("tracks", track_id),
+            external_urls=ExternalURLs(spotify=web_url("track", track_id)),
+            explicit=meta.get("is_explicit") == "true",
+            artists=artists,
+            album=AlbumStub(
+                id=album_id,
+                name=meta.get("album_title"),
+                uri=album_uri,
+                href=api_href("albums", album_id),
+                external_urls=ExternalURLs(spotify=web_url("album", album_id)),
+                images=[SpotifyImage(url=image_url)] if image_url else [],
+            ),
+            raw=meta,
+        )
+
+    def _search_results_from_spclient(self, data: dict) -> SearchResults:
+        results = data.get("results", {})
+
+        def _hits(section: dict) -> PaginatedResult:
+            hits = section.get("hits", [])
+            return PaginatedResult(items=hits, total=len(hits))
+
+        return SearchResults(
+            tracks=_hits(results.get("tracks", {})),
+            albums=_hits(results.get("albums", {})),
+            artists=_hits(results.get("artists", {})),
+            playlists=_hits(results.get("playlists", {})),
+        )
+
+    @staticmethod
+    def _extract_id(item) -> str:
+        if isinstance(item, dict):
+            return id_from_uri(item.get("uri", "")) or item.get("id", "")
+        return item.id or ""