spotifywebapiPython 1.0.52__py3-none-any.whl → 1.0.53__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -15,7 +15,7 @@ from zeroconf import Zeroconf
 from .oauthcli import AuthClient
 from .models import *
 from .models import UserProfile as UserProfileCurrentUser
-from .sautils import export, GetUnixTimestampMSFromUtcNow, _xmlGetInnerText
+from .sautils import export, GetUnixTimestampMSFromUtcNow, _xmlGetInnerText, validateDelay
 from .saappmessages import SAAppMessages
 from .spotifyapierror import SpotifyApiError
 from .spotifyapimessage import SpotifyApiMessage
@@ -631,32 +631,6 @@ class SpotifyClient:
         return result
     
 
-    def _ValidateDelay(self, delay:float, default:float=0.5, maxDelay:float=10) -> float:
-        """
-        Validates a delay value.
-        
-        Args:
-            delay (int):
-                The delay value to validate.
-            default (int):
-                The default delay value to set if the user-input delay is not valid.
-            maxDelay (int):
-                The maximum delay value allowed.  
-                Default is 10.
-        """
-        if (isinstance(delay,int)): 
-            delay = float(delay)
-            
-        if (not isinstance(delay,float)) or (delay < 0): 
-            result = default
-        elif (delay > maxDelay): 
-            result = maxDelay
-        else:
-            result = delay
-            
-        return result
-
-
     def _ValidateMarket(self, 
                         market:str,
                         ) -> str:
@@ -5945,10 +5919,10 @@ class SpotifyClient:
     def PlayerActivateDevices(
             self, 
             verifyUserContext:bool=False,
-            delay:float=0.50,
+            delay:float=0.25
             ) -> str:
         """
-        Activates all Spotify Connect player devices, and (optionally) switches the active user
+        Activates all static Spotify Connect player devices, and (optionally) switches the active user
         context to the current user context.
         
         Args:
@@ -5961,7 +5935,7 @@ class SpotifyClient:
                 Time delay (in seconds) to wait AFTER issuing the final Connect command (if necessary).
                 This delay will give the spotify web api time to process the device list change before 
                 another command is issued.  
-                Default is 0.50; value range is 0 - 10.
+                Default is 0.25; value range is 0 - 10.
                 
         Returns:
             A string that contains status text.
@@ -5985,6 +5959,10 @@ class SpotifyClient:
         The user context switch is bypassed if the `verifyUserContext` argument is False.  If the user context 
         is to be switched, then a Disconnect will be issued if a user context is active on the device followed 
         by a Connect to the user context specified on the class constructor.
+        
+        Dynamic Spotify Connect devices are not processed by this method, as they are temporary devices and are 
+        already active and in the device list.  These devices are not found in Zeroconf discovery process, and only
+        exist in the player device list.  These are usually Spotify Connect web or mobile players with temporary device id's.        
 
         <details>
           <summary>Sample Code</summary>
@@ -6012,7 +5990,7 @@ class SpotifyClient:
                 raise SpotifyZeroconfApiError(SAAppMessages.ARGUMENT_REQUIRED_ERROR % (apiMethodName, 'SpotifyConnectUsername'), logsi=_logsi)
 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.25, 10)
             if (not isinstance(verifyUserContext, bool)):
                 verifyUserContext = False
 
@@ -6072,23 +6050,18 @@ class SpotifyClient:
                         # the current user context before connecting a different user.
                         if (info.HasActiveUser):
                             _logsi.LogVerbose("Spotify Connect user context '%s' is being disconnected for Device id '%s'" % (deviceActiveUser, deviceIdResult))
-                            zcfResult = zconn.Disconnect()
+                            zcfResult = zconn.Disconnect(delay)
                             status = status + 'disconnected from user context "%s";' % deviceActiveUser
-                    
+
                         # 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!
                         _logsi.LogVerbose("Spotify Connect user context '%s' is being connected for Device id '%s'" % (self._SpotifyConnectUsername, deviceIdResult))
-                        zcfResult = zconn.Connect(self._SpotifyConnectUsername, self._SpotifyConnectPassword)
+                        zcfResult = zconn.Connect(self._SpotifyConnectUsername, self._SpotifyConnectPassword, delay)
                         status = status + 'connected to user context "%s"' % self._SpotifyConnectUsername
 
                         # trace.
                         _logsi.LogVerbose("Spotify Connect user context switch from '%s' to '%s' was requested for Device id '%s'" % (deviceActiveUser, self._SpotifyConnectUsername, deviceIdResult))
 
-                        # give spotify web api time to process the change and add the device to the device list.
-                        if delay > 0:
-                            _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % delay)
-                            time.sleep(delay)
-                        
                 # append device status to results.
                 result = "%s%s\n" % (result, MSG_RESULT % (info.RemoteName, info.DeviceId, info.ActiveUser, status))
 
@@ -6243,6 +6216,11 @@ class SpotifyClient:
             SpotifApiError: 
                 If the method fails for any other reason.
 
+        Note that this method will only return the devices for which the current user
+        context has control of, or other available devices that do not have an active
+        user context assigned.  Use the `GetSpotifyConnectDevices` method to retrieve
+        a complete list of devices that are available to all users.
+                
         The `ConfigurationCache` is updated with the results of this method.  Use the
         `refresh` argument (with False value) to retrieve the cached value and avoid
         the spotify web api request.  This results in better performance.
@@ -9422,7 +9400,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device pause playback", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -9555,7 +9533,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device play context", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # check for device name; convert to an id if a name was supplied.
             #deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -9663,7 +9641,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device play track favorites", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # get current users favorite tracks.
             tracks:TrackPageSaved = self.GetTrackFavorites(limitTotal=200)
@@ -9774,7 +9752,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device play tracks", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # build a list of all item uri's.
             # remove any leading / trailing spaces in case user put a space between the items.
@@ -9885,7 +9863,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device resume playback", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -9982,7 +9960,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device seek position", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -10074,7 +10052,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device skip next", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -10163,7 +10141,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device skip previous", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -10206,6 +10184,7 @@ class SpotifyClient:
             deviceValue:str, 
             verifyUserContext:bool=True,
             verifyTimeout:float=5.0,
+            delay:float=0.25
             ) -> str:
         """
         Resolves a Spotify Connect device identifier from a specified device id, name, alias id,
