spotifywebapiPython 1.0.243__py3-none-any.whl → 1.0.251__py3-none-any.whl

spotifywebapipython/models/episodesimplified.py

@@ -186,6 +186,18 @@ class EpisodeSimplified:
         return self._Id
 
 
+    @property
+    def IdOrigin(self) -> str:
+        """ 
+        The origin Spotify ID for the episode.
+
+        The `Id` value is always returned, as linkfrom details do not exist for episodes.
+
+        This is a helper property, and is not part of the Spotify Web API specification.
+        """
+        return self._Id
+
+
     @property
     def Images(self) -> list[ImageObject]:
         """ 
@@ -211,6 +223,18 @@ class EpisodeSimplified:
         return self._IsExternallyHosted
 
 
+    @property
+    def IsLinkedFrom(self) -> bool:
+        """ 
+        Whether or not the episode is linked from another episode.
+
+        False is always returned, as linkfrom details do not exist for episodes.
+
+        This is a helper property, and is not part of the Spotify Web API specification.
+        """
+        return False
+
+
     @property
     def IsPlayable(self) -> bool:
         """ 
@@ -294,6 +318,18 @@ class EpisodeSimplified:
         return self._Uri
 
 
+    @property
+    def UriOrigin(self) -> str:
+        """ 
+        The origin Spotify URI for the episode.
+
+        The `Uri` value is always returned, as linkfrom details do not exist for episodes.
+
+        This is a helper property, and is not part of the Spotify Web API specification.
+        """
+        return self._Uri
+
+
     def ToDictionary(self) -> dict:
         """
         Returns a dictionary representation of the class.
@@ -332,6 +368,9 @@ class EpisodeSimplified:
             'resume_point': resumePoint,
             'type': self._Type,
             'uri': self._Uri,           
+            'is_linked_from': self.IsLinkedFrom,
+            'id_origin': self.IdOrigin,
+            'uri_origin': self.UriOrigin,
         }
         return result
         
@@ -367,4 +406,6 @@ class EpisodeSimplified:
         if self._Restrictions is not None: msg = '%s\n %s' % (msg, str(self._Restrictions))
         if self._ResumePoint is not None: msg = '%s\n %s' % (msg, str(self._ResumePoint))
         if self._Type is not None: msg = '%s\n Type="%s"' % (msg, str(self._Type))
+        if self.IdOrigin is not None: msg = '%s\n IdOrigin="%s"' % (msg, str(self.IdOrigin))
+        if self.UriOrigin is not None: msg = '%s\n UriOrigin="%s"' % (msg, str(self.UriOrigin))
         return msg

spotifywebapipython/models/imagepalettecolors.py

@@ -0,0 +1,111 @@
+# external package imports.
+from typing import List, Tuple
+
+# our package imports.
+from ..vibrant import Swatch
+from ..sautils import export
+
+@export
+class ImagePaletteColors:
+    """
+    Image Palette Colors object.
+
+    This is a helper class, and is not part of the Spotify Web API specification.
+    """
+
+    def __init__(self, root:list[Tuple[int, int, int]]=None) -> None:
+        """
+        Initializes a new instance of the class.
+        
+        Args:
+            root (list[Tuple[int, int, int]]):
+                A list of color palette Tuple in the form (r, g, b) that contains extracted 
+                color palette information; otherwise, None.
+        """
+        # initialize storage.
+        self._ImageSource:str = None
+        self._Items:list[Swatch] = []
+
+        if (not isinstance(root, list)):
+
+            pass
+        
+        else:
+
+            # store color palette information.
+            if root is not None:
+                for item in root:
+                    if item is not None:
+                        self._Items.append(Swatch(rgb=item))
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def ImageSource(self) -> str:
+        """ 
+        Image that was processed to obtain the palette.
+        """
+        return self._ImageSource
+
+    @ImageSource.setter
+    def ImageSource(self, value:str):
+        """ 
+        Sets the ImageSource property value.
+        """
+        self._ImageSource = value
+
+
+    @property
+    def Items(self) -> list[Swatch]:
+        """ 
+        Array of `Swatch` objects.
+        """
+        return self._Items
+    
+
+    @property
+    def ItemsCount(self) -> int:
+        """ 
+        Length of `Items` array.
+        """
+        return len(self._Items)
+    
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'image_source': self._ImageSource,
+            'items_count': self.ItemsCount,
+            'items': [ item.ToDictionary() for item in self._Items ],
+        }
+
+        return result
+        
+
+    def ToString(self, includeItems:bool=False) -> str:
+        """
+        Returns a displayable string representation of the class.
+        
+        Args:
+            includeItems (bool):
+                True to include the Items collection of objects; otherwise, False
+                to only return base properties.
+        """
+        msg:str = 'Swatch:'
+        msg = '%s\n ImageSource="%s"' % (msg, str(self._ImageSource))
+        msg = '%s\n Items Count="%s"' % (msg, str(self.ItemsCount))
+        
+        if (includeItems):
+            if self.Items is not None: msg = '%s\n\n %s' % (msg, str(self.Items))
+            
+        return msg 

spotifywebapipython/models/imagevibrantcolors.py

@@ -8,6 +8,8 @@ from ..sautils import export
 class ImageVibrantColors:
     """
     Image Vibrant Colors object.
