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

spotifywebapipython/models/playerplaystate.py

@@ -28,6 +28,7 @@ class PlayerPlayState:
         """
         self._Actions:PlayerActions = None
         self._Context:Context = None
+        self._ItemType:str = None
         self._CurrentlyPlayingType:str = None
         self._Device:Device = None
         self._Item:object = None
@@ -37,6 +38,9 @@ class PlayerPlayState:
         self._ShuffleState:bool = None
         self._SmartShuffle:bool = None
         self._Timestamp:int = None
+
+        # helper properties, not part of the Spotify Web API interface.
+        self._IsEmpty:bool = True
         
         if (root is None):
 
@@ -55,7 +59,9 @@ class PlayerPlayState:
             # process all collections and objects.
             item:dict = root.get('actions',None)
             if item is not None:
-                self._Actions = PlayerActions(root=item)
+                disallows:dict = item.get('disallows')
+                if disallows is not None:
+                    self._Actions = PlayerActions(root=disallows)
 
             item:dict = root.get('context',None)
             if item is not None:
@@ -72,7 +78,31 @@ class PlayerPlayState:
                 elif self._CurrentlyPlayingType == 'episode':
                     self._Item = Episode(root=item)
 
-        
+            # if root contains keys, then assume it is NOT empty.
+            if (len(root) > 0):
+                self._IsEmpty = False
+
+        # post load validations.
+        if self._Actions is None:
+            self._Actions = PlayerActions()
+        if self._Device is None:
+            self._Device = Device()
+        if self._CurrentlyPlayingType is None:
+            self._CurrentlyPlayingType = 'unknown'
+        if self._IsPlaying is None:
+            self._IsPlaying = False
+        if self._ProgressMS is None:
+            self._ProgressMS = 0
+        if self._RepeatState is None:
+            self._RepeatState = 'off'
+        if self._ShuffleState is None:
+            self._ShuffleState = False
+        if self._SmartShuffle is None:
+            self._SmartShuffle = False
+        if self._Timestamp is None:
+            self._Timestamp = 0
+
+
     def __repr__(self) -> str:
         return self.ToString()
 
@@ -126,6 +156,27 @@ class PlayerPlayState:
         return self._Item
 
 
+    @property
+    def ItemType(self) -> str:
+        """ 
+        The type of the currently playing episode; can be null.  
+        This value will be null if the `Item` property value is null.
+        
+        If not null, it can be one of `audiobook` or `podcast`.
+        
+        Note that this is not a Spotify Web API property; it is loaded from our API so
+        that the type of episode can be determined programatically (e.g. audiobook or podcast).
+        """
+        return self._ItemType
+
+    @ItemType.setter
+    def ItemType(self, value:str):
+        """ 
+        Sets the ItemType property value.
+        """
+        self._ItemType = value
+
+
     @property
     def IsAdvertisement(self) -> bool:
         """ 
@@ -136,6 +187,39 @@ class PlayerPlayState:
         return False
 
 
+    @property
+    def IsEmpty(self) -> bool:
+        """ 
+        True if Spotify playstate returned an empty response; otherwise, false.
+
+        Note that for Sonos devices, the Spotify Web API reports an empty playstate since 
+        the SoCo API is actually controlling player.
+
+        This is a helper property, and is not part of the Spotify Web API specification.
+        """
+        return self._IsEmpty
+
+    @IsEmpty.setter
+    def IsEmpty(self, value:bool):
+        """ 
+        Sets the IsEmpty property value.
+        """
+        if isinstance(value, bool):
+            self._IsEmpty = value
+
+
+    @property
+    def IsMuted(self) -> bool:
+        """ 
+        True if the player device volume is zero (muted) OR there is no device; 
+        otherwise, false.
+        """
+        if self._Device is None:
+            return True
+        else:
+            return self._Device.IsMuted
+
+
     @property
     def IsPlaying(self) -> bool:
         """ 
@@ -148,7 +232,7 @@ class PlayerPlayState:
         """ 
         Sets the IsPlaying property value.
         """
-        if value is None or isinstance(value, bool):
+        if isinstance(value, bool):
             self._IsPlaying = value
 
 
@@ -159,9 +243,9 @@ class PlayerPlayState:
         
         The `RepeatState` property contains the actual repeat setting.
         """
-        if self._RepeatState is None or self._RepeatState == 'off': 
-            return False
-        return True
+        if self._RepeatState != 'off': 
+            return True
+        return False
 
 
     @property
@@ -169,9 +253,19 @@ class PlayerPlayState:
         """ 
         True if shuffle play is enabled; otherwise, False. 
         """
