spots-cli 0.1.0__py3-none-any.whl

spots_cli/models/playlist_info.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spots_cli.models import Metadata, YTVideoInfo
+
+
+@dataclass
+class PlaylistInfo:
+    """
+    A playlist metadata object.
+
+    Args:
+        cover (str): The playlist cover image.
+        name (str): The playlist's name.
+        artist (str, Optional): The artist of the playlist (if album). Defaults to None.
+        provider_metadata (list[Metadata]): A list of provider metadata for the playlist.
+        youtube_metadata (list[YTVideoInfo]): A list youtube metadata for the playlist.
+    """
+
+    name: str
+    cover: str
+    provider_metadata: list[Metadata]
+    youtube_metadata: list[YTVideoInfo]
+    artist: str | None = None

spots_cli/models/search_provider.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spots_cli.bootstrap.container import Clients, Core
+    from spots_cli.models import Metadata, PlaylistInfo, MetadataProvider
+
+
+@dataclass
+class ArtistInfo:
+    name: str
+    cover: str
+    id: str
+
+
+class SearchProvider(ABC):
+    """Responsible for searching for query on a Media Provider"""
+
+    @abstractmethod
+    def __init__(
+        self,
+        *,
+        metadata: MetadataProvider,
+        clients: Clients,
+        core: Core,
+        fallback_providers: list[SearchProvider] = [],
+    ):
+        self.fallback_providers = fallback_providers
+        self.clients = clients
+        self.metadata = metadata
+
+    @abstractmethod
+    def search_artist(self, artist_query: str) -> ArtistInfo:
+        pass
+
+    @abstractmethod
+    def search_artist_top_tracks(self, *, artist_id: str) -> PlaylistInfo:
+        pass
+
+    @abstractmethod
+    def search_playlist(self, playlist_url: str) -> PlaylistInfo:
+        pass
+
+    @abstractmethod
+    def search_album(self, album_url: str) -> PlaylistInfo:
+        pass
+
+    @abstractmethod
+    def search_track(self, query: str) -> Metadata:
+        """Searches for a title on media provider
+
+        Args:
+            query (str): the title to be searched for
+
+        Raises:
+            SongNotFound: the `query` is not found.
+            TypeError: if query format not: `Artist - Title`
+
+        Returns:
+            Metadata: The metadata of the title.
+        """
+        pass

spots_cli/models/sentinel.py

@@ -0,0 +1,4 @@
+class Sentinel:
+    """Represents a missing song in cache"""
+
+    pass

spots_cli/models/yt_video_info.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spots_cli.models import ArtistAndTitle
+
+
+@dataclass
+class YTVideoInfo:
+    id: str
+    title: str
+    uploader: str
+    audio_ext: str
+    filesize: int
+
+    @property
+    def video_link(self):
+        return f"https://youtube.com.watch?v={self.id}"
+
+    @property
+    def full_title(self):
+        return f"{self.uploader} - {self.title}"
+
+    @full_title.setter
+    def full_title(self, artist_and_title: ArtistAndTitle):
+        self.uploader = artist_and_title.artist
+        self.title = artist_and_title.title

spots_cli/scripts/__init__.py

@@ -0,0 +1,2 @@
+from spots_cli.scripts.add_to_history import main as update_history
+from spots_cli.scripts.duplicate_songs_remover import main as remove_duplicate_songs

spots_cli/scripts/add_to_history.py

