spotifywebapiPython 1.0.284__py3-none-any.whl → 1.0.286__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -3674,6 +3674,7 @@ class SpotifyClient:
         market:str=None,
         limitTotal:int=None,
         sortResult:bool=True,
+        filterCriteria:str|None=None,
         ) -> AlbumPageSaved:
         """
         Get a list of the albums saved in the current Spotify user's 'Your Library'.
@@ -3707,6 +3708,9 @@ class SpotifyClient:
                 True to sort the items by name; otherwise, False to leave the items in the same order they 
                 were returned in by the Spotify Web API.  
                 Default: True
+            filterCriteria (str):
+                Filter returned entries by a album name or uri value.  
+                Value can be a full name (e.g. "My Album Name"), or a partial name (e.g. "My").
                 
         Returns:
             An `AlbumPageSaved` object that contains saved album information.
@@ -3744,6 +3748,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("market", market)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
+            apiMethodParms.AppendKeyValue("filterCriteria", filterCriteria)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of the user's album favorites", apiMethodParms)
                 
             # validations.
@@ -3817,13 +3822,32 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
             
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Album.Name or "").lower(), reverse=False)
                 else:
                     result.Items.sort(key=lambda x: (x.AddedAt or "").lower(), reverse=True)
 
+                # apply filter criteria (if specified).
+                if (filterCriteria is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: \"%s\"" % (filterCriteria))
+                    filterCriteriaCompare:str = (filterCriteria or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterCriteriaCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        item:AlbumSaved = result.Items[idx]
+                        itemFound:bool = False
+                        if (isFilterUri):
+                            if ((item.Album.Uri or "").lower() == filterCriteriaCompare):
+                                itemFound = True
+                        elif ((item.Album.Name or "").lower().find(filterCriteriaCompare) > -1):
+                            itemFound = True
+                        if (not itemFound):
+                            result.Items.pop(idx)
+            
             # trace.
             _logsi.LogObject(SILevel.Verbose, (TRACE_METHOD_RESULT_TYPE + result.PagingInfo) % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -3849,6 +3873,7 @@ class SpotifyClient:
         country:str=None,
         limitTotal:int=None,
         sortResult:bool=True,
+        filterCriteria:str|None=None,
         ) -> AlbumPageSimplified:
         """
         <span class="deprecated">
@@ -3886,6 +3911,9 @@ class SpotifyClient:
                 True to sort the items by name; otherwise, False to leave the items in the same order they 
                 were returned in by the Spotify Web API.  
                 Default: True
+            filterCriteria (str):
+                Filter returned entries by a album name or uri value.  
+                Value can be a full name (e.g. "My Album Name"), or a partial name (e.g. "My").
                 
         Returns:
             An `AlbumPageSimplified` object that contains simplified album information.
@@ -3923,6 +3951,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("country", country)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
+            apiMethodParms.AppendKeyValue("filterCriteria", filterCriteria)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of new album releases", apiMethodParms)
                 
             # are spotify web player credentials configured? if so, then we will use them to create
@@ -3997,11 +4026,30 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
 
