spotifywebapiPython 1.0.36__py3-none-any.whl → 1.0.147__py3-none-any.whl

spotifywebapipython/models/device.py

@@ -43,6 +43,18 @@ class Device:
             self._Type = root.get('type', None)
             self._VolumePercent = root.get('volume_percent', None)
 
+        # post load validations.
+        if self._IsActive is None:
+            self._IsActive = False
+        if self._IsPrivateSession is None:
+            self._IsPrivateSession = False
+        if self._IsRestricted is None:
+            self._IsRestricted = False
+        if self._SupportsVolume is None:
+            self._SupportsVolume = False
+        if self._VolumePercent is None:
+            self._VolumePercent = 0
+
 
     def __repr__(self) -> str:
         return self.ToString()
@@ -52,6 +64,24 @@ class Device:
         return self.ToString()
 
 
+    # implement sorting support.
+    def __eq__(self, other):
+        try:
+            return self.Name == other.Name
+        except Exception as ex:
+            if (isinstance(self, Device )) and (isinstance(other, Device )):
+                return self.Name == other.Name
+            return False
+
+    def __lt__(self, other):
+        try:
+            return self.Name < other.Name
+        except Exception as ex:
+            if (isinstance(self, Device )) and (isinstance(other, Device )):
+                return self.Name < other.Name
+            return False
+
+
     @property
     def Id(self) -> str:
         """ 
@@ -62,6 +92,14 @@ class Device:
         """
         return self._Id
 
+    @Id.setter
+    def Id(self, value:str):
+        """ 
+        Sets the Id property value.
+        """
+        if isinstance(value, str):
+            self._Id = value
+
 
     @property
     def IsActive(self) -> bool:
@@ -70,6 +108,23 @@ class Device:
         """
         return self._IsActive
 
+    @IsActive.setter
+    def IsActive(self, value:bool):
+        """ 
+        Sets the IsActive property value.
+        """
+        if isinstance(value, bool):
+            self._IsActive = value
+
+
+    @property
+    def IsMuted(self) -> bool:
+        """ 
+        True if the player device volume is zero (muted); 
+        otherwise, false.
+        """
+        return (self._VolumePercent == 0)
+
 
     @property
     def IsPrivateSession(self) -> bool:
@@ -101,6 +156,14 @@ class Device:
         """
         return self._Name
 
+    @Name.setter
+    def Name(self, value:str):
+        """ 
+        Sets the Name property value.
+        """
+        if isinstance(value, str):
+            self._Name = value
+
 
     @property
     def SelectItemNameAndId(self) -> str:
@@ -130,6 +193,14 @@ class Device:
         """
         return self._Type
 
+    @Type.setter
+    def Type(self, value:str):
+        """ 
+        Sets the Type property value.
+        """
+        if isinstance(value, str):
+            self._Type = value
+
 
     @property
     def VolumePercent(self) -> int:
@@ -141,6 +212,14 @@ class Device:
         """
         return self._VolumePercent
 
+    @VolumePercent.setter
+    def VolumePercent(self, value:int):
+        """ 
+        Sets the VolumePercent property value.
+        """
+        if isinstance(value, int):
+            self._VolumePercent = value
+
 
     @staticmethod
     def GetIdFromSelectItem(value:str) -> str:
@@ -153,7 +232,7 @@ class Device:
                 
         Returns:
             The Id portion of a `SelectItemNameAndId` property value, or None
-            if the Id potion could not be determined.
+            if the Id portion could not be determined.
         """
         result:str = None
         if isinstance(value, str):
@@ -174,7 +253,7 @@ class Device:
                 
         Returns:
             The Name portion of a `SelectItemNameAndId` property value, or None
-            if the Name potion could not be determined.
+            if the Name portion could not be determined.
         """
         result:str = None
         if isinstance(value, str):
@@ -198,6 +277,9 @@ class Device:
             'supports_volume': self._SupportsVolume,
             'type': self._Type,
             'volume_percent': self._VolumePercent,
