spots-cli 0.1.0__py3-none-any.whl

spots_cli/engine/file_storage.py

@@ -0,0 +1,347 @@
+from json import load, dump
+from json.decoder import JSONDecodeError
+from logging import getLogger
+from os.path import exists
+from pathlib import Path
+from shutil import move
+from tempfile import NamedTemporaryFile
+from typing import Any, Literal, Optional, TypedDict, Sequence, overload
+
+from spots_cli.models import SongNotFound, Metadata, Sentinel, YTVideoInfo
+from spots_cli.utils import get_config_path
+
+logger = getLogger(__name__)
+
+
+TMetadataCache = dict[str, Metadata | Sentinel]
+TArtistCache = dict[str, Sequence[YTVideoInfo | Sentinel]]
+
+TSerializedRecord = dict[str, dict[str, Any]]
+
+MediaProviders = Literal["artist", "youtube", "yt_likes", "spotify_likes", "metadata"]
+
+NOT_FOUND = Sentinel()
+
+
+class CacheOptions(TypedDict):
+    metadata: TMetadataCache
+    artist: TArtistCache
+    youtube: dict[str, Any]
+    yt_likes: dict[str, YTVideoInfo | Sentinel]
+    spotify_likes: TMetadataCache
+
+
+class SerializedCacheOptions(TypedDict):
+    metadata: dict[str, TSerializedRecord]
+    artist: dict[str, list[dict[str, Any]]]
+    youtube: dict[str, YTVideoInfo]
+    yt_likes: dict[str, TSerializedRecord]
+    spotify_likes: dict[str, TSerializedRecord]
+
+
+class FileStorage:
+    """A class for caching search results in a JSON file."""
+
+    def __init__(self) -> None:
+        self.__file_path = get_config_path() / ".metadata.json"
+        self.__objects: CacheOptions = {
+            "artist": {},
+            "metadata": {},
+            "youtube": {},
+            "yt_likes": {},
+            "spotify_likes": {},
+        }
+        self._dirty = False
+
+    def update_youtube(
+        self,
+        query: str,
+        *,
+        title: Optional[str] = None,
+        uploader: Optional[str] = None,
+    ) -> None:
+        """Update fields of an existing YT-DLP cache entry."""
+        record = self.__objects["youtube"].get(query)
+
+        if not record:
+            return
+
+        if title is not None:
+            record.title = title
+
+        if uploader is not None:
+            record.uploader = uploader
+
+    def cache_file_exists(self) -> None:
+        if not exists(self.__file_path):
+            objects = {
+                "metadata": {},
+                "artist": {},
+                "youtube": {},
+                "yt_likes": {},
+                "spotify_likes": {},
+            }
+
+            with open(self.__file_path, "w") as f:
+                dump(objects, f)
+
+    def get_spotify_likes(self) -> TMetadataCache:
+        return self.__objects["spotify_likes"]
+
+    def all(self) -> CacheOptions:
+        """Returns the stored objects."""
+        return self.__objects
+
+    @overload
+    def new(
+        self,
+        *,
+        query: str,
+        result: YTVideoInfo | Sentinel,
+        query_type: Literal["yt_likes"],
+    ) -> None: ...
+
+    @overload
+    def new(
+        self,
+        *,
+        query: str,
+        result: Metadata | Sentinel,
+        query_type: Literal["metadata"],
+    ) -> None: ...
+
+    @overload
+    def new(
+        self,
+        *,
+        query: str,
+        result: Metadata | Sentinel,
+        query_type: Literal["spotify_likes"],
+    ) -> None: ...
+
+    @overload
+    def new(
+        self,
+        *,
+        query: str,
+        result: Sequence[YTVideoInfo | Sentinel],
+        query_type: Literal["artist"],
+    ) -> None: ...
+
+    @overload
+    def new(
+        self,
+        *,
+        query: str,
+        result: YTVideoInfo | Sentinel,
+        query_type: Literal["youtube"],
+    ) -> None: ...
+
+    def new(
+        self,
+        *,
+        query: str,
+        result,
+        query_type: MediaProviders,
+    ) -> None:
+        query = query.replace(" Audio", "")
+
+        if self.__objects[query_type].get(query):
+            return
+
+        logger.debug(f"[Cache] New entry: {query}")
+        self._dirty = True
+
+        match query_type:
+            case "metadata":
+                self.__objects["metadata"][query] = result
+            case "artist":
+                if not self.__objects["artist"][query]:
+                    self.__objects["artist"][query] = []
+                self.__objects["artist"][query] = list(
+                    self.__objects["artist"][query]
+                ) + [result]
+            case "youtube":
+                self.__objects["youtube"][query] = result
+            case "spotify_likes":
+                self.__objects["spotify_likes"][query] = result
+            case "yt_likes":
+                self.__objects["yt_likes"][query] = result
+
+    def save(self) -> None:
+        """Serializes and saves the cache to the JSON file safely."""
+        if not self._dirty:
+            return
+
+        logger.debug("[Cache] Updating")
+
+        serialized_objects: SerializedCacheOptions = {
+            "metadata": {
+                key: value.__dict__ for key, value in self.__objects["metadata"].items()
+            },
+            "artist": {
+                artist: [item.__dict__ for item in playlist]
+                for artist, playlist in self.__objects["artist"].items()
+            },
+            "youtube": {
+                key: value.__dict__ for key, value in self.__objects["youtube"].items()
+            },
+            "yt_likes": {
+                key: value.__dict__ for key, value in self.__objects["yt_likes"].items()
+            },
+            "spotify_likes": {
+                key: value.__dict__
+                for key, value in self.__objects["spotify_likes"].items()
+            },
+        }
+
+        # Write to temp file in the same directory
+        dir_path = Path(self.__file_path).parent
+        with NamedTemporaryFile(
+            "w", dir=dir_path, delete=False, encoding="utf-8"
+        ) as tmp_file:
+            dump(serialized_objects, tmp_file)
+            temp_path = tmp_file.name
+
+        tmp_file.close()
+
+        # Atomically replace the original file
+        move(temp_path, self.__file_path)
+
+        self._dirty = False
+
+    def reload(self) -> None:
+        """Deserializes and reloads the cache from the JSON file."""
+        logger.debug("[Cache] Loading into memory")
+        try:
+            with open(self.__file_path, "r") as file:
+                loaded_objects = load(file)
+
+                if "metadata" in loaded_objects:
+                    self.__objects["metadata"] = {
+                        key: (
+                            Metadata(**value)
+                            if value != NOT_FOUND.__dict__
+                            else NOT_FOUND
+                        )
+                        for key, value in loaded_objects["metadata"].items()
+                    }
+                else:
+                    self.__objects["metadata"] = {}
+
+                if "spotify_likes" in loaded_objects:
+                    self.__objects["spotify_likes"] = {
+                        key: (
+                            Metadata(**value)
+                            if value != NOT_FOUND.__dict__
+                            else NOT_FOUND
+                        )
+                        for key, value in loaded_objects["spotify_likes"].items()
+                    }
+                else:
+                    self.__objects["spotify_likes"] = {}
+
+                if "artist" in loaded_objects:
+                    self.__objects["artist"] = {
+                        artist: [
+                            (
+                                YTVideoInfo(**item)
+                                if item != NOT_FOUND.__dict__
+                                else NOT_FOUND
+                            )
+                            for item in playlist
+                        ]
+                        for artist, playlist in loaded_objects["artist"].items()
+                    }
+                else:
+                    self.__objects["artist"] = {}
+
+                if "youtube" in loaded_objects:
+                    self.__objects["youtube"] = {
+                        key: (
+                            YTVideoInfo(**value)
+                            if value != NOT_FOUND.__dict__
+                            else NOT_FOUND
+                        )
+                        for key, value in loaded_objects["youtube"].items()
+                    }
+                else:
+                    self.__objects["youtube"] = {}
+
+                if "yt_likes" in loaded_objects:
+                    self.__objects["yt_likes"] = {
+                        key: (
+                            YTVideoInfo(**value)
+                            if value != NOT_FOUND.__dict__
+                            else NOT_FOUND
+                        )
+                        for key, value in loaded_objects["yt_likes"].items()
+                    }
+                else:
+                    self.__objects["yt_likes"] = {}
+        except (FileNotFoundError, JSONDecodeError):
+            self.__objects = {
+                "metadata": {},
+                "artist": {},
+                "youtube": {},
+                "yt_likes": {},
+                "spotify_likes": {},
+            }
+
+    @overload
+    def get(
+        self,
+        *,
+        query: str,
+        query_type: Literal["metadata"],
+        alt_query: str = "",
+    ) -> Metadata: ...
+
+    @overload
+    def get(
+        self,
+        *,
+        query: str,
+        query_type: Literal["artist"],
+        alt_query: str = "",
+    ) -> list[Metadata]: ...
+
+    @overload
+    def get(
+        self,
+        *,
+        query: str,
+        query_type: Literal["youtube"],
+        alt_query: str = "",
+    ) -> YTVideoInfo: ...
+
+    @overload
+    def get(
+        self,
+        *,
+        query: str,
+        query_type: Literal["yt_likes"],
+        alt_query: str = "",
+    ) -> YTVideoInfo: ...
+
+    def get(
+        self,
+        *,
+        query: str,
+        query_type: MediaProviders,
+        alt_query: str = "",
+    ):
+        logger.debug(f"[Cache] Reading: {query} [{query_type}]")
+        query = query.replace(" Audio", "")
+
+        cache = self.__objects[query_type].get(query) or self.__objects[query_type].get(
+            alt_query
+        )
+
+        if isinstance(cache, Sentinel):
+            logger.debug(f"[Cache] Miss: {query}")
+            raise SongNotFound(query)
+
+        else:
+            logger.debug(f"[Cache] Hit: {cache}" if cache else "[Cache] No entry")
+            return cache

