spotifywebapiPython 1.0.112__py3-none-any.whl → 1.0.114__py3-none-any.whl

spotifywebapipython/models/playerqueueinfo.py

@@ -42,15 +42,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()
@@ -122,6 +132,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 +162,8 @@ class PlayerQueueInfo:
             
         result:dict = \
         {
-            'currently_playing': currentlyPlaying,
             'currently_playing_type': self._CurrentlyPlayingType,
+            'currently_playing': currentlyPlaying,
             'queue': [ item.ToDictionary() for item in self._Queue ],
         }
         return result

spotifywebapipython/models/trackpage.py

@@ -58,6 +58,46 @@ class TrackPage(PageObject):
         return self._Items
     
 
+    def GetUris(self, afterUri:str=None) -> str:
+        """ 
+        Gets a comma-delimited list of uri's contained in the underlying `Items` list.
+        
+        args:
+            afterUri (str):
+                If specified, the process will look for this uri before adding subsequent
+                uri's to the returned results.  This allows you to skip uri's that have
+                recently been played.
+        
+        This is a convenience method so one does not have to loop through the `Items`
+        array of PlayHistory objects to get the list of uri's.
+        """
+        result:str = ""
+        addUri:bool = False
+        item:Track
+
+        # add uri's from the beginning if no `afterUri` argument was passed.
+        if (afterUri is None) or (len(afterUri.strip()) == 0):
+            addUri = True
+        
+        for item in self._Items:
+
+            if (not addUri):
+
+                # check for `afterUri` match; if found, we will start adding uri's
+                # to the list with the next item.
+                if (afterUri == item.Uri):
+                    addUri = True
+                    
+            elif (addUri):
+                
+                # add item uri to the list.
+                if (len(result) > 0):
+                    result += ","
+                result += item.Uri
+                
+        return result
+    
+
     def ToString(self, includeItems:bool=False) -> str:
         """
         Returns a displayable string representation of the class.

spotifywebapipython/spotifyclient.py

@@ -839,6 +839,8 @@ class SpotifyClient:
                            deviceId:str=None
                            ) -> None:
         """
+        DEPRECATED - use `AddPlayerQueueItems` method instead.
+        
         Add an item to the end of the user's current playback queue. 
         
         This method requires the `user-modify-playback-state` scope.
@@ -863,13 +865,6 @@ class SpotifyClient:
         This API only works for users who have Spotify Premium. 
         
         The order of execution is not guaranteed when you use this API with other Player API endpoints.