-        if self.ShuffleState is None or self.ShuffleState == 'off':
-            return False
-        return True
+        if (self.ShuffleState == 'on') or (self.ShuffleState == True):
+            return True
+        return False
+
+
+    @property
+    def IsSmartShuffleEnabled(self) -> bool:
+        """ 
+        True if smart shuffle play is enabled; otherwise, False. 
+        """
+        if (self.SmartShuffle == 'on' or self.SmartShuffle == True):
+            return True
+        return False
 
 
     @property
@@ -181,6 +275,14 @@ class PlayerPlayState:
         """
         return self._ProgressMS
 
+    @ProgressMS.setter
+    def ProgressMS(self, value:int):
+        """ 
+        Sets the ProgressMS property value.
+        """
+        if isinstance(value, int):
+            self._ProgressMS = value
+
 
     @property
     def RepeatState(self) -> str:
@@ -191,17 +293,17 @@ class PlayerPlayState:
 
 
     @property
-    def ShuffleState(self) -> str:
+    def ShuffleState(self) -> bool:
         """ 
-        If shuffle is `on` or `off`.
+        If shuffle is enabled, True or False.
         """
         return self._ShuffleState
 
 
     @property
-    def SmartShuffle(self) -> str:
+    def SmartShuffle(self) -> bool:
         """ 
-        If smart shuffle is `on` or `off`.
+        If smart shuffle is enabled, True or False.
         """
         return self._SmartShuffle
 
@@ -237,6 +339,14 @@ class PlayerPlayState:
         """
         return self._Timestamp
 
+    @Timestamp.setter
+    def Timestamp(self, value:int):
+        """ 
+        Sets the Timestamp property value.
+        """
+        if isinstance(value, int):
+            self._Timestamp = value
+
 
     def ToDictionary(self) -> dict:
         """
@@ -260,6 +370,7 @@ class PlayerPlayState:
             
         result:dict = \
         {
+            'is_empty': self._IsEmpty,
             'actions': actions,
             'context': context,
             'currently_playing_type': self._CurrentlyPlayingType,
@@ -270,6 +381,7 @@ class PlayerPlayState:
             'shuffle_state': self._ShuffleState,
             'smart_shuffle': self._SmartShuffle,
             'timestamp': self._Timestamp,
+            'item_type': self._ItemType,
             'item': item,
         }
         return result
@@ -282,13 +394,16 @@ class PlayerPlayState:
         msg:str = 'PlayerPlayState:'
         #if self._Actions is not None: msg = '%s\n %s' % (msg, str(self._Actions))
         if self._CurrentlyPlayingType is not None: msg = '%s\n CurrentlyPlayingType="%s"' % (msg, str(self._CurrentlyPlayingType))
+        if self._ItemType is not None: msg = '%s\n ItemType="%s"' % (msg, str(self._ItemType))
         if self._Device is not None: msg = '%s\n Device Name="%s"' % (msg, str(self._Device.Name))
         #if self._Context is not None: msg = '%s\n %s' % (msg, str(self._Context))
         #if self._Item is not None: msg = '%s\n %s' % (msg, str(self._Item))
+        if self.IsMuted is not None: msg = '%s\n IsMuted="%s"' % (msg, str(self.IsMuted))
         if self._IsPlaying is not None: msg = '%s\n IsPlaying="%s"' % (msg, str(self._IsPlaying))
         if self._ProgressMS is not None: msg = '%s\n ProgressMS="%s"' % (msg, str(self._ProgressMS))
         if self._RepeatState is not None: msg = '%s\n RepeatState="%s"' % (msg, str(self._RepeatState))
         if self._ShuffleState is not None: msg = '%s\n ShuffleState="%s"' % (msg, str(self._ShuffleState))
         if self._SmartShuffle is not None: msg = '%s\n SmartShuffle="%s"' % (msg, str(self._SmartShuffle))
         if self._Timestamp is not None: msg = '%s\n Timestamp="%s"' % (msg, str(self._Timestamp))
+        msg = '%s\n IsEmpty="%s"' % (msg, str(self.IsEmpty))
         return msg 

spotifywebapipython/models/playerqueueinfo.py

@@ -24,6 +24,7 @@ class PlayerQueueInfo:
         """
         self._CurrentlyPlaying:object = None
         self._CurrentlyPlayingType:str = None
+        self._DateLastRefreshed:float = 0
         self._Queue:list[object] = []
         
         if (root is None):
@@ -42,15 +43,25 @@ class PlayerQueueInfo:
                 elif self._CurrentlyPlayingType == 'episode':
                     self._CurrentlyPlaying = Episode(root=item)
 