@@ -0,0 +1,45 @@
+"""Recursively adds user's downloaded songs to spots history file"""
+
+from mutagen.id3 import ID3
+from mutagen.mp3 import MP3, HeaderNotFoundError
+from os import listdir, path, getcwd
+
+from spots_cli.utils import get_config_path
+
+history_file = get_config_path() / ".spots_download_history.txt"
+
+
+def update_history(file_path):
+    """Update history file with song information"""
+    try:
+        song = MP3(file_path, ID3)
+        artist = song.get("TPE1", "")
+        artist = f"{artist} - " if artist else ""
+        title = song.get("TIT2", "")
+        song_name = f"{artist}{title}"
+        if title:
+            with open(history_file, "a", newline="") as history:
+                history.write(f"{song_name}\n")
+    except (HeaderNotFoundError, KeyError):
+        pass
+
+
+def process_directory(directory):
+    """Process all MP3 files in a directory"""
+    for item in listdir(directory):
+        item_path = path.join(directory, item)
+        if path.isdir(item_path):
+            process_directory(item_path)  # Recursively process subdirectories
+        elif item_path.lower().endswith(".mp3"):
+            update_history(item_path)
+
+
+def main(folder):
+    if path.exists(folder):
+        print("Updating Spots downloads history...")
+
+        process_directory(folder)
+
+        print("Spots downloads history updated!")
+    else:
+        print("Folder not found.")

spots_cli/scripts/bootstrap.py

@@ -0,0 +1,92 @@
+import os
+import sys
+import subprocess
+import shutil
+from pathlib import Path
+
+ENV_NAME = "venv"
+
+
+def run(cmd, env=None):
+    """Run a shell command and stream output."""
+    print(f"\n>> {' '.join(cmd)}")
+    subprocess.check_call(cmd, env=env)
+
+
+def get_venv_paths(env_name):
+    """Return platform-specific paths."""
+    if os.name == "nt":
+        python_path = Path(env_name) / "Scripts" / "python.exe"
+        pip_path = Path(env_name) / "Scripts" / "pip.exe"
+    else:
+        python_path = Path(env_name) / "bin" / "python"
+        pip_path = Path(env_name) / "bin" / "pip"
+
+    return python_path, pip_path
+
+
+def create_venv(env_name, recreate=False):
+    """Create or recreate virtual environment."""
+    if Path(env_name).exists():
+        if recreate:
+            print(f"Removing existing venv: {env_name}")
+            shutil.rmtree(env_name)
+        else:
+            print(f"Venv already exists: {env_name}")
+            return
+
+    print(f"Creating virtual environment: {env_name}")
+    run([sys.executable, "-m", "venv", env_name])
+
+
+def install_dependencies(pip_path):
+    """Install dependencies."""
+    # Upgrade pip first
+    run([str(pip_path), "install", "--upgrade", "pip", "setuptools", "wheel"])
+
+    # Install from requirements.txt if present
+    if Path("requirements.txt").exists():
+        print("Installing from requirements.txt...")
+        run([str(pip_path), "install", "-r", "requirements.txt"])
+    else:
+        print("No requirements.txt found, skipping.")
+
+
+def install_current_package(pip_path):
+    """Install current project (useful for PyPI-style projects)."""
+    if Path("pyproject.toml").exists() or Path("setup.py").exists():
+        print("Installing current package...")
+        run([str(pip_path), "install", "-e", "."])
+    else:
+        print("No project file found (pyproject.toml/setup.py), skipping.")
+
+
+def main():
+    recreate = "--recreate" in sys.argv
+
+    print("🚀 Python environment bootstrap")
+
+    create_venv(ENV_NAME, recreate=recreate)
+
+    python_path, pip_path = get_venv_paths(ENV_NAME)
+
+    if not python_path.exists():
+        print("❌ Failed to locate venv Python executable")
+        sys.exit(1)
+
+    install_dependencies(pip_path)
+    install_current_package(pip_path)
+
+    print("\n✅ Setup complete!")
+
+    if os.name == "nt":
+        activate_cmd = f"{ENV_NAME}\\Scripts\\activate"
+    else:
+        activate_cmd = f"source {ENV_NAME}/bin/activate"
+
+    print(f"\n👉 To activate the environment:\n{activate_cmd}")
+    print(f"\n👉 Or run directly:\n{python_path} your_script.py")
+
+
+if __name__ == "__main__":
+    main()

spots_cli/scripts/duplicate_songs_remover.py