+            # helper property(s), not part of the Spotify Web API interface:
+            'is_muted': self.IsMuted,
+            'select_item_name_and_id': self.SelectItemNameAndId,
         }
         return result
         
@@ -209,6 +291,7 @@ class Device:
         msg:str = 'Device:'
         if self._Id is not None: msg = '%s\n Id="%s"' % (msg, str(self._Id))
         if self._IsActive is not None: msg = '%s\n IsActive="%s"' % (msg, str(self._IsActive))
+        if self.IsMuted is not None: msg = '%s\n IsMuted="%s"' % (msg, str(self.IsMuted))
         if self._IsPrivateSession is not None: msg = '%s\n IsPrivateSession="%s"' % (msg, str(self._IsPrivateSession))
         if self._IsRestricted is not None: msg = '%s\n IsRestricted="%s"' % (msg, str(self._IsRestricted))
         if self._Name is not None: msg = '%s\n Name="%s"' % (msg, str(self._Name))

spotifywebapipython/models/episodepagesaved.py

@@ -39,7 +39,8 @@ class EpisodePageSaved(PageObject):
             items:list = root.get('items',None)
             if items is not None:
                 for item in items:
-                    self._Items.append(EpisodeSaved(root=item))
+                    if item is not None:
+                        self._Items.append(EpisodeSaved(root=item))
 
         
     def __repr__(self) -> str:

spotifywebapipython/models/episodepagesimplified.py

@@ -38,7 +38,8 @@ class EpisodePageSimplified(PageObject):
             items:list = root.get('items',None)
             if items is not None:
                 for item in items:
-                    self._Items.append(EpisodeSimplified(root=item))
+                    if item is not None:
+                        self._Items.append(EpisodeSimplified(root=item))
 
         
     def __repr__(self) -> str:

spotifywebapipython/models/episodesaved.py

@@ -51,8 +51,8 @@ class EpisodeSaved:
         
         Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero 
         offset: YYYY-MM-DDTHH:MM:SSZ. If the time is imprecise (for example, the date/time of an 
-        album release), an additional field indicates the precision; see for example, release_date 
-        in an album object.
+        episode release), an additional field indicates the precision; see for example, release_date 
+        in an episode object.
         """
         return self._AddedAt
 

spotifywebapipython/models/episodesimplified.py

@@ -153,7 +153,7 @@ class EpisodeSimplified:
     @property
     def ExternalUrls(self) -> ExternalUrls:
         """ 
-        Known external URLs for the album.
+        Known external URLs for the episode.
         """
         return self._ExternalUrls
     
@@ -197,12 +197,10 @@ class EpisodeSimplified:
     @property
     def ImageUrl(self) -> str:
         """