+            # for some reason, the Spotify Web API will return up to 10 duplicate items 
+            # with the same information!  for example:
+            # - if there is only 1 item in the queue, then 10 duplicate items are returned by the Spotify Web API.
+            # - if there are 5 items in the queue, then 5 duplicate items are returned by the Spotify Web API.
+            # we will check for this scenario, and only return non-duplicate items if so.
             items:list = root.get('queue',None)
             if items is not None:
                 for item in items:
+                    
                     itemType = item.get('type','unknown')
                     if itemType == 'track':
-                        self._Queue.append(Track(root=item))
+                        track:Track = Track(root=item)
+                        if (track) and (not self.ContainsUri(track.Uri)):
+                            self._Queue.append(track)
                     elif itemType == 'episode':
-                        self._Queue.append(Episode(root=item))
-        
+                        episode:Episode = Episode(root=item)
+                        if (episode) and (not self.ContainsUri(episode.Uri)):
+                            self._Queue.append(episode)
+                        
 
     def __repr__(self) -> str:
         return self.ToString()
@@ -78,6 +89,30 @@ class PlayerQueueInfo:
         return self._CurrentlyPlayingType
 
 
+    @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 Queue(self) -> list[object]:
         """ 
@@ -122,6 +157,26 @@ class PlayerQueueInfo:
         return result
 
 
+    def ContainsUri(self, uri:str) -> bool:
+        """
+        Checks the `Queue` collection to see if an item already exists with the
+        specified Uri value.
+        
+        Returns True if the specified Uri value exists in the collection; otherwise, False.
+        """
+        result:bool = False
+        
+        if (uri is None):
+            return result
+        
+        for item in self._Queue:
+            if item.Uri == uri:
+                result = True
+                break
+            
+        return result
+        
+
     def ToDictionary(self) -> dict:
         """
         Returns a dictionary representation of the class.
@@ -132,8 +187,9 @@ class PlayerQueueInfo:
             
         result:dict = \
         {
-            'currently_playing': currentlyPlaying,
+            'date_last_refreshed': self._DateLastRefreshed,
             'currently_playing_type': self._CurrentlyPlayingType,
+            'currently_playing': currentlyPlaying,
             'queue': [ item.ToDictionary() for item in self._Queue ],
         }
         return result
@@ -146,4 +202,5 @@ class PlayerQueueInfo:
         msg:str = 'PlayerQueueInfo:'
         if self._CurrentlyPlayingType is not None: msg = '%s\n CurrentlyPlayingType="%s"' % (msg, str(self._CurrentlyPlayingType))
         if self.QueueCount is not None: msg = '%s\n QueueCount="%s"' % (msg, str(self.QueueCount))
+        msg = '%s\n DateLastRefreshed=%s' % (msg, str(self._DateLastRefreshed))
         return msg 

spotifywebapipython/models/playhistorypage.py

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

spotifywebapipython/models/playlist.py

@@ -31,7 +31,10 @@ class Playlist(PlaylistSimplified):
 
         if (root is None):
 
-            pass
+            # if not building the class from json response, then initialize various properties as 
+            # the playlist is probably being built manually.
+            self._Followers = Followers()
+            self._Tracks = PlaylistPage()
         
         else:
 
@@ -73,9 +76,9 @@ class Playlist(PlaylistSimplified):
 
     def GetTracks(self) -> list[Track]:
         """ 
-        Gets a list of all tracks contained in the underlying `Items` list.
+        Gets a list of all tracks contained in the underlying `Tracks.Items` list.
         
-        This is a convenience method so one does not have to loop through the `Items`
+        This is a convenience method so one does not have to loop through the `Tracks.Items`
         array of PlaylistPage objects to get the list of tracks.
         """
         result:list[Track] = []

spotifywebapipython/models/playlistpage.py

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

spotifywebapipython/models/playlistpagesimplified.py

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

spotifywebapipython/models/playlistsimplified.py

@@ -38,7 +38,10 @@ class PlaylistSimplified:
 
         if (root is None):
 
-            pass
+            # if not building the class from json response, then initialize various properties as 
+            # the playlist is probably being built manually.
+            self._ExternalUrls = ExternalUrls()
+            self._Tracks = PlaylistTrackSummary()
         
         else:
 
@@ -116,6 +119,14 @@ class PlaylistSimplified:
         Only returned for modified, verified playlists; otherwise null.
         """
         return self._Description
+
+    @Description.setter
+    def Description(self, value:str):
+        """ 
+        Sets the Description property value.
+        """
+        if isinstance(value, str):
+            self._Description = value
     
 
     @property
@@ -137,12 +148,20 @@ class PlaylistSimplified:
     @property
     def Id(self) -> str:
         """ 
