spotifywebapiPython 1.0.121__py3-none-any.whl → 1.0.123__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -2333,7 +2333,13 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("collaborative", collaborative)
             apiMethodParms.AppendKeyValue("imagePath", imagePath)
             _logsi.LogMethodParmList(SILevel.Verbose, "Create an empty playlist for a user", apiMethodParms)
-                
+
+            # validations.
+            if (public is None):
+                public = True
+            if (collaborative is None):
+                collaborative = False
+
             # if userId is not supplied, then use profile value.
             if userId is None or len(userId.strip()) == 0:
                 userId = self.UserProfile.Id
@@ -2489,7 +2495,7 @@ class SpotifyClient:
             public (bool):
                 If true the playlist will be included in user's public playlists, if false it 
                 will remain private.  
-                Default = True. 
+                Default is True. 
                 
         Raises:
             SpotifyWebApiError: 
@@ -2515,6 +2521,10 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("playlistId", playlistId)
             apiMethodParms.AppendKeyValue("public", public)
             _logsi.LogMethodParmList(SILevel.Verbose, "Add the current user as a follower of a playlist", apiMethodParms)
+            
+            # validations.
+            if (public is None):
+                public = True
                 
             # if playlistId not specified, then return currently playing playlist id value.
             if (playlistId is None) or (len(playlistId.strip()) == 0):
@@ -3943,6 +3953,13 @@ class SpotifyClient:
             sortResult:bool=True,
             ) -> list[Artist]:
         """
+        <span class="deprecated">
+            DEPRECATED - api endpoint no longer supported by Spotify as of 2024/11/27.
+            More information about the deprecated functionality can be found on the 
+            <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api" target="_blank">Spotify Developer Forum Blog</a>
+            page.
+        </span>       
+        
         Get Spotify catalog information about artists similar to a given artist.  
         Similarity is based on analysis of the Spotify community's listening history.
         
@@ -3985,6 +4002,9 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("artistId", artistId)
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify catalog information about artists similar to a given artist", apiMethodParms)
+            
+            # api endpoint no longer supported by Spotify as of 2024/11/27.
+            raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_DEPRECATED_ENDPOINT % apiMethodName)
 
             # validations.
             if sortResult is None: 
@@ -4986,6 +5006,10 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("locale", locale)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a single category used to tag items in Spotify", apiMethodParms)
                 
+            # validations.
+            if (refresh is None):
+                refresh = True
+                
             # can we use a cached value?
             cacheKey:str = "GetBrowseCategorys"
             if (not refresh) and (cacheKey in self._ConfigurationCache):
@@ -5277,6 +5301,10 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("refresh", refresh)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a sorted list of ALL browse categories", apiMethodParms)
                 
+            # validations.
+            if (refresh is None):
+                refresh = True
+                
             # can we use the cached value?
             if (not refresh) and (apiMethodName in self._ConfigurationCache):
                 
@@ -5324,6 +5352,13 @@ class SpotifyClient:
             sortResult:bool=True,
             ) -> Tuple[PlaylistPageSimplified, str]:
         """
+        <span class="deprecated">
+            DEPRECATED - api endpoint no longer supported by Spotify as of 2024/11/27.
+            More information about the deprecated functionality can be found on the 
+            <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api" target="_blank">Spotify Developer Forum Blog</a>
+            page.
+        </span>       
+        
         Get a list of Spotify playlists tagged with a particular category.
         
         Args:
@@ -5405,6 +5440,9 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of Spotify playlists tagged with a particular category", apiMethodParms)
                 
+            # api endpoint no longer supported by Spotify as of 2024/11/27.
+            raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_DEPRECATED_ENDPOINT % apiMethodName)
+
             # validations.
             if limit is None: 
                 limit = 20
@@ -5564,6 +5602,10 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("ignoreResponseErrors", ignoreResponseErrors)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify catalog information for a single audiobook chapter", apiMethodParms)
                 
+            # validations.
+            if (ignoreResponseErrors is None):
+                ignoreResponseErrors = False
+                
             # ensure market was either supplied or implied; default if neither.
             market = self._ValidateMarket(market)
 
@@ -6071,6 +6113,13 @@ class SpotifyClient:
             sortResult:bool=True,
             ) -> Tuple[PlaylistPageSimplified, str]:
         """
+        <span class="deprecated">
+            DEPRECATED - api endpoint no longer supported by Spotify as of 2024/11/27.
+            More information about the deprecated functionality can be found on the 
+            <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api" target="_blank">Spotify Developer Forum Blog</a>
+            page.
+        </span>       
+        
         Get a list of Spotify featured playlists (shown, for example, on a Spotify player's 'Browse' tab).
         
         Args:
@@ -6159,6 +6208,9 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("sortResult", sortResult)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get a list of Spotify featured playlists", apiMethodParms)
                 
+            # api endpoint no longer supported by Spotify as of 2024/11/27.
+            raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_DEPRECATED_ENDPOINT % apiMethodName)
+
             # validations.
             if limit is None: 
                 limit = 20
@@ -6259,6 +6311,13 @@ class SpotifyClient:
                   refresh:bool=True
                   ) -> list[str]:
         """