spots_cli/engine/persistence_model.py

@@ -0,0 +1,3 @@
+from spots_cli.engine import FileStorage
+
+storage = FileStorage()

spots_cli/engine/retry.py

@@ -0,0 +1,34 @@
+from tenacity import retry as _retry
+from tenacity import retry_if_exception
+
+from spots_cli.models import SongNotFound
+
+
+def is_retryable_exception(exc: BaseException) -> bool:
+    # Only retry transient failures
+    return not isinstance(exc, SongNotFound)
+
+
+def retry(*args, **kwargs):
+    """
+    Project-wide retry decorator.
+    - Never retries SongNotFound
+    - Always re-raises the final exception
+    """
+
+    user_retry = kwargs.pop("retry", None)
+
+    base_retry = retry_if_exception(is_retryable_exception)
+
+    if user_retry is not None:
+        # Combine user retry conditions with ours
+        retry_condition = base_retry & user_retry
+    else:
+        retry_condition = base_retry
+
+    return _retry(
+        *args,
+        retry=retry_condition,
+        reraise=True,
+        **kwargs,
+    )

spots_cli/integrations/__init__.py

@@ -0,0 +1 @@
+from spots_cli.integrations.spotify_user_playlist_modify import SpotifyUserPlaylistModify

spots_cli/integrations/spotify_user_playlist_modify.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from logging import getLogger
+from tenacity import stop_after_delay
+from typing import TYPE_CHECKING
+
+from spots_cli.engine import retry
+from spots_cli.models import SpotifyUnavailableError
+
+if TYPE_CHECKING:
+    from spots_cli.clients import SpotifyClient
+    from spots_cli.bootstrap.container import Clients
+
+
+logger = getLogger(__name__)
+
+
+class SpotifyUserPlaylistModify:
+    """A class to retrieve metadata for a spotify track, album or playlist
+
+    Attributes:
+        track_url (str): The spotify url to be processed
+    """
+
+    def __init__(self, *, clients: Clients) -> None:
+        self.clients = clients
+
+    def _client(self) -> SpotifyClient:
+        if not self.clients.spotify:
+            raise SpotifyUnavailableError(
+                "Spotify client is not configured. Enable Spotify features in your environment."
+            )
+        return self.clients.spotify
+
+    @retry(stop=stop_after_delay(30))
+    def modify_saved_tracks_playlist(self, action: str, tracks: str):
+        # update scope for write
+        self.clients.secrets.write(key="scope", value="user-library-modify")
+        self._client().signin()
+
+        logger.info(f"Removing {tracks} from playlist...")
+        if action == "add":
+            self._client().client.current_user_saved_tracks_add(tracks)
+        elif action == "delete":
+            self._client().client.current_user_saved_tracks_delete([tracks])
+        else:
+            raise TypeError("`delete` or `add` actions only")