@@ -0,0 +1,54 @@
+"""Removes all duplicate mp3 files"""
+
+from os import listdir, path, getcwd, remove
+from sys import argv
+from mutagen.id3 import ID3
+from mutagen.mp3 import MP3, HeaderNotFoundError
+
+original_songs: dict[str, str] = {}
+
+i = 0
+
+
+def process_song(file_path: str):
+    """Removes a song if it is a duplicate"""
+    try:
+        song = MP3(file_path, ID3)
+        artist = song.get("TPE1", "")
+        artist = f"{artist} - " if artist else ""
+        title = song.get("TIT2", "")
+        song_name = f"{artist}{title}"
+
+        original = original_songs.get(song_name)
+        if original:
+            remove(file_path)
+        else:
+            original_songs[song_name] = file_path
+    except (HeaderNotFoundError, KeyError):
+        pass
+
+
+def process_directory(directory: str):
+    """Process all MP3 files in a directory"""
+    contents = listdir(directory)
+    contents.sort(reverse=True)
+
+    for item in contents:
+        print(f"[{globals()['i']}] Scanning: {item}")
+        globals()["i"] += 1
+        item_path = path.join(directory, item)
+        if path.isdir(item_path):
+            process_directory(item_path)  # Recursively process subdirectories
+        elif item_path.lower().endswith(".mp3"):
+            process_song(item_path)
+
+
+def main(folder: str):
+    if path.exists(folder):
+        print("Searching for duplicate songs...")
+
+        process_directory(folder)
+
+        print("Duplicate songs removed!")
+    else:
+        print("Folder not found.")

spots_cli/services/__init__.py

@@ -0,0 +1,8 @@
+from spots_cli.services.youtube_metadata_service import YouTubeMetadataService
+from spots_cli.services.youtube_search_service import YoutubeSearchService
+from spots_cli.services.providers_metadata import ProvidersMetadata
+from spots_cli.services.provider_search_container import ProviderSearchContainer
+from spots_cli.services.deezer_search_service import DeezerSearchService
+from spots_cli.services.deezer_metadata_service import DeezerMetadataService
+from spots_cli.services.spotify_search_service import SpotifySearchService
+from spots_cli.services.spotify_metadata_service import SpotifyMetadataService

spots_cli/services/deezer_metadata_service.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from logging import getLogger
+from typing import Any, cast, overload, TYPE_CHECKING
+
+from spots_cli.models import SongNotFound, Metadata, Sentinel, MetadataProvider
+from spots_cli.utils import fetch_data, FetchResponseFailure, FetchResponseSuccess
+
+if TYPE_CHECKING:
+    from spots_cli.bootstrap.container import Clients, Core
+
+
+logger = getLogger(__name__)
+
+
+class DeezerMetadataService(MetadataProvider):
+    def __init__(
+        self,
+        *,
+        clients: Clients,
+        core: Core,
+    ):
+        self.clients = clients
+        self.core = core
+
+    @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: ...
+
+    def get(
+        self,
+        *,
+        track_id: str | None = None,
+        search_result: dict[str, Any] | None = None,
+    ) -> Metadata:
+        logger.debug("Searching for metadata on Deezer...")
+
+        if track_id is not None:
+            query_id = track_id
+        elif search_result is not None:
+            query_id = search_result["id"]
+        else:
+            raise ValueError("Either track_id or search_result must be provided")
+
+        # check cache first
+        url = "https://open.deezer.com/track/" + query_id
+        cache = self.core.storage.get(query=url, query_type="metadata")
+        if isinstance(cache, Sentinel):
+            raise SongNotFound(query_id)
+        elif isinstance(cache, Metadata):
+            return cache
+
+        # search song if id provided
+        if track_id is not None:
+            # retrieve track from deezer
+            uri = f"https://api.deezer.com/track/{track_id}"
+            track_res = fetch_data(uri)
+
+            if isinstance(track_res, FetchResponseFailure):
+                track_res = cast(FetchResponseFailure, track_res)
+                error_msg = track_res.error
+
+                if error_msg == "no data":
+                    raise SongNotFound(f"Id {track_id}")
+                else:
+                    raise Exception(f"Unknown error occurred: {error_msg}")
+
+            track_res = cast(FetchResponseSuccess, track_res)
+            track = cast(dict[str, Any], track_res.data)
+        elif search_result is not None:
+            track = search_result
+        else:
+            raise ValueError("Either track_id or search_result must be provided")
+
+        album_info = track["album"]
+        album_name = album_info["title"]
+        cover = album_info["cover_xl"]
+
+        artist_info = track["artist"]
+        artist_name = artist_info["name"]
+        track_name = track["title"]
+
+        # get track lyrics
+        try:
+            lyrics = self.core.lyrics.get_lyrics(title=track_name, artist=artist_name)
+        except Exception as e:
+            logger.error(f"Error occurred while searching for lyrics", e)
+            lyrics = ""
+
+        metadata = Metadata(
+            title=track_name,
+            artist=artist_name,
+            link=track["link"],
+            release_date=track["release_date"],
+            tracknumber=str(track["track_position"]),
+            cover=cover,
+            lyrics=lyrics,
+            album=album_name,
+            preview_url=track["preview"],
+            artist_cover=artist_info["picture"],
+            artist_id=artist_info["id"],
+        )
+        self.core.storage.new(query=url, result=metadata, query_type="metadata")
+        return metadata

