spots-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{spots_cli-0.2.0 → spots_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spots_cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: Spots is a modular music coordination library that unifies multiple providers (e.g. Deezer, Spotify, YouTube) into a single, consistent interface.
 Project-URL: Homepage, https://github.com/mdesignscode/spots_flask
 Project-URL: Issues, https://github.com/mdesignscode/spots_flask

{spots_cli-0.2.0 → spots_cli-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "spots_cli"
-version = "0.2.0"
+version = "0.2.2"
 authors = [
   { name="Marlon Baatjes", email="marlonbaatjes62@gmail.com" }
 ]

{spots_cli-0.2.0 → spots_cli-0.2.2}/src/spots_cli/app/domain_resolver.py

@@ -8,6 +8,7 @@ from spots_cli.models import Metadata, SongNotFound, Sentinel, YTVideoInfo
 
 if TYPE_CHECKING:
     from spots_cli.bootstrap.container import Core
+    from spots_cli.core import YouTubeExtractor
     from spots_cli.models import SearchProvider
     from spots_cli.services import YoutubeSearchService
 
@@ -27,8 +28,9 @@ class ResolvedDomainResult:
     youtube: YTVideoInfo
 
 
-def _fallback_metadata(video: YTVideoInfo) -> Metadata:
-    """Builds a bare-bones Metadata object straight from a YouTube result.
+def fallback_metadata(video: YTVideoInfo, extractor: YouTubeExtractor) -> Metadata:
+    """Builds a bare-bones Metadata object straight from a YouTube result,
+    with the artist and title cleaned of video noise like "(Official Video)".
 
     Used when no provider (Spotify/Deezer) has metadata for a track, or the
     provider's result doesn't match. The provider is only used to prettify
@@ -36,11 +38,13 @@ def _fallback_metadata(video: YTVideoInfo) -> Metadata:
     from YouTube, so a missing/mismatched provider entry should never cause
     a track to be dropped as long as it exists on YouTube.
     """
+    cleaned = extractor.clean_artist_and_title(video.uploader, video.title)
     return Metadata(
-        title=video.title,
-        artist=video.uploader,
+        title=cleaned.title or video.title,
+        artist=cleaned.artist or video.uploader,
         link=video.video_link,
         artist_id="",
+        is_fallback=True,
     )
 
 
@@ -96,7 +100,7 @@ class DomainResolver:
                         f"No provider metadata for '{video_title}', "
                         "falling back to YouTube-derived metadata"
                     )
-                    fallback = _fallback_metadata(video)
+                    fallback = fallback_metadata(video, self.core.extractor)
                     self.core.storage.new(
                         query=video_title, result=fallback, query_type="metadata"
                     )
@@ -117,7 +121,7 @@ class DomainResolver:
                         f"Provider metadata for '{video_title}' didn't match, "
                         "falling back to YouTube-derived metadata"
                     )
-                    fallback = _fallback_metadata(video)
+                    fallback = fallback_metadata(video, self.core.extractor)
                     self.core.storage.new(
                         query=video_title, result=fallback, query_type="metadata"
                     )

{spots_cli-0.2.0 → spots_cli-0.2.2}/src/spots_cli/app/media_resolver.py

@@ -4,10 +4,12 @@ from logging import getLogger
 from tenacity import stop_after_delay
 from typing import TYPE_CHECKING, Any, cast
 
+from spots_cli.app.domain_resolver import fallback_metadata
 from spots_cli.engine import retry
 from spots_cli.models import (
     InvalidURL,
     SongNotFound,
+    SpotifyUnavailableError,
     MediaResourceSingle,
     MediaResourcePlaylist,
     PlaylistInfo,
@@ -50,6 +52,13 @@ class MediaResolver:
         """
         # process spotify link
         if "spotify" in url:
+            # a Spotify id means nothing to the other providers
+            if not self.clients.spotify:
+                raise SpotifyUnavailableError(
+                    "Spotify links need Spotify turned on. Run `spots_cli setup` "
+                    "and enable Spotify, or paste the YouTube link instead."
+                )
+
             # single
             if "track" in url:
                 # retrieve Provider data
@@ -187,40 +196,35 @@ class MediaResolver:
                 yt_title = self.core.extractor.build_search_query(
                     video_info.result.uploader, video_info.result.title
                 )
+                # the user picked this video, so it is downloaded either way;
+                # the provider only adds tags (cover, album, lyrics)
                 try:
                     metadata = self.domain.provider_search.search_track(
                         yt_title)
                 except SongNotFound:
-                    self.core.storage.new(
-                        query=yt_title, result=Sentinel(), query_type="metadata"
-                    )
-                    self.core.storage.new(
-                        query=yt_title, result=Sentinel(), query_type="youtube"
-                    )
-                    raise
+                    metadata = None
 
-                tracks_match = self.core.matcher.match_tracks(
+                if metadata is None or not self.core.matcher.match_tracks(
                     metadata=metadata, video_info=video_info.result
-                )
-                if not tracks_match:
-                    self.core.storage.new(
-                        query=yt_title, result=Sentinel(), query_type="metadata"
+                ):
+                    logger.debug(
+                        f"No matching provider metadata for '{yt_title}', "
+                        "falling back to YouTube-derived metadata"
                     )
-                    self.core.storage.new(
-                        query=yt_title, result=Sentinel(), query_type="youtube"
-                    )
-                    raise SongNotFound(yt_title)
-                else:
-                    self.core.storage.new(
-                        query=yt_title, result=metadata, query_type="metadata"
-                    )
-                    self.core.storage.new(
-                        query=yt_title, result=video_info.result, query_type="youtube"
-                    )
-                    return MediaResourceSingle(
-                        resource_type="single",
-                        metadata=metadata,
-                        video_info=video_info.result,
+                    metadata = fallback_metadata(
+                        video_info.result, self.core.extractor
                     )
+
+                self.core.storage.new(
+                    query=yt_title, result=metadata, query_type="metadata"
+                )
+                self.core.storage.new(
+                    query=yt_title, result=video_info.result, query_type="youtube"
+                )
+                return MediaResourceSingle(
+                    resource_type="single",
+                    metadata=metadata,
+                    video_info=video_info.result,
+                )
         else:
             raise InvalidURL(url)

{spots_cli-0.2.0 → spots_cli-0.2.2}/src/spots_cli/core/pattern_matcher.py

@@ -141,8 +141,13 @@ class PatternMatcher:
         self.extractor = extractor
 
     def match_tracks(self, *, video_info: YTVideoInfo, metadata: Metadata) -> bool:
-        yt_artist = video_info.uploader or ""
-        yt_title = video_info.title or ""
+        # compare the song, not the raw upload: "Tyla - Water (Official
+        # Music Video)" by Tyla is the song "Water" by "Tyla"
+        cleaned = self.extractor.extract_artist_and_title(
+            video_info=video_info, metadata=metadata
+        )
+        yt_artist = cleaned.artist or video_info.uploader or ""
+        yt_title = cleaned.title or video_info.title or ""
 
         sp_artist = metadata.artist or ""
         sp_title = metadata.title or ""
@@ -164,7 +169,7 @@ class PatternMatcher:
         title_score = token_similarity(yt_title_tokens, sp_title_tokens)
         artist_score = token_similarity(yt_artist_tokens, sp_artist_tokens)
 
-        penalty = uploader_penalty(yt_artist)
+        penalty = uploader_penalty(video_info.uploader or "")
 
         final_score = 0.6 * title_score + 0.3 * artist_score - penalty
 

{spots_cli-0.2.0 → spots_cli-0.2.2}/src/spots_cli/core/youtube_extractor.py

@@ -166,15 +166,15 @@ class YouTubeExtractor:
             artist=youtube_artist.strip(), title=youtube_title.strip()
         )
 
-    def build_search_query(self, uploader: str, title: str) -> str:
-        """Cleans noisy YouTube uploader/title fields into a search-friendly
-        'Artist - Title' string for provider lookups (Deezer/Spotify).
+    def clean_artist_and_title(self, uploader: str, title: str) -> ArtistAndTitle:
+        """Cleans noisy YouTube uploader/title fields into an artist and a title.
 
-        Strips common suffixes like "(Official Video)" and de-duplicates the
-        uploader name when it's already repeated at the start of the title:
+        Strips common suffixes like "(Official Video)" and a trailing "VEVO",
+        and de-duplicates the uploader name when it's already repeated at the
+        start of the title:
 
             uploader="Tinashe", title="Tinashe - Needs (Official Video)"
-            -> "Tinashe - Needs"
+            -> artist="Tinashe", title="Needs"
         """
         uploader = self.remove_odd_keywords((uploader or "").strip())
         uploader = sub(r"vevo$", "", uploader, flags=IGNORECASE).strip()
@@ -192,4 +192,9 @@ class YouTubeExtractor:
             if deduped_title:
                 title = deduped_title
 
-        return f"{uploader} - {title}".strip(" -")
+        return ArtistAndTitle(artist=uploader, title=title)
+
+    def build_search_query(self, uploader: str, title: str) -> str:
+        """The cleaned 'Artist - Title' string for provider lookups (Deezer/Spotify)."""
+        cleaned = self.clean_artist_and_title(uploader, title)
+        return f"{cleaned.artist} - {cleaned.title}".strip(" -")

{spots_cli-0.2.0 → spots_cli-0.2.2}/src/spots_cli/engine/retry.py

@@ -1,18 +1,31 @@
 from tenacity import retry as _retry
 from tenacity import retry_if_exception
 
-from spots_cli.models import SongNotFound
+from spots_cli.models import (
+    InvalidURL,
+    SongNotFound,
+    SpotifyUnavailableError,
+    YouTubeUnavailableError,
+)
+
+# not transient: retrying can't change the answer
+PERMANENT_ERRORS = (
+    InvalidURL,
+    SongNotFound,
+    SpotifyUnavailableError,
+    YouTubeUnavailableError,
+)
 
 
 def is_retryable_exception(exc: BaseException) -> bool:
     # Only retry transient failures
-    return not isinstance(exc, SongNotFound)
+    return not isinstance(exc, PERMANENT_ERRORS)
 
 
 def retry(*args, **kwargs):
     """
     Project-wide retry decorator.
-    - Never retries SongNotFound
+    - Never retries PERMANENT_ERRORS
     - Always re-raises the final exception
     """
 

{spots_cli-0.2.0 → spots_cli-0.2.2}/src/spots_cli/models/metadata.py

@@ -17,6 +17,7 @@ class Metadata:
         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.
+        is_fallback (bool): True when no provider had this song, so the tags come from the YouTube title. Defaults to False.
     """
 
     title: str
@@ -30,6 +31,7 @@ class Metadata:
     release_date: str | None = None
     preview_url: str | None = None
     artist_cover: str | None = None
+    is_fallback: bool = False
 
     @property
     def full_title(self):

spots_cli-0.2.2/tests/app/test_media_resolver.py

@@ -0,0 +1,95 @@
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+
+from spots_cli.app.media_resolver import MediaResolver
+from spots_cli.core.pattern_matcher import PatternMatcher
+from spots_cli.core.youtube_extractor import YouTubeExtractor
+from spots_cli.models import Metadata, SongNotFound, SpotifyUnavailableError, YTVideoInfo
+
+LINK = "https://www.youtube.com/watch?v=XoiOOiuH8iI"
+
+
+@pytest.fixture
+def upload() -> YTVideoInfo:
+    return YTVideoInfo(
+        id="XoiOOiuH8iI",
+        title="Tyla - Water (Official Music Video)",
+        uploader="Tyla",
+        audio_ext="webm",
+        filesize=4,
+    )
+
+
+def build_resolver(upload, *, provider_result=None, provider_error=None, spotify=None):
+    extractor = YouTubeExtractor()
+    core = Mock(extractor=extractor, matcher=PatternMatcher(extractor=extractor))
+    domain = Mock()
+    domain.youtube_search.video_search.return_value = SimpleNamespace(
+        is_cached=False, result=upload
+    )
+    if provider_error:
+        domain.provider_search.search_track.side_effect = provider_error
+    else:
+        domain.provider_search.search_track.return_value = provider_result
+    clients = Mock(spotify=spotify)
+    return MediaResolver(core=core, domain=domain, clients=clients, domain_resolver=Mock())
+
+
+def song(title: str, artist: str) -> Metadata:
+    return Metadata(title=title, artist=artist, link="", artist_id="", album=title)
+
+
+def test_youtube_link_uses_matching_provider_metadata(upload):
+    resolver = build_resolver(upload, provider_result=song("Water", "Tyla"))
+
+    resource = resolver.resolve(url=LINK)
+
+    assert resource.metadata.album == "Water"
+    assert not resource.metadata.is_fallback
+    assert resource.video_info is upload
+
+
+def test_youtube_link_without_provider_metadata_still_resolves(upload):
+    resolver = build_resolver(upload, provider_error=SongNotFound("Tyla - Water"))
+
+    resource = resolver.resolve(url=LINK)
+
+    assert resource.metadata.is_fallback
+    assert resource.metadata.artist == "Tyla"
+    assert resource.video_info is upload
+
+
+def test_youtube_link_with_mismatched_provider_metadata_falls_back(upload):
+    resolver = build_resolver(upload, provider_result=song("Truth or Dare", "Tyla"))
+
+    resource = resolver.resolve(url=LINK)
+
+    assert resource.metadata.is_fallback
+    assert resource.metadata.title != "Truth or Dare"
+
+
+def test_spotify_link_needs_spotify_turned_on(upload):
+    resolver = build_resolver(upload)
+
+    with pytest.raises(SpotifyUnavailableError, match="spots_cli setup"):
+        resolver.resolve(url="https://open.spotify.com/track/5aIVCx5tnk0ntmdiinnYvw")
+
+    # not retried, and the Spotify id never reaches another provider
+    resolver.domain.provider_metadata.get.assert_not_called()
+
+
+def test_fallback_tags_drop_the_repeated_artist_and_video_tags():
+    upload = YTVideoInfo(
+        id="kSBQZH3dkZ8",
+        title="Tyla - THAT GIRL (Biuro Version) (Official Video)",
+        uploader="TylaVEVO",
+        audio_ext="webm",
+        filesize=4,
+    )
+    resolver = build_resolver(upload, provider_error=SongNotFound("Tyla - THAT GIRL"))
+
+    metadata = resolver.resolve(url=LINK).metadata
+
+    assert (metadata.artist, metadata.title) == ("Tyla", "THAT GIRL (Biuro Version)")

spots_cli-0.2.2/tests/core/test_pattern_matcher.py

@@ -0,0 +1,52 @@
+import pytest
+
+from spots_cli.core.pattern_matcher import PatternMatcher
+from spots_cli.core.youtube_extractor import YouTubeExtractor
+from spots_cli.models import Metadata, YTVideoInfo
+
+
+@pytest.fixture
+def matcher() -> PatternMatcher:
+    return PatternMatcher(extractor=YouTubeExtractor())
+
+
+def song(title: str, artist: str) -> Metadata:
+    return Metadata(title=title, artist=artist, link="", artist_id="")
+
+
+def video(title: str, uploader: str) -> YTVideoInfo:
+    return YTVideoInfo(id="x", title=title, uploader=uploader, audio_ext="webm", filesize=4)
+
+
+@pytest.mark.parametrize(
+    "title, uploader",
+    [
+        ("Tyla - Water (Official Music Video)", "Tyla"),
+        ("Tyla - Water (Official Audio)", "Tyla"),
+        ("Tyla - Water", "LatinHype"),
+        ("Water", "Tyla"),
+    ],
+)
+def test_matches_raw_youtube_titles(matcher, title, uploader):
+    assert matcher.match_tracks(video_info=video(title, uploader), metadata=song("Water", "Tyla"))
+
+
+def test_rejects_a_different_song_by_the_same_artist(matcher):
+    raw = video("Tyla - Truth or Dare (Official Video)", "Tyla")
+    assert not matcher.match_tracks(video_info=raw, metadata=song("Water", "Tyla"))
+
+
+def test_does_not_change_the_video(matcher):
+    raw = video("Tyla - Water (Official Music Video)", "Tyla")
+    matcher.match_tracks(video_info=raw, metadata=song("Water", "Tyla"))
+    assert (raw.title, raw.uploader) == ("Tyla - Water (Official Music Video)", "Tyla")
+
+
+def test_song_named_after_the_artist(matcher):
+    raw = video("Tyla - Tyla (Official Video)", "Tyla")
+    assert matcher.match_tracks(video_info=raw, metadata=song("Tyla", "Tyla"))
+
+
+def test_karaoke_channels_are_still_penalised(matcher):
+    raw = video("Tyla - Water (Karaoke Version)", "Sing King Karaoke")
+    assert not matcher.match_tracks(video_info=raw, metadata=song("Water", "Tyla"))