+                # apply filter criteria (if specified).
+                if (filterCriteria is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: \"%s\"" % (filterCriteria))
+                    filterCriteriaCompare:str = (filterCriteria or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterCriteriaCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        item:AlbumSimplified = result.Items[idx]
+                        itemFound:bool = False
+                        if (isFilterUri):
+                            if ((item.Uri or "").lower() == filterCriteriaCompare):
+                                itemFound = True
+                        elif ((item.Name or "").lower().find(filterCriteriaCompare) > -1):
+                            itemFound = True
+                        if (not itemFound):
+                            result.Items.pop(idx)
+
             # trace.
             _logsi.LogObject(SILevel.Verbose, (TRACE_METHOD_RESULT_TYPE + result.PagingInfo) % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -4551,8 +4599,10 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+    
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
 
@@ -5116,6 +5166,7 @@ class SpotifyClient:
         limit:int=20, 
         limitTotal:int=None,
         sortResult:bool=True,
+        filterCriteria:str|None=None,
         ) -> ArtistPage:
         """
         Get the current user's followed artists.
@@ -5139,6 +5190,9 @@ class SpotifyClient:
                 True to sort the items by name; otherwise, False to leave the items in the same order they 
                 were returned in by the Spotify Web API.  
                 Default: True
+            filterCriteria (str):
+                Filter returned entries by a audiobook name or uri value.  
+                Value can be a full name (e.g. "My AudioBook Name"), or a partial name (e.g. "My").
                 
         Returns:
             An `ArtistPage` object of matching results.
@@ -5175,6 +5229,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("limit", limit)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
+            apiMethodParms.AppendKeyValue("filterCriteria", filterCriteria)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get the current user's followed artists", apiMethodParms)
                 
             # validations.
@@ -5250,11 +5305,30 @@ class SpotifyClient:
             result.CursorAfter = pageObj.CursorAfter
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
         
+                # apply filter criteria (if specified).
+                if (filterCriteria is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: \"%s\"" % (filterCriteria))
+                    filterCriteriaCompare:str = (filterCriteria or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterCriteriaCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        item:Artist = result.Items[idx]
+                        itemFound:bool = False
+                        if (isFilterUri):
+                            if ((item.Uri or "").lower() == filterCriteriaCompare):
+                                itemFound = True
+                        elif ((item.Name or "").lower().find(filterCriteriaCompare) > -1):
+                            itemFound = True
+                        if (not itemFound):
+                            result.Items.pop(idx)
+
             # trace.
             _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -5687,6 +5761,7 @@ class SpotifyClient:
         offset:int=0,
         limitTotal:int=None,
         sortResult:bool=True,
+        filterCriteria:str|None=None,
         ) -> AudiobookPageSimplified:
         """
         Get a list of the audiobooks saved in the current Spotify user's 'Your Library'.
@@ -5712,6 +5787,9 @@ class SpotifyClient:
                 True to sort the items by name; otherwise, False to leave the items in the same order they 
                 were returned in by the Spotify Web API.  
                 Default: True
+            filterCriteria (str):
+                Filter returned entries by a audiobook name or uri value.  
+                Value can be a full name (e.g. "My AudioBook Name"), or a partial name (e.g. "My").
                 
         Returns:
             An `AudiobookPageSimplified` object that contains saved audiobook information.
@@ -5748,6 +5826,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("offset", offset)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
+            apiMethodParms.AppendKeyValue("filterCriteria", filterCriteria)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of the users audiobook favorites", apiMethodParms)
                 
             # validations.
@@ -5814,11 +5893,30 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
 
+                # apply filter criteria (if specified).
+                if (filterCriteria is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: \"%s\"" % (filterCriteria))
+                    filterCriteriaCompare:str = (filterCriteria or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterCriteriaCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        item:AudiobookSimplified = result.Items[idx]
+                        itemFound:bool = False
+                        if (isFilterUri):
+                            if ((item.Uri or "").lower() == filterCriteriaCompare):
+                                itemFound = True
+                        elif ((item.Name or "").lower().find(filterCriteriaCompare) > -1):
+                            itemFound = True
+                        if (not itemFound):
+                            result.Items.pop(idx)
+
             # trace.
             _logsi.LogObject(SILevel.Verbose, (TRACE_METHOD_RESULT_TYPE + result.PagingInfo) % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -6260,8 +6358,10 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
         
@@ -6569,8 +6669,10 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
 
@@ -7169,6 +7271,7 @@ class SpotifyClient:
         offset:int=0,
         limitTotal:int=None,
         sortResult:bool=True,
+        filterCriteria:str|None=None,
         ) -> EpisodePageSaved:
         """
         Get a list of the episodes saved in the current Spotify user's 'Your Library'.
@@ -7194,6 +7297,9 @@ class SpotifyClient:
                 True to sort the items by name; otherwise, False to leave the items in the same order they 
                 were returned in by the Spotify Web API.  
                 Default: True
+            filterCriteria (str):
+                Filter returned entries by a episode name or uri value.  
+                Value can be a full name (e.g. "My Episode Name"), or a partial name (e.g. "My").
                 
         Returns:
             An `EpisodePageSaved` object that contains saved episode information.
@@ -7230,6 +7336,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("offset", offset)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
+            apiMethodParms.AppendKeyValue("filterCriteria", filterCriteria)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of the users episode favorites", apiMethodParms)
                 
             # validations.
@@ -7298,13 +7405,32 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Episode.Name or "").lower(), reverse=False)
                 else:
                     result.Items.sort(key=lambda x: (x.AddedAt or "").lower(), reverse=True)
             
+                # apply filter criteria (if specified).
+                if (filterCriteria is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: \"%s\"" % (filterCriteria))
+                    filterCriteriaCompare:str = (filterCriteria or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterCriteriaCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        item:EpisodeSaved = result.Items[idx]
+                        itemFound:bool = False
+                        if (isFilterUri):
+                            if ((item.Episode.Uri or "").lower() == filterCriteriaCompare):
+                                itemFound = True
+                        elif ((item.Episode.Name or "").lower().find(filterCriteriaCompare) > -1):
+                            itemFound = True
+                        if (not itemFound):
+                            result.Items.pop(idx)
+
             # trace.
             _logsi.LogObject(SILevel.Verbose, (TRACE_METHOD_RESULT_TYPE + result.PagingInfo) % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -7618,8 +7744,10 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
 
@@ -9223,7 +9351,8 @@ class SpotifyClient:
         limit:int=50,
         after:int=None,
         before:int=None,
-        limitTotal:int=None
+        limitTotal:int=None,
+        filterCriteria:str|None=None,
         ) -> PlayHistoryPage:
         """
         Get tracks from the current user's recently played tracks.  
@@ -9254,6 +9383,9 @@ class SpotifyClient:
                 and paging is automatically used to retrieve all available items up to the
                 maximum number specified.  
                 Default: None (disabled)
+            filterCriteria (str):
+                Filter returned entries by a track name or uri value.  
+                Value can be a full name (e.g. "My Track Name"), or a partial name (e.g. "My").
                 
         Spotify currently limits the maximum number of items returned to 50 no matter what you 
         supply for the `limitTotal` argument.
@@ -9299,6 +9431,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("after", after)
             apiMethodParms.AppendKeyValue("before", before)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
+            apiMethodParms.AppendKeyValue("filterCriteria", filterCriteria)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get tracks from the current user's recently played tracks", apiMethodParms)
             
             # validations.
@@ -9388,6 +9521,26 @@ class SpotifyClient:
             result.CursorBefore = pageObj.CursorBefore
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
+            # any results to process?
+            if (len(result.Items) > 0):
+
+                # apply filter criteria (if specified).
+                if (filterCriteria is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: \"%s\"" % (filterCriteria))
+                    filterCriteriaCompare:str = (filterCriteria or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterCriteriaCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        item:PlayHistory = result.Items[idx]
+                        itemFound:bool = False
+                        if (isFilterUri):
+                            if ((item.Track.Uri or "").lower() == filterCriteriaCompare):
+                                itemFound = True
+                        elif ((item.Track.Name or "").lower().find(filterCriteriaCompare) > -1):
+                            itemFound = True
+                        if (not itemFound):
+                            result.Items.pop(idx)
+
             # trace.
             _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -9888,6 +10041,7 @@ class SpotifyClient:
         offset:int=0,
         limitTotal:int=None,
         sortResult:bool=True,
+        filterCriteria:str|None=None,
         ) -> PlaylistPageSimplified:
         """
         Get a list of the playlists owned or followed by the current Spotify user.
@@ -9913,6 +10067,9 @@ class SpotifyClient:
                 True to sort the items by name; otherwise, False to leave the items in the same order they 
                 were returned in by the Spotify Web API.  
                 Default: True
+            filterCriteria (str):
+                Filter returned entries by a playlist name or uri value.  
+                Value can be a full name (e.g. "My Playlist Name"), or a partial name (e.g. "My").
                 
         Returns:
             An `PlaylistPageSimplified` object that contains playlist information.
@@ -9958,6 +10115,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("offset", offset)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
+            apiMethodParms.AppendKeyValue("filterCriteria", filterCriteria)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of the users playlist favorites", apiMethodParms)
                 
             # are spotify web player credentials configured? if so, then we will use them to create
@@ -10028,10 +10186,29 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
+
+                # apply filter criteria (if specified).
+                if (filterCriteria is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: \"%s\"" % (filterCriteria))
+                    filterCriteriaCompare:str = (filterCriteria or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterCriteriaCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        item:PlaylistSimplified = result.Items[idx]
+                        itemFound:bool = False
+                        if (isFilterUri):
+                            if ((item.Uri or "").lower() == filterCriteriaCompare):
+                                itemFound = True
+                        elif ((item.Name or "").lower().find(filterCriteriaCompare) > -1):
+                            itemFound = True
+                        if (not itemFound):
+                            result.Items.pop(idx)
             
             # trace.
             _logsi.LogObject(SILevel.Verbose, (TRACE_METHOD_RESULT_TYPE + result.PagingInfo) % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
@@ -10202,8 +10379,10 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
             
@@ -10513,6 +10692,7 @@ class SpotifyClient:
         limitTotal:int=None,
         sortResult:bool=True,
         excludeAudiobooks:bool=True,
+        filterCriteria:str|None=None,
         ) -> ShowPageSaved:
         """
         Get a list of the shows saved in the current Spotify user's 'Your Library'.
@@ -10542,6 +10722,9 @@ class SpotifyClient:
                 True to exclude audiobook shows from the returned list, leaving only podcast shows;
                 otherwise, False to include all results returned by the Spotify Web API.  
                 Default: True  
+            filterCriteria (str):
+                Filter returned entries by a show name or uri value.  
+                Value can be a full name (e.g. "My Show Name"), or a partial name (e.g. "My").
                 
         Returns:
             An `ShowPageSaved` object that contains saved show information.
@@ -10584,6 +10767,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
             apiMethodParms.AppendKeyValue("excludeAudiobooks", excludeAudiobooks)
+            apiMethodParms.AppendKeyValue("filterCriteria", filterCriteria)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of the users show favorites", apiMethodParms)
                 
             # validations.
@@ -10668,13 +10852,32 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Show.Name or "").lower(), reverse=False)
                 else:
                     result.Items.sort(key=lambda x: (x.AddedAt or "").lower(), reverse=True)
             