-        Gets the first image url in the `Images` list, if images are defined;
-        otherwise, null.
+        Returns the highest resolution order image from the `Images` list, if images 
+        are defined; otherwise, null.
         """
-        if len(self._Images) > 0:
-            return self._Images[0].Url
-        return None
+        return ImageObject.GetImageHighestResolution(self._Images)
             
         
     @property
@@ -322,6 +320,7 @@ class EpisodeSimplified:
             'href': self._Href,
             'html_description': self._HtmlDescription,
             'id': self._Id,
+            'image_url': self.ImageUrl,
             'images': [ item.ToDictionary() for item in self._Images ],
             'is_externally_hosted': self._IsExternallyHosted,
             'is_playable': self._IsPlayable,

spotifywebapipython/models/imageobject.py

@@ -71,6 +71,104 @@ class ImageObject:
         return self._Width
 
 
+    @staticmethod
+    def GetImageHighestResolution(
+            images:list,
+            desiredWidth:int=None,
+            ) -> str:
+        """
+        Returns the highest resolution order image from a list of `ImageObject` items.
+    
+        Args:
+            images (list[ImageObject]):
+                The cover art for the media in various sizes, usually widest first.
+            desiredWidth (int):
+                A desired resolution width to return (if found); if not found, then the
+                highest resolution is returned.
+
+        Returns:
+            The highest resolution order image from the list of `images`.
+    
+        The Spotify Web API normally returns a list of `ImageObject` items with the
+        highest resolution image as the first list item; however, the GetShowFavorites
+        returns them in the reverse order.
+        """
+        result:str = None
+        resultWidth:int = 0
+
+        if (images is not None) and (len(images) > 0):
+        
+            # set default image to return.
+            result = images[0].Url
+            resultWidth:int = (images[0].Width or 0)  # in case width is null
+            
+            # search for the highest resolution image and return it.
+            image: ImageObject
+            for image in images:
+
+                imageWidth:int = (image.Width or 0)   # in case width is null
+
+                # check for exact desired width match.
+                if (desiredWidth is not None) and (desiredWidth == imageWidth):
+                    result = image.Url
+                    resultWidth = imageWidth
+                    break
+
+                # check for largest resolution width match.
+                if (imageWidth > resultWidth):
+                    result = image.Url
+                    resultWidth = imageWidth
+        
+        return result
+    
+
+    @staticmethod
+    def GetImageHighestResolutionWidth(
+            images:list,
+            desiredWidth:int=None,
+            ) -> str:
+        """
+        Returns the highest resolution order image width from a list of `ImageObject` items.
+    
+        Args:
+            images (list[ImageObject]):
+                The cover art for the media in various sizes, usually widest first.
+            desiredWidth (int):
+                A desired resolution width to return (if found); if not found, then the
+                highest resolution is returned.
+
+        Returns:
+            The highest resolution order image width from the list of `images`.
+    
+        The Spotify Web API normally returns a list of `ImageObject` items with the
+        highest resolution image as the first list item; however, the GetShowFavorites
+        returns them in the reverse order.
+        """
+        resultWidth:int = 0
+
+        if (images is not None) and (len(images) > 0):
+        
+            # set default image width to return.
+            resultWidth:int = (images[0].Width or 0)  # in case width is null
+            
+            # search for the highest resolution image width and return it.
+            image: ImageObject
+            for image in images:
+
+                imageWidth:int = (image.Width or 0)   # in case width is null
+
+                # check for exact desired width match.
+                if (desiredWidth is not None) and (desiredWidth == imageWidth):
+                    resultWidth = imageWidth
+                    break
+
+                # check for largest resolution width match.
+                if (imageWidth > resultWidth):
+                    resultWidth = imageWidth
+        
+        return resultWidth
+    
+
     def ToDictionary(self) -> dict:
         """
         Returns a dictionary representation of the class.

spotifywebapipython/models/pageobject.py

@@ -1,5 +1,3 @@
-# external package imports.
-
 # our package imports.
 from ..sautils import export
 
@@ -22,8 +20,9 @@ class PageObject:
         """
         self._CursorAfter:object = None
         self._CursorBefore:object = None
+        self._DateLastRefreshed:float = 0
         self._Href:str = None
-        self._IsCursor = False
+        self._IsCursor:bool = False
         self._Items:list[object] = []
         self._Limit:int = 0
         self._Next:str = None
@@ -103,6 +102,30 @@ class PageObject:
         self._CursorBefore = value
 
 
+    @property
+    def DateLastRefreshed(self) -> float:
+        """ 
+        Date and time items were was last refreshed, in unix epoch format (e.g. 1669123919.331225).
+        A value of zero indicates the date was unknown.
+        
+        Note that this attribute does not exist in the Spotify Web API; 
+        it was added here for convenience.
+        """
+        return self._DateLastRefreshed
+    
+    @DateLastRefreshed.setter
+    def DateLastRefreshed(self, value:float):
+        """ 
+        Sets the DateLastRefreshed property value.
+        """
+        if (value is None):
+            self._DateLastRefreshed = 0
+        elif isinstance(value, float):
+            self._DateLastRefreshed = value
+        elif isinstance(value, int):
+            self._DateLastRefreshed = float(value)
+
+
     @property
     def Href(self) -> str:
         """ 
@@ -114,7 +137,7 @@ class PageObject:
 
 
     @property
