spotifywebapiPython 1.0.101__py3-none-any.whl → 1.0.103__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -2656,6 +2656,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -2822,6 +2824,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -3344,6 +3348,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -3923,6 +3929,8 @@ class SpotifyClient:
                 limit = 20
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -4464,6 +4472,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -4849,6 +4859,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -5130,6 +5142,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -5586,6 +5600,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -5867,6 +5883,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -6648,6 +6666,10 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get user's available Spotify Connect player devices", apiMethodParms)
 
+            # validations.
+            if sortResult is None: 
+                sortResult = True
+
             # can we use the cached value?
             if (not refresh) and (apiMethodName in self._ConfigurationCache):
                 
@@ -7853,6 +7875,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -8011,6 +8035,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -8372,6 +8398,7 @@ class SpotifyClient:
             offset:int=0,
             limitTotal:int=None,
             sortResult:bool=True,
+            excludeAudiobooks:bool=True,
             ) -> ShowPageSaved:
         """
         Get a list of the shows saved in the current Spotify user's 'Your Library'.
@@ -8397,6 +8424,10 @@ 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
+            excludeAudiobooks (bool):
+                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  
                 
         Returns:
             An `ShowPageSaved` object that contains saved show information.
@@ -8407,6 +8438,11 @@ class SpotifyClient:
                 and the response contains error information.
             SpotifApiError: 
                 If the method fails for any other reason.
+                
+        For some reason, Spotify Web API returns audiobooks AND podcasts with the `/me/shows` service.
+        Spotify Web API returns only audiobooks with the `/me/audiobooks` service.
+        The reasoning for that is unclear, but the `excludeAudiobooks` argument allows you to
+        only return podcast shows in the results if desired.
 
         <details>
           <summary>Sample Code - Manual Paging</summary>
@@ -8433,6 +8469,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("offset", offset)
             apiMethodParms.AppendKeyValue("limitTotal", limitTotal)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
+            apiMethodParms.AppendKeyValue("excludeAudiobooks", excludeAudiobooks)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of the users show favorites", apiMethodParms)
                 
             # validations.
@@ -8442,6 +8479,10 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
+            if excludeAudiobooks is None: 
+                excludeAudiobooks = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -8493,6 +8534,20 @@ class SpotifyClient:
                     if not self._CheckForNextPageWithOffset(pageObj, result.ItemsCount, limit, limitTotal, urlParms):
                         break
 
+            # exclude audiobook shows if requested.
+            if (excludeAudiobooks):
+
+                item:ShowSaved
+                idx:int = 0
+                while idx < len(result.Items):
+                    if (result.Items[idx].Show is not None) \
+                    and (result.Items[idx].Show.Description is not None) \
+                    and (result.Items[idx].Show.Description.startswith('Author(s):')):
+                        del result.Items[idx]
+                        pageObj.Total -= 1
+                    else:
+                        idx += 1
+
             # update result object with final paging details.
             result.Total = pageObj.Total
 
@@ -8991,7 +9046,11 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("refresh", refresh)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get available Spotify Connect devices", apiMethodParms)
-                
+
+            # validations.
+            if sortResult is None: 
+                sortResult = True
+
             # can we use the cached value?
             if (not refresh) and (apiMethodName in self._ConfigurationCache):
                 
@@ -9399,6 +9458,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -10329,6 +10390,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -10493,6 +10556,8 @@ class SpotifyClient:
                 offset = 0
             if not isinstance(limitTotal, int):
                 limitTotal = 0
+            if sortResult is None: 
+                sortResult = True
                 
             # are we auto-paging?  if so, then use max limit.
             if limitTotal > 0: 
@@ -11312,11 +11377,13 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
-    def PlayerMediaSeek(self, 
-                        positionMS:int=0,
-                        deviceId:str=None,
-                        delay:float=0.50
-                        ) -> None:
+    def PlayerMediaSeek(
+            self, 
+            positionMS:int=0,
+            deviceId:str=None,
+            delay:float=0.50,
+            relativePositionMS:int=0,
+            ) -> None:
         """
         Seeks to the given position in the user's currently playing track for the specified 
         Spotify Connect device.
@@ -11339,6 +11406,11 @@ class SpotifyClient:
                 This delay will give the spotify web api time to process the change before 
                 another command is issued.  
                 Default is 0.50; value range is 0 - 10.
+            relativePositionMS (int):
+                The relative position in milliseconds to seek to; can be a positive or negative number.  
+                Passing in a positive relative position that causes the position to be greater than the 
+                length of the track will cause the player to start playing the next song.
+                Example: `25000`  
                 
         Raises:
             SpotifyWebApiError: 
@@ -11351,12 +11423,24 @@ class SpotifyClient:
         
         The order of execution is not guaranteed when you use this API with other Player API endpoints.
         
+        Note that the `relativePositionMS` functionality is not defined by the Spotify Web API.  This
+        argument was added to this API to support "skip" seeking.  A positive relative position that causes 
+        the seek position to be greater than the length of the track will cause the player to start playing 
+        the next song.  A negative relative position that causes the seek position to be less than zero 
+        will cause the player to start playing the track from the beginning.
+        
         <details>
           <summary>Sample Code</summary>
         ```python
         .. include:: ../docs/include/samplecode/SpotifyClient/PlayerMediaSeek.py
         ```
         </details>
+        <details>
+          <summary>Sample Code - Relative Positioning</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/PlayerMediaSeek_Relative.py
+        ```
+        </details>
         """
         apiMethodName:str = 'PlayerMediaSeek'
         apiMethodParms:SIMethodParmListContext = None
@@ -11368,10 +11452,15 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("positionMS", positionMS)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
             apiMethodParms.AppendKeyValue("delay", delay)
+            apiMethodParms.AppendKeyValue("relativePositionMS", relativePositionMS)
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device seek position", apiMethodParms)
                 
             # validations.
             delay = validateDelay(delay, 0.50, 10)
+            if (positionMS is None):
+                positionMS = 0
+            if (relativePositionMS is None):
+                relativePositionMS = 0
 
             # if deviceId was not specified, then verify that there is an active player device.
             if deviceId is None:
@@ -11379,6 +11468,20 @@ class SpotifyClient:
 
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+            
+            # was relative seeking specified?
+            if (relativePositionMS != 0) and (positionMS == 0):
+                
+                # get current track position.
+                playState:PlayerPlayState = self.GetPlayerPlaybackState()
+                newPositionMS:int = playState.ProgressMS
+                if (newPositionMS is not None) and (newPositionMS > 0):
+                    
+                    # calculate new position; if less than zero, then force it to zero.
+                    newPositionMS += relativePositionMS
+                    if (newPositionMS < 0):
+                        newPositionMS = 0
+                    positionMS = newPositionMS
 
             # build spotify web api request parameters.
             urlParms:dict = \