spots_cli/services/deezer_search_service.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from logging import getLogger
+from typing import Any, TypedDict, cast, TYPE_CHECKING
+
+from spots_cli.models import (
+    Metadata,
+    SearchProvider,
+    PlaylistInfo,
+    ArtistInfo,
+    MetadataProvider,
+    SongNotFound,
+    Sentinel,
+    InvalidSearchFormat,
+)
+from spots_cli.utils import search_fallbacks
+
+if TYPE_CHECKING:
+    from spots_cli.bootstrap.container import Clients, Core
+    from spots_cli.models import SearchProvider
+
+
+logger = getLogger(__name__)
+
+
+class DeezerResponseBase(TypedDict):
+    total: int
+    data: list[dict[str, Any]]
+
+
+class DeezerSearchService(SearchProvider):
+    def __init__(
+        self,
+        *,
+        metadata: MetadataProvider,
+        clients: Clients,
+        core: Core,
+        fallback_providers: list[SearchProvider] = [],
+    ):
+        self.fallback_providers = fallback_providers
+        self.clients = clients
+        self.core = core
+        self.metadata = metadata
+
+    def search_album(self, album_url: str) -> PlaylistInfo:
+        album_data = self.clients.deezer._get_resource_by_url(album_url)
+
+        album_metadata = [
+            self.metadata.get(search_result=result) for result in album_data["tracks"]
+        ]
+        artist_name = album_data["artist"]["name"]
+        return PlaylistInfo(
+            name=album_data["title"],
+            cover=album_data["cover"],
+            provider_metadata=album_metadata,
+            youtube_metadata=[],
+            artist=artist_name,
+        )
+
+    def search_playlist(self, playlist_url: str) -> PlaylistInfo:
+        playlist_data = self.clients.deezer._get_resource_by_url(playlist_url)
+
+        playlist_metadata = [
+            self.metadata.get(search_result=result)
+            for result in playlist_data["tracks"]
+        ]
+        return PlaylistInfo(
+            name=playlist_data["title"],
+            cover=playlist_data["picture"],
+            provider_metadata=playlist_metadata,
+            youtube_metadata=[],
+        )
+
+    def search_artist(self, artist_query: str) -> ArtistInfo:
+        # deezer provides a list of search results
+        # so we use the first result
+        metadata = self.search_track(artist_query)
+
+        cover = cast(str, metadata.artist_cover)
+        return ArtistInfo(name=metadata.artist, cover=cover, id=metadata.artist_id)
+
+    def search_artist_top_tracks(self, *, artist_id: str) -> PlaylistInfo:
+        try:
+            artist_id_int = int(artist_id)
+        except ValueError:
+            raise TypeError("Number ids required")
+
+        artist_info, top_tracks = self.clients.deezer.artist_top_tracks(artist_id_int)
+
+        # get metadata for each top track
+        top_tracks_playlist = [
+            self.metadata.get(track_id=top_track["id"]) for top_track in top_tracks
+        ]
+
+        return PlaylistInfo(
+            cover=artist_info.cover,
+            name="Top Tracks",
+            artist=artist_info.name,
+            provider_metadata=top_tracks_playlist,
+            youtube_metadata=[],
+        )
+
+    def search_track(self, query: str) -> Metadata:
+        query = query.replace("–", "-")  # `–` != `-`
+
+        if "-" not in query:
+            error_txt = "Search format: `Artist` - `Title`"
+            logger.error(error_txt)
+            raise InvalidSearchFormat()
+
+        cache = self.core.storage.get(query=query, query_type="metadata")
+
+        if isinstance(cache, Sentinel):
+            raise SongNotFound(query)
+        elif isinstance(cache, Metadata):
+            return cache
+        else:
+            try:
+                track_id = self.clients.deezer.search(query)
+                metadata = self.metadata.get(track_id=track_id)
+                self.core.storage.new(
+                    query=query, result=metadata, query_type="metadata"
+                )
+                return metadata
+            except SongNotFound:
+                metadata = search_fallbacks(
+                    query=query, providers=self.fallback_providers
+                )
+                self.core.storage.new(
+                    query=query, result=metadata, query_type="metadata"
+                )
+                return metadata