@@ -10225,6 +10204,11 @@ class SpotifyClient:
                 Connect device list.  This value is only used if a Connect command has to be
                 issued to activate the device.
                 Default is 5; value range is 0 - 10.
+            delay (float):
+                Time delay (in seconds) to wait AFTER issuing any command to the device.  
+                This delay will give the spotify zeroconf api time to process the change before 
+                another command is issued.  
+                Default is 0.25; value range is 0 - 10.
                 
         Returns:
             A device Id for the deviceValue if one could be resolved; 
@@ -10273,6 +10257,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("deviceValue", deviceValue)
             apiMethodParms.AppendKeyValue("verifyUserContext", verifyUserContext)
             apiMethodParms.AppendKeyValue("verifyTimeout", verifyTimeout)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Resolving Spotify Connect Player Device Id", apiMethodParms)
 
             # if device value not specified then we are done.
@@ -10281,7 +10266,8 @@ class SpotifyClient:
                 return None
             
             # validations.
-            verifyTimeout = self._ValidateDelay(verifyTimeout, 5, 10)
+            delay = validateDelay(delay, 0.25, 10)
+            verifyTimeout = validateDelay(verifyTimeout, 5, 10)
             if (not isinstance(verifyUserContext, bool)):
                 verifyUserContext = True
 
@@ -10376,7 +10362,7 @@ class SpotifyClient:
                     # the current user context before connecting a different user.
                     if (info.HasActiveUser):
                         _logsi.LogVerbose("Spotify Connect user context '%s' is being disconnected for Device id '%s'" % (deviceActiveUser, deviceIdResult))
-                        zcfResult = zconn.Disconnect()
+                        zcfResult = zconn.Disconnect(delay)
                     
                     # 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!
@@ -10490,7 +10476,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Set Spotify Connect device set repeat mode", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -10589,7 +10575,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Set Spotify Connect device set shuffle mode", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -10687,7 +10673,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Set Spotify Connect device set volume level", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -10785,7 +10771,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Transfer playback to a new Spotify Connect device", apiMethodParms)
             
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
             
             # check for device name; convert to an id if a name was supplied.
             #deviceId = self.PlayerConvertDeviceNameToId(deviceId)
@@ -10891,7 +10877,7 @@ class SpotifyClient:
             _logsi.LogMethodParmList(SILevel.Verbose, "Checks if a Spotify Connect device is active, and activate one if not", apiMethodParms)
                 
             # validations.
-            delay = self._ValidateDelay(delay, 0.50, 10)
+            delay = validateDelay(delay, 0.50, 10)
 
             # get current Spotify Connect player state.
             result = self.GetPlayerPlaybackState()

spotifywebapipython/zeroconfapi/zeroconfconnect.py

@@ -12,8 +12,11 @@ from .spotifyzeroconfapierror import SpotifyZeroconfApiError
 from .zeroconfresponse import ZeroconfResponse
 from .zeroconfgetinfo import ZeroconfGetInfo
 from ..saappmessages import SAAppMessages