spots_cli/models/__init__.py

@@ -0,0 +1,24 @@
+from spots_cli.models.artist_metadata import ArtistMetadata
+from spots_cli.models.errors import (
+    TitleExistsError,
+    InvalidURL,
+    SongNotFound,
+    VersionSkipped,
+    EmptySpotifyLikes,
+    YouTubeQuotaExceeded,
+    SpotifyUnavailableError,
+    YouTubeUnavailableError,
+    InvalidSearchFormat,
+)
+from spots_cli.models.helper_models import (
+    ArtistAndTitle,
+    SearchResponseSingle,
+    SearchResponseMultiple,
+)
+from spots_cli.models.media_resource import MediaResourceSingle, MediaResourcePlaylist
+from spots_cli.models.metadata import Metadata
+from spots_cli.models.metadata_provider import MetadataProvider
+from spots_cli.models.playlist_info import PlaylistInfo
+from spots_cli.models.search_provider import SearchProvider, ArtistInfo
+from spots_cli.models.sentinel import Sentinel
+from spots_cli.models.yt_video_info import YTVideoInfo

spots_cli/models/artist_metadata.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spots_cli.models import PlaylistInfo
+
+
+@dataclass
+class ArtistMetadata:
+    """
+    Metadata for an artist.
+
+    Args:
+        albums list[PlaylistInfo]: a list of metadata for each of the artist's albums/
+        cover (str): The artist's cover url.
+        name (str): The artist's name.
+    """
+
+    albums: list[PlaylistInfo]
+    cover: str
+    name: str