-        
-        <details>
-          <summary>Sample Code</summary>
-        ```python
-        .. include:: ../docs/include/samplecode/SpotifyClient/AddPlayerQueueItem.py
-        ```
-        </details>
         """
         apiMethodName:str = 'AddPlayerQueueItem'
         apiMethodParms:SIMethodParmListContext = None
@@ -921,6 +916,140 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
+    def AddPlayerQueueItems(
+            self, 
+            uris:str,
+            deviceId:str=None,
+            verifyDeviceId:bool=True,
+            delay:float=0.15,
+            ) -> None:
+        """
+        Add one or more items to the end of the user's current playback queue. 
+        
+        This method requires the `user-modify-playback-state` scope.
+
+        Args:
+            uris (str):
+                A list of Spotify track or episode URIs to add to the queue; can be track or episode URIs.  
+                All URIs must be of the same type - you cannot mix and match tracks and episodes!  
+                Example: [`spotify:track:6zd8T1PBe9JFHmuVnurdRp` ,`spotify:track:1kWUud3vY5ij5r62zxpTRy`].  
+                It can also be specified as a comma-delimited string.  
+                Example: `spotify:track:6zd8T1PBe9JFHmuVnurdRp,spotify:track:1kWUud3vY5ij5r62zxpTRy`.  
+                An unlimited number of items can be added in one request, but the more items the longer it
+                will take.
+            deviceId (str):
+                The id or name of the device this command is targeting.  
+                If not supplied, the user's currently active device is the target.  
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
+            verifyDeviceId (bool):
+                True to verify a device id is active; otherwise, false to assume that a
+                device id is already active.  
+                Default is True.  
+            delay (float):
+                Time delay (in seconds) to wait AFTER issuing the add request.  This delay will give the 
+                Spotify web api time to process the queue change before another command is issued.  
+                Default is 0.15; value range is 0 - 10.
+                
+        Raises:
+            SpotifyWebApiError: 
+                If the Spotify Web API request was for a non-authorization service 
+                and the response contains error information.
+            SpotifApiError: 
+                If the method fails for any other reason.
+
+        This API only works for users who have Spotify Premium. 
+        
+        The order of execution is not guaranteed when you use this API with other Player API endpoints.
+        
+        The Spotify Web API endpoint is called to add each item individually.  
+        The Spotify Web API does not currently support adding more than 1 item to the queue at a time.
+        
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/AddPlayerQueueItems.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'AddPlayerQueueItems'
+        apiMethodParms:SIMethodParmListContext = None
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("uris", uris)
+            apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("verifyDeviceId", verifyDeviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Add items to playback queue", apiMethodParms)
+            
+            # validations.
+            delay = validateDelay(delay, 0.15, 10)
+            if (verifyDeviceId is None):
+                verifyDeviceId = True
+
+            # build a list of all item uri's.
+            # remove any leading / trailing spaces in case user put a space between the items.
+            arrUris:list[str] = None
+            if isinstance(uris, list):
+                arrUris = uris
+            else:
+                arrUris = uris.split(',')
+                for idx in range(0, len(arrUris)):
+                    arrUris[idx] = arrUris[idx].strip()
+                
+            # if deviceId was not specified, then verify that there is an active player device.
+            if verifyDeviceId:    
+                if deviceId is None:
+                    deviceId:str = self.VerifyPlayerActiveDeviceId()
+
+            # check for device name; convert to an id if a name was supplied.
+            if verifyDeviceId:    
+                deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+                
+            # process all uri's.
+            for idx in range(0, len(arrUris)):
+                
+                # build spotify web api request parameters.
+                urlParms:dict = \
+                {
+                    'uri': arrUris[idx]
+                }
+                if deviceId is not None:
+                    urlParms['device_id'] = deviceId
+
+                # execute spotify web api request.
+                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/queue')
+                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                msg.UrlParameters = urlParms
+                self.MakeRequest('POST', msg)
+
+                # give spotify web api time to process the change.
+                if delay > 0:
+                    _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % delay)
+                    time.sleep(delay)
+
+            
+            # process results.
+            # no results to process - this is pass or fail.
+            return
+
+        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 AddPlaylistCoverImage(self, 
                               playlistId:str, 
                               imagePath:str
@@ -2728,7 +2857,8 @@ class SpotifyClient:
                     
             # update result object with final paging details.
             result.Total = pageObj.Total
-
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
+            
             # sort result items.
             if (len(result.Items) > 0):
                 if (sortResult is True):
@@ -2895,6 +3025,7 @@ class SpotifyClient:
                     
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -3162,6 +3293,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # do not sort items, as they are in playable order.
 
@@ -3429,6 +3561,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -3730,6 +3863,7 @@ class SpotifyClient:
     def GetArtistRelatedArtists(
             self, 
             artistId:str=None, 
+            sortResult:bool=True,
             ) -> list[Artist]:
         """
         Get Spotify catalog information about artists similar to a given artist.  
@@ -3741,6 +3875,10 @@ class SpotifyClient:
                 Example: `6APm8EjxOHSYM5B4i3vT3q`
                 If null, the currently playing artist uri id value is used; a Spotify Free or Premium account 
                 is required to correctly read the currently playing context.
+            sortResult (bool):
+                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
                 
         Returns:
             A list of `Artist` objects that contain the artist details.
@@ -3768,8 +3906,13 @@ class SpotifyClient:
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("artistId", artistId)
+            apiMethodParms.AppendKeyValue("sortResult", sortResult)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify catalog information about artists similar to a given artist", apiMethodParms)
-                
+
+            # validations.
+            if sortResult is None: 
+                sortResult = True
+
             # if artistId not specified, then return currently playing artist id value.
             if (artistId is None) or (len(artistId.strip()) == 0):
                 uri = self.GetPlayerNowPlayingArtistUri()
@@ -3789,6 +3932,11 @@ class SpotifyClient:
                 for item in items:
                     result.append(Artist(root=item))
         
+            # sort result items.
+            if (len(result) > 0):
+                if (sortResult is True):
+                    result.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
+        
             # trace.
             _logsi.LogArray(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, 'list[Artist]'), result)
             return result
@@ -4021,6 +4169,7 @@ class SpotifyClient:
             # update result object with final paging details.
             result.Total = pageObj.Total
             result.CursorAfter = pageObj.CursorAfter
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -4049,6 +4198,7 @@ class SpotifyClient:
             self, 
             artistId:str=None, 
             market:str=None, 
+            sortResult:bool=True,
             ) -> list[Track]:
         """
         Get Spotify catalog information about an artist's top tracks by country.
@@ -4067,6 +4217,10 @@ class SpotifyClient:
                 Note: If neither market or user country are provided, the content is considered unavailable for the client.  
                 Users can view the country that is associated with their account in the account settings.  
                 Example: `ES`
+            sortResult (bool):
+                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
                 
         Returns:
             A list of `Track` objects that contain the track details.
@@ -4095,8 +4249,13 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("artistId", artistId)
             apiMethodParms.AppendKeyValue("market", market)
+            apiMethodParms.AppendKeyValue("sortResult", sortResult)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify catalog information about an artist's top tracks", apiMethodParms)
                 
+            # validations.
+            if sortResult is None: 
+                sortResult = True
+            
             # ensure market was either supplied or implied; default if neither.
             market = self._ValidateMarket(market)
 
@@ -4125,6 +4284,11 @@ class SpotifyClient:
                 for item in items:
                     result.append(Track(root=item))
         
+            # sort result items.
+            if (len(result) > 0):
+                if (sortResult is True):
+                    result.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
+        
             # trace.
             _logsi.LogArray(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, 'list[Track]'), result)
             return result