-from ..sautils import export
+from ..sautils import export, validateDelay
 from ..spotifyapierror import SpotifyApiError
+from ..const import (
+    TRACE_MSG_DELAY_DEVICE,
+)
 
 # get smartinspect logger reference; create a new session for this module name.
 from smartinspectpython.siauto import SIAuto, SILevel, SISession, SIMethodParmListContext, SISourceId
@@ -261,10 +264,12 @@ class ZeroconfConnect:
         return responseData
 
 
-    def Connect(self,
-                username:str, 
-                password:str, 
-                ) -> ZeroconfResponse:
+    def Connect(
+            self,
+            username:str, 
+            password:str, 
+            delay:float=0.50
+            ) -> ZeroconfResponse:
         """
         Calls the `addUser` Spotify Zeroconf API endpoint to issue a call to SpConnectionLoginBlob.  If successful,
         the associated device id is added to the Spotify Connect active device list for the specified user account.
@@ -277,6 +282,11 @@ class ZeroconfConnect:
                 on the manufacturer device.               
             password (str):
                 Spotify Connect user password to login with.  
+            delay (float):
+                Time delay (in seconds) to wait AFTER issuing the command to the device.  
+                This delay will give the spotify zeroconf api time to process the change before 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
 
         Returns:
             A `ZeroconfResponse` object that indicates success or failure (see notes below).
@@ -321,6 +331,7 @@ class ZeroconfConnect:
             apiMethodParms.AppendKeyValue("Version", self._Version)
             apiMethodParms.AppendKeyValue("Uri", self._Uri)
             apiMethodParms.AppendKeyValue("username", username)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Connecting device to Spotify Connect using specified Username and Password", apiMethodParms)
 
             # validations.
@@ -328,6 +339,7 @@ class ZeroconfConnect:
                 raise SpotifyApiError(SAAppMessages.ARGUMENT_REQUIRED_ERROR % (apiMethodName, 'username'), logsi=_logsi)
             if (password is None) or (not isinstance(password,str)):
                 raise SpotifyApiError(SAAppMessages.ARGUMENT_REQUIRED_ERROR % (apiMethodName, 'password'), logsi=_logsi)
+            delay = validateDelay(delay, 0.50, 10)
 
             # get the current device id from the device via Spotify ZeroConf API `getInfo` endpoint.
             info:ZeroconfGetInfo = self.GetInformation()
@@ -361,6 +373,13 @@ class ZeroconfConnect:
 
             # trace.
             _logsi.LogObject(SILevel.Verbose, '%s result - type="%s"' % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
+            
+            # give spotify zeroconf api time to process the change.
+            if delay > 0:
+                _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % delay)
+                time.sleep(delay)
+                        
+            # return result to caller.
             return result
 
         except SpotifyZeroconfApiError: raise  # pass handled exceptions on thru
@@ -380,10 +399,20 @@ class ZeroconfConnect:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
-    def Disconnect(self) -> ZeroconfResponse:
+    def Disconnect(
+            self,
+            delay:float=0.50
+            ) -> ZeroconfResponse:
         """
         Calls the `resetUsers` Spotify Zeroconf API endpoint to issue a call to SpConnectionLogout.
         
+        Args:
+            delay (float):
+                Time delay (in seconds) to wait AFTER issuing the command to the device.  
+                This delay will give the spotify zeroconf api time to process the change before 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
+                
         Returns:
             A `ZeroconfResponse` object that indicates success or failure (see notes below).
 
@@ -415,8 +444,12 @@ class ZeroconfConnect:
             apiMethodParms.AppendKeyValue("CPath", self._CPath)
             apiMethodParms.AppendKeyValue("Version", self._Version)
             apiMethodParms.AppendKeyValue("Uri", self._Uri)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Disconnecting device from Spotify Connect", apiMethodParms)
             
+            # validations.
+            delay = validateDelay(delay, 0.50, 10)
+
             # execute spotify zeroconf api request.
             response = requests.post(
                 self._Uri,
@@ -436,12 +469,15 @@ class ZeroconfConnect:
             # process results.
             result = ZeroconfResponse(root=responseData)
 
-            # just in case user tries to issue a connect immediately after this, give the device
-            # a little time to reset the connection so the subsequent connect does not fail.
-            time.sleep(0.5)
-
             # trace.
             _logsi.LogObject(SILevel.Verbose, '%s result - type="%s"' % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
+
+            # give spotify zeroconf api time to process the change.
+            if delay > 0:
+                _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % delay)
+                time.sleep(delay)
+                        
+            # return result to caller.
             return result
 
         except SpotifyZeroconfApiError: raise  # pass handled exceptions on thru