+                # apply filter criteria (if specified).
+                if (filterCriteria is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: \"%s\"" % (filterCriteria))
+                    filterCriteriaCompare:str = (filterCriteria or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterCriteriaCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        item:ShowSaved = result.Items[idx]
+                        itemFound:bool = False
+                        if (isFilterUri):
+                            if ((item.Show.Uri or "").lower() == filterCriteriaCompare):
+                                itemFound = True
+                        elif ((item.Show.Name or "").lower().find(filterCriteriaCompare) > -1):
+                            itemFound = True
+                        if (not itemFound):
+                            result.Items.pop(idx)
+
             # trace.
             _logsi.LogObject(SILevel.Verbose, (TRACE_METHOD_RESULT_TYPE + result.PagingInfo) % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -11474,6 +11677,7 @@ class SpotifyClient:
         sortResult:bool=True,
         filterArtist:str=None,
         filterAlbum:str=None,
+        filterCriteria:str|None=None,
         ) -> TrackPageSaved:
         """
         Get a list of the tracks saved in the current Spotify user's 'Your Library'.
@@ -11513,6 +11717,9 @@ class SpotifyClient:
             filterAlbum (str):
                 Filter returned entries by an album name or uri value.
                 Value can be the full name of the album (e.g. "Carried Me"), or a partial name (e.g. "Carried").
+            filterCriteria (str):
+                Filter returned entries by a track name or uri value.  
+                Value can be a full name (e.g. "My Track Name"), or a partial name (e.g. "My").
                 
         Returns:
             An `TrackPageSaved` object that contains saved track information.
@@ -11552,6 +11759,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
             apiMethodParms.AppendKeyValue("filterArtist", filterArtist)
             apiMethodParms.AppendKeyValue("filterAlbum", filterAlbum)
+            apiMethodParms.AppendKeyValue("filterCriteria", filterCriteria)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of the users track favorites", apiMethodParms)
                 
             # validations.
@@ -11674,6 +11882,23 @@ class SpotifyClient:
                         if (not albumFound):
                             result.Items.pop(idx)
 
+                # apply filter criteria (if specified).
+                if (filterCriteria is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: %s=\"%s\"" % ("track", filterCriteria))
+                    filterCriteriaCompare:str = (filterCriteria or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterCriteriaCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        item:TrackSaved = result.Items[idx]
+                        itemFound:bool = False
+                        if (isFilterUri):
+                            if ((item.Track.Uri or "").lower() == filterCriteriaCompare):
+                                itemFound = True
+                        elif ((item.Track.Name or "").lower().find(filterCriteriaCompare) > -1):
+                            itemFound = True
+                        if (not itemFound):
+                            result.Items.pop(idx)
+
             # trace.
             _logsi.LogObject(SILevel.Verbose, (TRACE_METHOD_RESULT_TYPE + result.PagingInfo) % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -12674,8 +12899,10 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
         
@@ -12841,8 +13068,10 @@ class SpotifyClient:
             result.Total = pageObj.Total
             result.DateLastRefreshed = datetime.utcnow().timestamp()
 
-            # sort result items.
+            # any results to process?
             if (len(result.Items) > 0):
+
+                # sort result items.
                 if (sortResult is True):
                     result.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
         

{spotifywebapipython-1.0.284.dist-info → spotifywebapipython-1.0.286.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: spotifywebapipython
-Version: 1.0.284
+Version: 1.0.286
 Summary: Spotify Web API Python3 Library
 Author: Todd Lucas
 Author-email: <thlucas@yahoo.com>