spots_cli/models/errors.py

@@ -0,0 +1,69 @@
+"""Custom error classes"""
+
+
+class TitleExistsError(Exception):
+    """File already downloaded"""
+
+    def __init__(self, title: str):
+        self.message = f"{title} already downloaded"
+        super().__init__(self.message)
+
+
+class InvalidURL(Exception):
+    """Url not valid"""
+
+    def __init__(self, url: str):
+        self.message = f"{url} is invalid"
+        super().__init__(self.message)
+
+
+class SongNotFound(Exception):
+    """A search term is not found"""
+
+    def __init__(self, query: str):
+        self.message = f"{query} not found"
+        super().__init__(self.message)
+
+
+class VersionSkipped(Exception):
+    """A search term contains blacklisted keywords"""
+
+    def __init__(self, query: str):
+        self.message = f"[Blacklisted] {query} skipped"
+        super().__init__(self.message)
+
+
+class YouTubeQuotaExceeded(Exception):
+    """The YouTube API quota has been exceeded"""
+
+    def __init__(self):
+        self.message = "The YouTube API quota has been exceeded"
+        super().__init__(self.message)
+
+
+class EmptySpotifyLikes(Exception):
+    """The YouTube API quota has been exceeded"""
+
+    def __init__(self):
+        self.message = "The YouTube API quota has been exceeded"
+        super().__init__(self.message)
+
+
+class InvalidSearchFormat(Exception):
+    """Invalid search query format"""
+
+    def __init__(self):
+        self.message = "Use format `Artist - Title` for search queries"
+        super().__init__(self.message)
+
+
+class YouTubeUnavailableError(RuntimeError):
+    """YouTube account features unavailable"""
+
+    pass
+
+
+class SpotifyUnavailableError(RuntimeError):
+    """Spotify search features unavailable"""
+
+    pass