-    def IsCursor(self) -> list[object]:
+    def IsCursor(self) -> bool:
         """ 
         True if cursors were returned at some point during the life of this paging object.
         """
@@ -274,6 +297,7 @@ class PageObject:
         """
         result:dict = \
         {
+            'date_last_refreshed': self._DateLastRefreshed,
             'href': self._Href,
             'limit': self._Limit,
             'next': self._Next,
@@ -309,6 +333,7 @@ class PageObject:
         msg = '%s\n Previous="%s"' % (msg, str(self._Previous))
         msg = '%s\n Total="%s"' % (msg, str(self._Total))
         msg = '%s\n Items Count="%s"' % (msg, str(self.ItemsCount))
+        msg = '%s\n DateLastRefreshed=%s' % (msg, str(self._DateLastRefreshed))
         if self._CursorAfter is not None: msg = '%s\n Cursor After="%s"' % (msg, str(self._CursorAfter))
         if self._CursorBefore is not None: msg = '%s\n Cursor Before="%s"' % (msg, str(self._CursorBefore))
         

spotifywebapipython/models/playeractions.py

@@ -36,16 +36,38 @@ class PlayerActions:
         
         else:
 
-            self._InterruptingPlayback:bool = root.get('interrupting_playback', None)
-            self._Pausing:bool = root.get('pausing', None)
-            self._Resuming:bool = root.get('resuming', None)
-            self._Seeking:bool = root.get('seeking', None)
-            self._SkippingNext:bool = root.get('skipping_next', None)
-            self._SkippingPrev:bool = root.get('skipping_prev', None)
-            self._TogglingRepeatContext:bool = root.get('toggling_repeat_context', None)
-            self._TogglingRepeatTrack:bool = root.get('toggling_shuffle', None)
-            self._TogglingShuffle:bool = root.get('toggling_repeat_track', None)
-            self._TransferringPlayback:bool = root.get('transferring_playback', None)
+            self._InterruptingPlayback = root.get('interrupting_playback', None)
+            self._Pausing = root.get('pausing', None)
+            self._Resuming = root.get('resuming', None)
+            self._Seeking = root.get('seeking', None)
+            self._SkippingNext = root.get('skipping_next', None)
+            self._SkippingPrev = root.get('skipping_prev', None)
+            self._TogglingRepeatContext = root.get('toggling_repeat_context', None)
+            self._TogglingRepeatTrack = root.get('toggling_repeat_track', None)
+            self._TogglingShuffle = root.get('toggling_shuffle', None)
+            self._TransferringPlayback = root.get('transferring_playback', None)
+
+        # post load validations.
+        if self._InterruptingPlayback is None:
+            self._InterruptingPlayback = False
+        if self._Pausing is None:
+            self._Pausing = False
+        if self._Resuming is None:
+            self._Resuming = False
+        if self._Seeking is None:
+            self._Seeking = False
+        if self._SkippingNext is None:
+            self._SkippingNext = False
+        if self._SkippingPrev is None:
+            self._SkippingPrev = False
+        if self._TogglingRepeatContext is None:
+            self._TogglingRepeatContext = False
+        if self._TogglingRepeatTrack is None:
+            self._TogglingRepeatTrack = False
+        if self._TogglingShuffle is None:
+            self._TogglingShuffle = False
+        if self._TransferringPlayback is None:
+            self._TransferringPlayback = False
 
 
     def __repr__(self) -> str:
@@ -160,7 +182,7 @@ class PlayerActions:
         """
         Returns a displayable string representation of the class.
         """
-        msg:str = 'PlaybackActions:'
+        msg:str = 'PlayerActions:'
         if self._InterruptingPlayback is not None: msg = '%s\n InterruptingPlayback="%s"' % (msg, str(self._InterruptingPlayback))
         if self._Pausing is not None: msg = '%s\n Pausing="%s"' % (msg, str(self._Pausing))
         if self._Resuming is not None: msg = '%s\n Resuming="%s"' % (msg, str(self._Resuming))