@@ -4401,6 +4565,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # no sorting, as chapters are in playable order.
 
@@ -4553,6 +4718,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -4946,6 +5112,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -5231,6 +5398,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -5692,6 +5860,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -5984,6 +6153,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -7391,6 +7561,7 @@ class SpotifyClient:
             result.Total = result.ItemsCount
             result.CursorAfter = pageObj.CursorAfter
             result.CursorBefore = pageObj.CursorBefore
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # trace.
             _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
@@ -7814,6 +7985,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # do not sort this list, as it is in play order.
             
@@ -7966,6 +8138,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -8127,6 +8300,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -8407,6 +8581,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # no sort, as items are in playable order.
 
@@ -8586,6 +8761,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -9562,6 +9738,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -10490,6 +10667,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -10656,6 +10834,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # sort result items.
             if (len(result.Items) > 0):
@@ -11284,6 +11463,25 @@ class SpotifyClient:
                 # if so, then use the found device id in case a device name was specified.
                 if scDevice is not None:
                     deviceId = scDevice.Id
+                    
+            # left this here in case we want to implement it in the future.
+                    
+            # # are we backfilling the player queue? if so, we can only have 50 uris total.
+            # if (backfillUrisPageOffset > -1) and (len(arrUris) < 50):
+
+            #     # are we playing tracks?
+            #     if (len(arrUris) > 0) and (SpotifyClient.GetTypeFromUri(arrUris[0]) == 'track'):
+                    
+            #         _logsi.LogVerbose("Backfilling player queue items from users top tracks")
+                
+            #         # get list of users top tracks (50 max items).
+            #         pageObj:TrackPage = self.GetUsersTopTracks(timeRange='medium_term', offset=backfillUrisPageOffset, limit=(50 - len(arrUris)), sortResult=False)
+                
+            #         # add them to the player queue; no need to validate the device id, since we
+            #         # know there is an active device id by this point.
+            #         item:Track
+            #         for item in pageObj.Items:
+            #             arrUris.append(item.Uri)
 
             # build spotify web api request parameters.
             reqData:dict = \
@@ -11308,7 +11506,7 @@ class SpotifyClient:
             if delay > 0:
                 _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % delay)
                 time.sleep(delay)
-
+                
             # process results.
             # no results to process - this is pass or fail.
             return
@@ -14029,6 +14227,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # do not sort, as spotify uses intelligent AI to return results in its order.
 
@@ -14221,6 +14420,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # do not sort, as spotify uses intelligent AI to return results in its order.
 
@@ -14415,6 +14615,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # do not sort, as spotify uses intelligent AI to return results in its order.
 
@@ -14607,6 +14808,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # do not sort, as spotify uses intelligent AI to return results in its order.
 
@@ -14799,6 +15001,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # do not sort, as spotify uses intelligent AI to return results in its order.
 
@@ -14991,6 +15194,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # do not sort, as spotify uses intelligent AI to return results in its order.
 
@@ -15183,6 +15387,7 @@ class SpotifyClient:
 
             # update result object with final paging details.
             result.Total = pageObj.Total
+            result.DateLastRefreshed = datetime.utcnow().timestamp()
 
             # do not sort, as spotify uses intelligent AI to return results in its order.