+
+    This is a helper class, and is not part of the Spotify Web API specification.
     """
 
     def __init__(self, root:Palette=None) -> None:

spotifywebapipython/models/pageobject.py

@@ -304,6 +304,7 @@ class PageObject:
             'offset': self._Offset,
             'previous': self._Previous,
             'total': self._Total,
+            'items_count': self.ItemsCount,
             'items': [ item.ToDictionary() for item in self._Items ],
         }
 

spotifywebapipython/spotifyclient.py

@@ -3,8 +3,6 @@ import base64
 from datetime import datetime
 import json
 from io import BytesIO
-from platform import architecture
-from ssl import ALERT_DESCRIPTION_ACCESS_DENIED
 from oauthlib.oauth2 import BackendApplicationClient, WebApplicationClient
 import random
 from soco import SoCo
@@ -24,7 +22,7 @@ from zeroconf import Zeroconf
 
 # our package imports.
 from .oauthcli import AuthClient
-from .vibrant import Vibrant, Palette
+from .vibrant import Vibrant, Palette, ColorThiefFast
 from .models import *
 from .models import UserProfile as UserProfileCurrentUser
 from .spotifyconnect import SpotifyConnectDirectoryTask, SpotifyConnectDeviceNotFound
@@ -7288,6 +7286,152 @@ class SpotifyClient:
             return None
 
 
+    def GetImagePaletteColors(
+        self, 
+        imageSource:str=None, 
+        colorCount:int=10, 
+        colorQuality:int=1, 
+        brightnessFilterLow:int=None, 
+        brightnessFilterHigh:int=None, 
+        hueDistanceFilter:int=None, 
+        ) -> ImagePaletteColors:
+        """
+        Extracts color palette RGB values from the specified image source.  
+        
+        Args:
+            imageSource (str):  
+                The image source to extract color palette information from.  If the prefix of the 
+                value is `http:` or `https:`, then the image is downloaded from the url.  
+                This can also point to a filename on the local file system.  
+                If null, the currently playing Spotify track image url is used; if no track
+                is playing, then an exception is raised.
+                Example: `http://mydomain/image1.jpg`  
+                Example: `c:/image1.jpg`  
+                Default is None.  
+            colorCount (int):  
+                The size of the palette (max number of colors).  
+                Range is 1 to 256.  
+                Default is 10.  
+            colorQuality (int):  
+                Controls the processing time and quality of the palette generation.  
+                A lower value (e.g. 1) results in higher quality but takes more processing time, 
+                while a higher value (e.g. 5) is faster but may result in a lower-quality palette.   
+                Default is 1.  
+            brightnessFilterLow (int):  
+                Removes colors that are too dark based on their brightness value.  
+                Range is 0 to 765.  
+                Default is None.  
+            brightnessFilterHigh (int):  
+                Remove colors that are too light based on their brightness value.  
+                Range is 0 to 765.  
+                Default is None.  
+            hueDistanceFilter (int):  
+                Remove colors that are too close to each other for the specified hue.  
+                This keeps the colors looking fairly distinct.  
+                Range is 0 to 360.  
+                Default is None.  
+                
+        Returns:
+            A `ImagePaletteColors` object that contains extracted color information.
+                
+        Raises:
+            SpotifyWebApiError: 
+                If the Spotify Web API request was for a non-authorization service 
+                and the response contains error information.
+            SpotifyApiError: 
+                If the method fails for any other reason.
+
+        The median cut algorithm is used to cluster similar colors.
+
+        The returned list of palette entries will always have a length value that
+        matches the `colorCount` argument.  If colors are filtered, then the
+        list is padded with black (e.g. 0,0,0) entries.  This ensures that
+        the list length always matches the requested color count.
+
+        If the `brightnessFilterX` values are specified, each color in the
+        returned array is converted to a brightness value (R+G+B=brightness, 0-765)
+        and will be filtered out based on the high / low filter arguments.
+
+        If the `hueDistanceFilter` is specified, each color in the returned array
+        is converted to a hue value and will be filtered out based on the distance
+        between it and the next color.
+
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/GetImagePaletteColors.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'GetImagePaletteColors'
+        apiMethodParms:SIMethodParmListContext = None
+        result:ImagePaletteColors = {}
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("imageSource", imageSource)
+            apiMethodParms.AppendKeyValue("colorCount", colorCount)
+            apiMethodParms.AppendKeyValue("colorQuality", colorQuality)
+            apiMethodParms.AppendKeyValue("brightnessFilterLow", brightnessFilterLow)
+            apiMethodParms.AppendKeyValue("brightnessFilterHigh", brightnessFilterHigh)
+            apiMethodParms.AppendKeyValue("hueDistanceFilter", hueDistanceFilter)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Get color palette from an image url", apiMethodParms)
+                
+            # validations.
+            if (not isinstance(colorCount,int)):
+                colorCount = 10
+            if (not isinstance(colorQuality,int)):
+                colorQuality = 1
+
+            # if image source not specified, then return currently playing track image url value.
+            if (imageSource is None):
+                nowPlaying:PlayerPlayState = self.GetPlayerNowPlaying(additionalTypes=SpotifyMediaTypes.EPISODE.value)
+                if nowPlaying is not None:
+                    if nowPlaying.CurrentlyPlayingType in [SpotifyMediaTypes.TRACK.value,SpotifyMediaTypes.EPISODE.value]:
+                        trackItem:Track = nowPlaying.Item
+                        if (trackItem is not None):
+                            imageSource = trackItem.ImageUrl
+                if (imageSource is None):
+                    raise SpotifyApiError(SAAppMessages.ARGUMENT_REQUIRED_ERROR % (apiMethodName, 'imageSource'), logsi=_logsi)
+
+            # prepare to extract color palette from the image source.
+            colorThiefFast = ColorThiefFast(imageSource)
+
+            # extract the color palette, based on filter criteria specified.
+            palette = colorThiefFast.get_palette(
+                color_count=colorCount, 
+                quality=colorQuality, 
+                brightness_filter_low=brightnessFilterLow, 
+                brightness_filter_high=brightnessFilterHigh,
+                hue_distance_filter=hueDistanceFilter,
+            )
+
+            _logsi.LogArray(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(palette).__name__), palette)
+        
+            # process results.
+            result = ImagePaletteColors(root=palette)
+            result.ImageSource = imageSource
+
+            # trace.
+            _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
+            return result
+
+        except SpotifyApiError: raise  # pass handled exceptions on thru
+        except SpotifyWebApiError: raise  # pass handled exceptions on thru
+        except SpotifyWebApiAuthenticationError: raise  # pass handled exceptions on thru
+        except Exception as ex:
+            
+            # format unhandled exception.
+            raise SpotifyApiError(SAAppMessages.UNHANDLED_EXCEPTION.format(apiMethodName, str(ex)), ex, logsi=_logsi)
+
+        finally:
+        
+            # trace.
+            _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
     def GetImageVibrantColors(
         self, 
         imageSource:str=None, 
@@ -10730,6 +10874,8 @@ class SpotifyClient:
         market:str=None,
         limitTotal:int=None,
         sortResult:bool=True,
+        filterArtist:str=None,
+        filterAlbum:str=None,
         ) -> TrackPageSaved:
         """
         Get a list of the tracks saved in the current Spotify user's 'Your Library'.
@@ -10763,6 +10909,12 @@ 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
+            filterArtist (str):
+                Filter returned entries by an artist name or uri value.  
+                Value can be the full name of the artist (e.g. "Jeremy Camp"), or a partial name (e.g. "Camp").
+            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").
                 
         Returns:
             An `TrackPageSaved` object that contains saved track information.
@@ -10800,6 +10952,8 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("market", market)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
+            apiMethodParms.AppendKeyValue("filterArtist", filterArtist)
+            apiMethodParms.AppendKeyValue("filterAlbum", filterAlbum)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of the users track favorites", apiMethodParms)
                 
             # validations.
@@ -10873,13 +11027,55 @@ 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.Track.Name or "").lower(), reverse=False)
                 else:
                     result.Items.sort(key=lambda x: (x.AddedAt or "").lower(), reverse=True)
 
+                # apply artist filter criteria.
+                if (filterArtist is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: %s=\"%s\"" % ("artist", filterArtist))
+                    filterArtistCompare:str = (filterArtist or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterArtistCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        trackSaved:TrackSaved = result.Items[idx]
+                        artistFound:bool = False
+                        artist:ArtistSimplified = None
+                        for artist in trackSaved.Track.Artists:
+                            if (isFilterUri):
+                                if ((artist.Uri or "").lower() == filterArtistCompare):
+                                    artistFound = True
+                                    break
+                            elif ((artist.Name or "").lower().find(filterArtistCompare) > -1):
+                                artistFound = True
+                                break
+                        if (not artistFound):
+                            result.Items.pop(idx)
+
+                # apply album filter criteria.
+                if (filterAlbum is not None):
+                    _logsi.LogVerbose("Applying filter criteria to results list: %s=\"%s\"" % ("album", filterAlbum))
+                    filterAlbumCompare:str = (filterAlbum or "").lower()
+                    isFilterUri:bool = SpotifyClient.IsSpotifyUri(filterAlbumCompare)
+                    # process list in reverse order since we are removing items.
+                    for idx in reversed(range(len(result.Items))):
+                        trackSaved:TrackSaved = result.Items[idx]
+                        albumFound:bool = False
+                        album:Album = trackSaved.Track.Album
+                        if (album is not None):
+                            if (isFilterUri):
+                                if ((album.Uri or "").lower() == filterAlbumCompare):
+                                    albumFound = True
+                            elif ((album.Name or "").lower().find(filterAlbumCompare) > -1):
+                                albumFound = True
+                        if (not albumFound):
+                            result.Items.pop(idx)
+
             # trace.
             _logsi.LogObject(SILevel.Verbose, (TRACE_METHOD_RESULT_TYPE + result.PagingInfo) % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
             return result
@@ -12683,6 +12879,8 @@ class SpotifyClient:
         delay:float=0.50,
         resolveDeviceId:bool=True,
         limitTotal:int=200,
+        filterArtist:str=None,
+        filterAlbum:str=None,
         ) -> None:
         """
         Get a list of the tracks saved in the current Spotify user's 'Your Library'
