Fix breaking changes from Spotify API February 2026 update

- Rename playlist item key from 'track' to 'item'
- Update fields param, use playlist_items instead of playlist_tracks
- Deprecate isrc_match
- Add unittests

Author: beberry

src/spotify_to_tidal/sync.py

@@ -4,7 +4,6 @@
 from .cache import failure_cache, track_match_cache
 import datetime
 from difflib import SequenceMatcher
-from functools import partial
 from typing import Callable, List, Sequence, Set, Mapping
 import math
 import requests
@@ -17,7 +16,6 @@
 from tqdm import tqdm
 import traceback
 import unicodedata
-import math
 
 from .type import spotify as t_spotify
 
@@ -28,8 +26,11 @@ def simple(input_string: str) -> str:
     # only take the first part of a string before any hyphens or brackets to account for different versions
     return input_string.split('-')[0].strip().split('(')[0].strip().split('[')[0].strip()
 
-def isrc_match(tidal_track: tidalapi.Track, spotify_track) -> bool:
-    if "isrc" in spotify_track["external_ids"]:
+def deprecated_isrc_match(tidal_track: tidalapi.Track, spotify_track) -> bool:
+    """Spotify has deprecated the external_ids attribute and it will not be
+    returned to clients past 03/09/2026. This method can be removed past this
+    date."""
+    if "isrc" in spotify_track.get("external_ids", {}):
         return tidal_track.isrc == spotify_track["external_ids"]["isrc"]
     return False
 
@@ -89,7 +90,7 @@ def get_spotify_artists(spotify, do_normalize=False) -> Set[str]:
 
 def match(tidal_track, spotify_track) -> bool:
     if not spotify_track['id']: return False