-        The Spotify user ID for the playlist.
+        The Spotify ID for the playlist.
         
         Example: `5v5ETK9WFXAnGQ3MRubKuE`
         """
         return self._Id
 
+    @Id.setter
+    def Id(self, value:str):
+        """ 
+        Sets the Id property value.
+        """
+        if isinstance(value, str):
+            self._Id = value
+    
 
     @property
     def Images(self) -> list[ImageObject]:
@@ -159,12 +178,10 @@ class PlaylistSimplified:
     @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
@@ -174,6 +191,14 @@ class PlaylistSimplified:
         """
         return self._Name
     
+    @Name.setter
+    def Name(self, value:str):
+        """ 
+        Sets the Name property value.
+        """
+        if isinstance(value, str):
+            self._Name = value
+    
 
     @property
     def Owner(self) -> Owner:
@@ -219,6 +244,14 @@ class PlaylistSimplified:
         """
         return self._Type
 
+    @Type.setter
+    def Type(self, value:str):
+        """ 
+        Sets the Type property value.
+        """
+        if isinstance(value, str):
+            self._Type = value
+    
 
     @property
     def Uri(self) -> str:
@@ -229,6 +262,14 @@ class PlaylistSimplified:
         """
         return self._Uri
     
+    @Uri.setter
+    def Uri(self, value:str):
+        """ 
+        Sets the Uri property value.
+        """
+        if isinstance(value, str):
+            self._Uri = value
+    
 
     def ToDictionary(self) -> dict:
         """
@@ -253,6 +294,7 @@ class PlaylistSimplified:
             'external_urls': externalUrls,
             'href': self._Href,
             'id': self._Id,
+            'image_url': self.ImageUrl,
             'images': [ item.ToDictionary() for item in self._Images ],
             'name': self._Name,
             'owner': owner,

spotifywebapipython/models/playlisttrack.py

@@ -116,6 +116,7 @@ class PlaylistTrack:
         {
             'added_at': self._AddedAt,
             'added_by': addedBy,
+            'image_url': self.ImageUrl,
             'is_local': self._IsLocal,
             'track': track
         }

spotifywebapipython/models/playlisttracksummary.py

@@ -23,7 +23,9 @@ class PlaylistTrackSummary:
         
         if (root is None):
 
-            pass
+            # if not building the class from json response, then initialize various properties as 
+            # the playlist is probably being built manually.
+            self._Total = 0
         
         else:
 

spotifywebapipython/models/searchresponse.py

@@ -106,7 +106,7 @@ class SearchResponse:
         return self._Albums
     
     @Albums.setter
-    def Albums(self, value:str):
+    def Albums(self, value:AlbumPageSimplified):
         """ 
         Sets the Albums property value.
         """

spotifywebapipython/models/showpagesaved.py

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

spotifywebapipython/models/showpagesimplified.py

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

spotifywebapipython/models/showsaved.py

@@ -51,8 +51,8 @@ class ShowSaved:
         
         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/showsimplified.py

@@ -130,7 +130,7 @@ class ShowSimplified:
     @property
     def Explicit(self) -> bool:
         """ 
-        Whether or not the show has explicit lyrics (true = yes it does; false = no it does not OR unknown).
+        Whether or not the show has explicit content (true = yes it does; false = no it does not OR unknown).
         """
         return self._Explicit
 
@@ -147,6 +147,7 @@ class ShowSimplified:
     def Href(self) -> str:
         """ 
         A link to the Web API endpoint providing full details of the show.
+        Example: `https://api.spotify.com/v1/shows/3IM0lmZxpFAY7CwMuv9H4g?locale=en-US%2Cen%3Bq%3D0.9`
         """
         return self._Href
 
@@ -164,6 +165,7 @@ class ShowSimplified:
     def Id(self) -> str:
         """ 
         The Spotify ID for the show.
+        Example: `3IM0lmZxpFAY7CwMuv9H4g`
         """
         return self._Id
 
@@ -182,10 +184,8 @@ class ShowSimplified:
         Gets the first image url in 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
     def IsExternallyHosted(self) -> bool:
@@ -210,6 +210,8 @@ class ShowSimplified:
     def MediaType(self) -> str:
         """ 
         The media type of the show.
+        
+        Example: `audio`
         """
         return self._MediaType
 
@@ -272,6 +274,7 @@ class ShowSimplified:
             '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,
             'languages': [ item for item in self._Languages ],