@@ -12711,6 +12909,12 @@ class SpotifyClient:
             limitTotal (int):
                 The maximum number of items to retrieve from favorites.  
                 Default is 200; value range is 1 - 750.  
+            filterArtist (str):
+                Filter returned entries by an artist name or uri value.  
+                Value can be the full name of the artist (e.g. "Jeremy Camp"), or a partial name (e.g. "Camp").
+            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").
                 
         Raises:
             SpotifyWebApiError: 
@@ -12735,6 +12939,13 @@ class SpotifyClient:
         .. include:: ../docs/include/samplecode/SpotifyClient/PlayerMediaPlayTrackFavorites.py
         ```
         </details>
+        
+        <details>
+          <summary>Sample Code - Filter by Artist</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/PlayerMediaPlayTrackFavorites_FilterArtist.py
+        ```
+        </details>
         """
         apiMethodName:str = 'PlayerMediaPlayTrackFavorites'
         apiMethodParms:SIMethodParmListContext = None
@@ -12749,6 +12960,8 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("delay", delay)
             apiMethodParms.AppendKeyValue("resolveDeviceId (DEPRECATED)", resolveDeviceId)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
+            apiMethodParms.AppendKeyValue("filterArtist", filterArtist)
+            apiMethodParms.AppendKeyValue("filterAlbum", filterAlbum)
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device play track favorites", apiMethodParms)
                 
             # validations.
@@ -12759,7 +12972,7 @@ class SpotifyClient:
                 limitTotal = 750
 
             # get current users favorite tracks.
-            tracks:TrackPageSaved = self.GetTrackFavorites(limitTotal=limitTotal, sortResult=False)
+            tracks:TrackPageSaved = self.GetTrackFavorites(limitTotal=limitTotal, sortResult=False, filterArtist=filterArtist, filterAlbum=filterAlbum)
             if (tracks.ItemsCount == 0):
                 _logsi.LogVerbose("Current user has no favorite tracks; nothing to do")
                 return
@@ -12768,7 +12981,7 @@ class SpotifyClient:
             arrUris:list[str] = []
             trackSaved:TrackSaved
             for trackSaved in tracks.Items:
-                arrUris.append(trackSaved.Track.Uri)
+                arrUris.append(trackSaved.Track.UriOrigin)
 
             # resolve the device object from the device id.
             scDevice = self._ResolveDeviceObject(deviceId, True)