-    return isrc_match(tidal_track, spotify_track) or (
+    return deprecated_isrc_match(tidal_track, spotify_track) or (
         duration_match(tidal_track, spotify_track)
         and name_match(tidal_track, spotify_track)
         and artist_match(tidal_track, spotify_track)
@@ -161,7 +162,7 @@ async def repeat_on_request_error(function, *args, remaining=5, **kwargs):
 async def _fetch_all_from_spotify_in_chunks(fetch_function: Callable) -> List[dict]:
     output = []
     results = fetch_function(0)
-    output.extend([item['track'] for item in results['items'] if item['track'] is not None])
+    output.extend([item['item'] for item in results['items'] if item['item']['type'] == 'track'])
 
     # Get all the remaining tracks in parallel
     if results['next']:
@@ -171,15 +172,15 @@ async def _fetch_all_from_spotify_in_chunks(fetch_function: Callable) -> List[di
             desc="Fetching additional data chunks"
         )
         for extra_result in extra_results:
-            output.extend([item['track'] for item in extra_result['items'] if item['track'] is not None])
+            output.extend([item['item'] for item in extra_result['items'] if item['item']['type'] == 'track'])
 
     return output
 
 
 async def get_tracks_from_spotify_playlist(spotify_session: spotipy.Spotify, spotify_playlist):
     def _get_tracks_from_spotify_playlist(offset: int, playlist_id: str):
-        fields = "next,total,limit,items(track(name,album(name,artists),artists,track_number,duration_ms,id,external_ids(isrc))),type"
-        return spotify_session.playlist_tracks(playlist_id=playlist_id, fields=fields, offset=offset)
+        fields = "next,total,limit,items(item(name,album(name,artists),artists,track_number,duration_ms,id,external_ids(isrc))),type"
+        return spotify_session.playlist_items(playlist_id=playlist_id, fields=fields, offset=offset)
 
     print(f"Loading tracks from Spotify playlist '{spotify_playlist['name']}'")
     items = await repeat_on_request_error( _fetch_all_from_spotify_in_chunks, lambda offset: _get_tracks_from_spotify_playlist(offset=offset, playlist_id=spotify_playlist["id"]))
@@ -239,7 +240,7 @@ def get_tracks_for_new_tidal_playlist(spotify_tracks: Sequence[t_spotify.Spotify
             if tidal_id in seen_tracks:
                 track_name = spotify_track['name']
                 artist_names = ', '.join([artist['name'] for artist in spotify_track['artists']])
-                print(f'Duplicate found: Track "{track_name}" by {artist_names} will be ignored') 
+                print(f'Duplicate found: Track "{track_name}" by {artist_names} will be ignored')
             else:
                 output.append(tidal_id)
                 seen_tracks.add(tidal_id)
@@ -287,7 +288,7 @@ async def _run_rate_limiter(semaphore):
         for song in song404:
             file.write(f"{song}\n")
 
-            
+
 async def sync_playlist(spotify_session: spotipy.Spotify, tidal_session: tidalapi.Session, spotify_playlist, tidal_playlist: tidalapi.Playlist | None, config: dict):
     """ sync given playlist to tidal """
     # Get the tracks from both Spotify and Tidal, creating a new Tidal playlist if necessary
@@ -321,7 +322,7 @@ async def sync_playlist(spotify_session: spotipy.Spotify, tidal_session: tidalap
 async def sync_favorites(spotify_session: spotipy.Spotify, tidal_session: tidalapi.Session, config: dict):
     """ sync user favorites to tidal """
     async def get_tracks_from_spotify_favorites() -> List[dict]:
-        _get_favorite_tracks = lambda offset: spotify_session.current_user_saved_tracks(offset=offset)    
+        _get_favorite_tracks = lambda offset: spotify_session.current_user_saved_tracks(offset=offset)
         tracks = await repeat_on_request_error( _fetch_all_from_spotify_in_chunks, _get_favorite_tracks)
         tracks.reverse()
         return tracks

tests/unit/test_sync.py

@@ -0,0 +1,146 @@
+from typing import Literal
+from unittest.mock import MagicMock
+import asyncio
+
+from spotify_to_tidal.sync import deprecated_isrc_match
+from spotify_to_tidal.sync import _fetch_all_from_spotify_in_chunks
+from spotify_to_tidal.sync import get_tracks_from_spotify_playlist
+
+
+def _make_tidal_track(isrc: str = 'USAT21234567') -> MagicMock:
+    track = MagicMock()
+    track.isrc = isrc
+    return track
+
+
+def _make_spotify_track(
+    isrc: str = 'USAT21234567',
+    name: str = 'Test Track',
+    external_ids: bool = True,
+) -> dict:
+    """Build a minimal Spotify track dict. external_ids are deprecated and will
+    go away soon."""
+    track = {
+        'name': name,
+        'id': 'spotify123',
+        'type': 'track',
+        'duration_ms': 210000,
+        'track_number': 1,
+        'artists': [{'name': 'Test Artist'}],
+        'album': {'name': 'Test Album', 'artists': [{'name': 'Test Artist'}]},
+    }
+    if external_ids:
+        track['external_ids'] = {'isrc': isrc}
+    return track
+
+def _make_spotify_api_response(items, next_url=None, total=None, limit=50) -> dict:
+    """Build a response dict matching Spotify's playlist items endpoint."""
+    return {
+        'items': items,
+        'next': next_url,
+        'total': total or len(items),
+        'limit': limit,
+    }
+
+
+def _make_playlist_item(track_name: str = 'Test Track', item_type: Literal['track','episode']  = 'track') -> dict:
+    """Build a single playlist item."""
+    return {
+        'item': {
+            'name': track_name,
+            'id': 'spotify123',
+            'type': item_type,
+            'duration_ms': 210000,
+            'track_number': 1,
+            'artists': [{'name': 'Test Artist'}],
+            'album': {'name': 'Test Album', 'artists': [{'name': 'Test Artist'}]},
+        },
+        'type': item_type,
+    }
+
+
+
+class TestDeprecatedIsrcMatch:
+    def test_matches_when_isrc_present_and_equal(self) -> None:
+        tidal = _make_tidal_track(isrc='USAT21234567')
+        spotify = _make_spotify_track(isrc='USAT21234567')
+        assert deprecated_isrc_match(tidal, spotify) is True
+
+    def test_no_match_when_isrc_differs(self) -> None:
+        tidal = _make_tidal_track(isrc='USAT21234567')
+        spotify = _make_spotify_track(isrc='GBDCA0000001')
+        assert deprecated_isrc_match(tidal, spotify) is False
+
+    def test_returns_false_when_external_ids_missing(self) -> None:
+        tidal = _make_tidal_track()
+        spotify = _make_spotify_track(external_ids=False)
+        assert deprecated_isrc_match(tidal, spotify) is False
+
+    def test_returns_false_when_isrc_key_missing(self) -> None:
+        tidal = _make_tidal_track()
+        spotify = _make_spotify_track()
+        spotify['external_ids'] = {}
+        assert deprecated_isrc_match(tidal, spotify) is False
+
+
+
+class TestFetchAllFromSpotifyInChunks:
+    def test_single_page(self) -> None:
+        items = [_make_playlist_item('Track 1'), _make_playlist_item('Track 2')]
+        response = _make_spotify_api_response(items)
+
+        def fetch_fn(offset: int) -> dict:
+            return response
+
+        result = asyncio.run(_fetch_all_from_spotify_in_chunks(fetch_fn))
+        assert len(result) == 2
+        assert result[0]['name'] == 'Track 1'
+        assert result[1]['name'] == 'Track 2'
+
+    def test_multiple_pages(self) -> None:
+        page1_items = [_make_playlist_item('Track 1')]
+        page2_items = [_make_playlist_item('Track 2')]
+        page1 = _make_spotify_api_response(
+            page1_items, next_url='https://spotify.example.com/next', total=2, limit=1
+        )
+        page2 = _make_spotify_api_response(page2_items, total=2, limit=1)
+
+        def fetch_fn(offset: int) -> dict:
+            return page1 if offset == 0 else page2
+
+        result = asyncio.run(_fetch_all_from_spotify_in_chunks(fetch_fn))
+        assert len(result) == 2
+        assert result[0]['name'] == 'Track 1'
+        assert result[1]['name'] == 'Track 2'
+
+    def test_filters_non_track_items(self) -> None:
+        items = [
+            _make_playlist_item('Track 1', item_type='track'),
+            _make_playlist_item('Episode 1', item_type='episode'),
+        ]
+        response = _make_spotify_api_response(items)
+        def fetch_fn(offset: int) -> dict:
+            return response
+
+        result = asyncio.run(_fetch_all_from_spotify_in_chunks(fetch_fn))
+        assert len(result) == 1
+        assert result[0]['name'] == 'Track 1'
+
+
+class TestGetTracksFromSpotifyPlaylist:
+    def test_filters_out_episodes(self) -> None:
+        items = [
+            _make_playlist_item('Track 1', item_type='track'),
+            _make_playlist_item('Episode 1', item_type='episode'),
+        ]
+        response = _make_spotify_api_response(items)
+        mock_session = MagicMock()
+        mock_session.playlist_items.return_value = response
+        spotify_playlist = {'name': 'My Playlist', 'id': 'playlist123'}
+
+        result = asyncio.run(
+            get_tracks_from_spotify_playlist(mock_session, spotify_playlist)
+        )
+        assert len(result) == 1
+        assert result[0]['name'] == 'Track 1'
+