+        <span class="deprecated">
+            DEPRECATED - api endpoint no longer supported by Spotify as of 2024/11/27.
+            More information about the deprecated functionality can be found on the 
+            <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api" target="_blank">Spotify Developer Forum Blog</a>
+            page.
+        </span>       
+        
         Get a sorted list of available genres seed parameter values.
         
         Args:
@@ -6297,6 +6356,13 @@ class SpotifyClient:
             _logsi.EnterMethod(SILevel.Debug, apiMethodName)
             _logsi.LogVerbose("Get a sorted list of available genres")
                 
+            # api endpoint no longer supported by Spotify as of 2024/11/27.
+            raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_DEPRECATED_ENDPOINT % apiMethodName)
+
+            # validations.
+            if (refresh is None):
+                refresh = True
+                
             # can we use the cached value?
             if (not refresh) and (apiMethodName in self._ConfigurationCache):
                 
@@ -6416,6 +6482,10 @@ class SpotifyClient:
             _logsi.EnterMethod(SILevel.Debug, apiMethodName)
             _logsi.LogVerbose("Get a sorted list of available markets (country codes)")
             
+            # validations.
+            if (refresh is None):
+                refresh = True
+                
             # can we use the cached value?
             if (not refresh) and (apiMethodName in self._ConfigurationCache):
                 
@@ -6556,6 +6626,8 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Get user's available Spotify Connect player device", apiMethodParms)
             
             # validations.
+            if (refresh is None):
+                refresh = True
             if deviceId is None:
                 return None
             deviceId = deviceId.lower()  # prepare for compare
@@ -6833,6 +6905,10 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("refresh", refresh)
             _logsi.LogMethodParmList(SILevel.Verbose, "Checking Spotify Connect Player device for name", apiMethodParms)
 
+            # validations.
+            if (refresh is None):
+                refresh = False
+                
             # if nothing specified then just use it as-is.
             if (value is None) or (len(value.strip()) == 0):
                 _logsi.LogVerbose("Device ID not specified; active device will be used")
@@ -6942,6 +7018,8 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Get user's available Spotify Connect player devices", apiMethodParms)
 
             # validations.
+            if (refresh is None):
+                refresh = True
             if sortResult is None: 
                 sortResult = True
 
@@ -7180,6 +7258,10 @@ class SpotifyClient:
         """
         result:str = None
         
+        # validations.
+        if (ignoreResponseErrors is None):
+            ignoreResponseErrors = False
+                
         # get nowplaying status.
         nowPlaying:PlayerPlayState = self.GetPlayerNowPlaying(market, additionalTypes='episode')
         
@@ -9006,7 +9088,8 @@ class SpotifyClient:
                 Default is 5; value range is 0 - 10.
             refreshDeviceList (bool):
                 True to refresh the Spotify Connect device list; otherwise, False to use the 
-                Spotify Connect device list cache.
+                Spotify Connect device list cache.  
+                Default is False.  
             activateDevice (bool):
                 True to activate the device if necessary; otherwise, False.  
                 Default is True.  
@@ -9058,6 +9141,8 @@ class SpotifyClient:
         apiMethodParms:SIMethodParmListContext = None
         deviceResultId:str = None
         deviceResult:SpotifyConnectDevice = None
+        
+        DELAY_DISCONNECT:float = 0.350
 
         try:
             
@@ -9086,6 +9171,10 @@ class SpotifyClient:
             verifyTimeout = validateDelay(verifyTimeout, 5, 10)
             if (not isinstance(verifyUserContext, bool)):
                 verifyUserContext = True
+            if (activateDevice is None):
+                activateDevice = True
+            if (refreshDeviceList is None):
+                refreshDeviceList = False
 
             # determine if the device value specified is a name (e.g. "Bose-ST10-1") or 
             # an id (e.g. "30fbc80e35598f3c242f2120413c943dfd9715fe", "48b677ca-ef9b-516f-b702-93bf2e8c67ba").
@@ -9099,6 +9188,12 @@ class SpotifyClient:
 
             # get all available Spotify Connect devices on the network.
             scDevices:SpotifyConnectDevices = self.GetSpotifyConnectDevices(refresh=refreshDeviceList)
+            
+            # if we refreshed the device list, then give the device(s) a little time to disconnect so that
+            # a new connection can be established (if required).
+            if (refreshDeviceList):
+                _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % DELAY_DISCONNECT)
+                time.sleep(DELAY_DISCONNECT)
 
             # process all discovered devices.
             for scDevice in scDevices:
@@ -9199,7 +9294,17 @@ class SpotifyClient:
                     if (not activateDevice):
                         _logsi.LogVerbose("Activation not requested for Spotify Connect device: '%s'" % (deviceResult.Title))
                         break
-
+                    
+                    # does the device need to be activated?
+                    # check for the device in the available device list.
+                    # if we find it, then there is no need to activate it and we are done.
+                    # note - if another user is controlling the device, then it will not be in the active device list
+                    # for the current user!
+                    device:Device = self.GetPlayerDevice(deviceResultId, refresh=True)
+                    if device is not None:
+                        _logsi.LogVerbose("Spotify Connect device '%s' is already in the available device list; no need to re-activate" % (deviceResult.Title))
+                        break
+                    
                     zcfResult:ZeroconfResponse
                                           
                     # disconnect the device.
@@ -9215,7 +9320,8 @@ class SpotifyClient:
                         # some devices only support a single connection on the spotify connect 
                         # zeroconf webserver, so we have to give it a little time to process the 
                         # disconnect command before we try to call the Connect method.
-                        time.sleep(0.350)
+                        _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % DELAY_DISCONNECT)
+                        time.sleep(DELAY_DISCONNECT)
                     
                     # connect the device to OUR Spotify Connect user context.
                     # note that the result here only indicates that the connect was submitted - NOT that it was successful!
@@ -9356,6 +9462,8 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Get available Spotify Connect devices", apiMethodParms)
 
             # validations.
+            if refresh is None:
+                refresh = True
             if sortResult is None: 
                 sortResult = True
 
@@ -9609,6 +9717,13 @@ class SpotifyClient:
             trackId:str=None, 
             ) -> AudioFeatures:
         """