spots_cli/services/provider_search_container.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spots_cli.bootstrap.container import Clients, Core
+    from spots_cli.models import SearchProvider, MetadataProvider
+
+
+class ProviderSearchContainer:
+    def __init__(self, clients: Clients, metadata: MetadataProvider, core: Core):
+        from spots_cli.services import DeezerSearchService, SpotifySearchService
+
+        # Define all possible providers with availability checks
+        provider_registry: dict[str, tuple[type[SearchProvider], bool]] = {
+            "deezer": (DeezerSearchService, True),  # always available
+            "spotify": (
+                SpotifySearchService,
+                bool(clients.spotify),  # availability check
+            ),
+        }
+
+        # Filter only available providers
+        available_providers = {
+            name: cls
+            for name, (cls, is_available) in provider_registry.items()
+            if is_available
+        }
+
+        if not available_providers:
+            raise RuntimeError("No search providers available")
+
+        # Resolve default provider safely
+        default_provider = clients.secrets.read(key="main_provider", alt="deezer")
+
+        if default_provider not in available_providers:
+            # fallback to first available provider
+            default_provider = next(iter(available_providers))
+
+        provider_cls = available_providers[default_provider]
+
+        # Remove main from fallback pool
+        fallback_classes = {
+            name: cls
+            for name, cls in available_providers.items()
+            if name != default_provider
+        }
+
+        # Instantiate fallback providers
+        fallback_providers = [
+            cls(metadata=metadata, clients=clients, core=core)
+            for cls in fallback_classes.values()
+        ]
+
+        # Wire fallbacks (optional, depending on your design)
+        for provider in fallback_providers:
+            provider.fallback_providers = fallback_providers
+
+        # Instantiate main provider
+        self.main = provider_cls(
+            metadata=metadata,
+            clients=clients,
+            core=core,
+            fallback_providers=fallback_providers,
+        )
+
+        self.fallbacks = fallback_providers

spots_cli/services/providers_metadata.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from spots_cli.models import MetadataProvider
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from spots_cli.bootstrap.container import Clients, Core
+
+
+class ProvidersMetadata:
+    def __init__(self, *, clients: Clients, core: Core):
+        from spots_cli.services import DeezerMetadataService, SpotifyMetadataService
+
+        media_providers: dict[str, type[MetadataProvider]] = {
+            "deezer": DeezerMetadataService,
+            "spotify": SpotifyMetadataService,
+        }
+
+        default_provider = clients.secrets.read(key="main_provider", alt="deezer")
+
+        provider_cls = media_providers[default_provider]
+        self.metadata = provider_cls(core=core, clients=clients)