spots_cli/models/helper_models.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spots_cli.models import YTVideoInfo
+
+
+@dataclass
+class ArtistAndTitle:
+    title: str
+    artist: str
+
+
+@dataclass
+class SearchResponseSingle:
+    result: YTVideoInfo
+    is_cached: bool
+
+
+@dataclass
+class SearchResponseMultiple:
+    result: list[YTVideoInfo]
+    is_cached: bool

spots_cli/models/media_resource.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spots_cli.models import PlaylistInfo, YTVideoInfo, Metadata
+
+
+@dataclass
+class MediaResourceSingle:
+    resource_type: Literal["single"]
+    metadata: Metadata
+    video_info: YTVideoInfo
+
+
+@dataclass
+class MediaResourcePlaylist:
+    resource_type: Literal["playlist"]
+    playlist_info: PlaylistInfo

spots_cli/models/metadata.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Metadata:
+    """Creates a metadata object
+
+    Args:
+        title (str): the songs title
+        artist (str): the artist(s)
+        link (str): the link of the song
+        cover (str, optional): the url for the cover image. Defaults to ""
+        tracknumber (str, optional): the song's position in an album. `position/album_length`. Defaults to ""
+        album (str, optional): the album name. Defaults to ""
+        lyrics (str, optional): the lyrics of the song. Defaults to ""
+        release_date (str | None, optional): the release date of the song. Defaults to None.
+        preview_url (str | None, optional): A link to a 30 second preview (MP3 format) of the track. Defaults to None.
+        artist_cover (str | None, optional): The artist's cover image. Defauls to None.
+        artist_id (str): The artist's id.
+    """
+
+    title: str
+    artist: str
+    link: str
+    artist_id: str
+    cover: str | None = ""
+    tracknumber: str | None = ""
+    album: str | None = ""
+    lyrics: str | None = ""
+    release_date: str | None = None
+    preview_url: str | None = None
+    artist_cover: str | None = None
+
+    @property
+    def full_title(self):
+        return f"{self.artist} - {self.title}"

spots_cli/models/metadata_provider.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, overload, Any
+
+if TYPE_CHECKING:
+    from spots_cli.models import Metadata
+    from spots_cli.bootstrap.container import Core, Clients
+
+
+class MetadataProvider(ABC):
+
+    @abstractmethod
+    def __init__(
+        self,
+        *,
+        core: Core,
+        clients: Clients,
+    ):
+        pass
+
+    @overload
+    def get(self, *, track_id: str, search_result: None = None) -> Metadata: ...
+
+    @overload
+    def get(
+        self, *, track_id: None = None, search_result: dict[str, Any]
+    ) -> Metadata: ...
+
+    @abstractmethod
+    def get(
+        self,
+        *,
+        track_id: str | None = None,
+        search_result: dict[str, Any] | None = None,
+    ) -> Metadata:
+        """
+        Retrieves metadata for a track
+
+        Arguments:
+            track_id (str, Optional): the track id to retrieve data from. None if search_result passed. Defaults to None.
+            search_result (dict[str, Any], Optional): Pre-fetched result data. None if track_id passed.Defaults to None.
+
+        Returns:
+            Metadata: an object with retrieved data
+
+        Raises:
+            SongNotFound: if spotify search results empty.
+            InvalidURL: if url invalid.
+            MetadataNotFound: if metadata not found for id.
+        """
+        pass