+        <span class="deprecated">
+            DEPRECATED - api endpoint no longer supported by Spotify as of 2024/11/27.
+            More information about the deprecated functionality can be found on the 
+            <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api" target="_blank">Spotify Developer Forum Blog</a>
+            page.
+        </span>       
+        
         Get audio feature information for a single track identified by its unique Spotify ID.
         
         Args:
@@ -9646,6 +9761,9 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("trackId", trackId)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get audio feature information for a single track", apiMethodParms)
                 
+            # api endpoint no longer supported by Spotify as of 2024/11/27.
+            raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_DEPRECATED_ENDPOINT % apiMethodName)
+
             # if trackId not specified, then return currently playing track id value.
             if (trackId is None) or (len(trackId.strip()) == 0):
                 uri = self.GetPlayerNowPlayingUri('track')
@@ -10042,6 +10160,13 @@ class SpotifyClient:
                                 minValence:float=None, maxValence:float=None, targetValence:float=None
                                 ) -> TrackRecommendations:
         """
+        <span class="deprecated">
+            DEPRECATED - api endpoint no longer supported by Spotify as of 2024/11/27.
+            More information about the deprecated functionality can be found on the 
+            <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api" target="_blank">Spotify Developer Forum Blog</a>
+            page.
+        </span>       
+        
         Get track recommendations for specified criteria.
         
         Use the `GetTrackAudioFeatures` method to get an idea of what to specify for some of the
@@ -10280,6 +10405,9 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("targetValence", targetValence)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get track recommendations for specified criteria", apiMethodParms)
                 
+            # api endpoint no longer supported by Spotify as of 2024/11/27.
+            raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_DEPRECATED_ENDPOINT % apiMethodName)
+
             # ensure market was either supplied or implied; default if neither.
             market = self._ValidateMarket(market)
 
@@ -10511,6 +10639,10 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get profile information about the current user", apiMethodParms)
                 
+            # validations.
+            if (refresh is None):
+                refresh = True
+
             # can we use the cached value?
             if (not refresh) and (apiMethodName in self._ConfigurationCache):
                 
@@ -11268,12 +11400,13 @@ class SpotifyClient:
                 
             # validations.
             delay = validateDelay(delay, 0.50, 10)
+            if (resolveDeviceId is None):
+                resolveDeviceId = True
 
             # has the device id been resolved?
             if (resolveDeviceId):
                 
-                # no - ensure the specified device id / name is active and available, and
-                # the user context is set correctly.
+                # no - ensure the specified device id / name is active and available.
                 scDevice = self.GetSpotifyConnectDevice(
                     deviceId, 
                     refreshDeviceList=False, 
@@ -11397,6 +11530,10 @@ class SpotifyClient:
                 
             # validations.
             delay = validateDelay(delay, 0.50, 10)
+            if (shuffle is None):
+                shuffle = True
+            if (resolveDeviceId is None):
+                resolveDeviceId = True
 
             # get current users favorite tracks.
             tracks:TrackPageSaved = self.GetTrackFavorites(limitTotal=limitTotal)
@@ -11413,8 +11550,7 @@ class SpotifyClient:
             # has the device id been resolved?
             if (resolveDeviceId):
                 
-                # no - ensure the specified device id / name is active and available, and
-                # the user context is set correctly.
+                # no - ensure the specified device id / name is active and available.
                 scDevice = self.GetSpotifyConnectDevice(
                     deviceId, 
                     refreshDeviceList=False, 
@@ -11526,6 +11662,8 @@ class SpotifyClient:
                 
             # validations.
             delay = validateDelay(delay, 0.50, 10)
+            if (resolveDeviceId is None):
+                resolveDeviceId = True
 
             # build a list of all item uri's.
             # remove any leading / trailing spaces in case user put a space between the items.
@@ -11540,8 +11678,7 @@ class SpotifyClient:
             # has the device id been resolved?
             if (resolveDeviceId):
                 
-                # no - ensure the specified device id / name is active and available, and
-                # the user context is set correctly.
+                # no - ensure the specified device id / name is active and available.
                 scDevice = self.GetSpotifyConnectDevice(
                     deviceId, 
                     refreshDeviceList=False, 
@@ -12275,7 +12412,7 @@ class SpotifyClient:
                 The shuffle mode to set: 
                 - `True`  - Shuffle user's playback.
                 - `False` - Do not shuffle user's playback.
-                Default: `False`  
+                Default is False
             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.  
@@ -12540,9 +12677,14 @@ class SpotifyClient:
             
             # validations.
             delay = validateDelay(delay, 0.50, 10)
-            
-            # ensure the specified device id / name is active and available, and
-            # the user context is set correctly.
+            if (play is None):
+                play = True
+            if (refreshDeviceList is None):
+                refreshDeviceList = True
+            if (forceActivateDevice is None):
+                forceActivateDevice = True
+            
+            # ensure the specified device id / name is active and available.
             scDevice = self.GetSpotifyConnectDevice(
                 deviceId, 
                 refreshDeviceList=refreshDeviceList, 
@@ -12567,7 +12709,7 @@ class SpotifyClient:
             {
                 'device_ids': [deviceId]
             }
-            if play is not None:
+            if (play is not None):
                 reqData['play'] = play
 
             # execute spotify web api request.
@@ -12580,6 +12722,13 @@ class SpotifyClient:
             if delay > 0:
                 _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % delay)
                 time.sleep(delay)
+
+            # if forceActivateDevice=True, then we need to resume play manually if play=True
+            # was specified; this is due to the device losing its current status since it 
+            # was being forcefully activated (e.g. disconnected and reconnected).
+            if (forceActivateDevice) and (play):
+                _logsi.LogVerbose('Resuming play on device that was forcefully activated')
+                self.PlayerMediaResume()
                 
             # process results.
             # no results to process - this is pass or fail.
@@ -12661,6 +12810,8 @@ class SpotifyClient:
                 
             # validations.
             delay = validateDelay(delay, 0.50, 10)
+            if (play is None):
+                play = False
 
             # get current Spotify Connect player state.
             result = self.GetPlayerPlaybackState()
@@ -15624,6 +15775,8 @@ class SpotifyClient:
             if scope is not None:
                 if (not isinstance(scope, list)) and (not isinstance(scope, str)):
                     raise SpotifyApiError(SAAppMessages.ARGUMENT_TYPE_ERROR % (apiMethodName, 'scope', 'list', type(scope).__name__), logsi=_logsi)
+            if (forceAuthorize is None):
+                forceAuthorize = False
 
             # create oauth provider for spotify authentication code with pkce.
             self._AuthClient:AuthClient = AuthClient(
@@ -15807,6 +15960,8 @@ class SpotifyClient:
             if scope is not None:
                 if (not isinstance(scope, list)) and (not isinstance(scope, str)):
                     raise SpotifyApiError(SAAppMessages.ARGUMENT_TYPE_ERROR % (apiMethodName, 'scope', 'list', type(scope).__name__), logsi=_logsi)
+            if (forceAuthorize is None):
+                forceAuthorize = False
 
             # create oauth provider for spotify authentication code with pkce.
             self._AuthClient:AuthClient = AuthClient(

spotifywebapipython/zeroconfapi/zeroconfresponse.py

@@ -49,7 +49,7 @@ class ZeroconfResponse:
     @property
     def ResponseSource(self) -> str:
         """ 
-        Response source string (e.g. "").
+        Response source string (e.g. "", "eSDK", etc).
         """
         return self._ResponseSource