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

spotifywebapipython/spotifyclient.py

@@ -6342,25 +6342,32 @@ class SpotifyClient:
                 and the response contains error information.
             SpotifyZeroconfApiError:
                 If any Spotify Zeroconf API request failed.  
-                If the `spotifyConnectUsername` argument was not specified for the class contructor.
             SpotifApiError: 
+                If the `spotifyConnectLoginId` argument was not specified for the class contructor.  
+                If the `spotifyConnectUsername` argument was not specified for the class contructor.  
+                If the `spotifyConnectPassword` argument was not specified for the class contructor.  
                 If the method fails for any other reason.
 
-        A Zeroconf discovery process is initiated to search for all Spotify Connect devices connected
-        to the local network.  A Spotify Zeroconf API `getInfo` call is then issued for each device
-        that was found to retrieve device information.  A Spotify Zeroconf API `addUser` call is also
-        issued for each device that does not have an active user context established, OR if the currently
-        active user context does not match the `SpotifyConnectUsername` argument specified on the class 
-        constructor and the `verifyUserContext` argument is True.
-        
-        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.        
+        A Zeroconf discovery process is initiated to search for all Spotify Connect devices connected 
+        to the local network.  It will then iterate through the returned devices and perform the 
+        following on each one:  
+        - call Spotify Zeroconf API `getInfo` endpoint to retrieve device information.  
+        - call Spotify Zeroconf API `resetUsers` endpoint to disconnect the device.  This step is omitted 
+        for dynamic devices (see note below).  Note that this will force any users that are connected to 
+        the device off of the device.  
+        - call Spotify Zeroconf API `addUser` endpoint to connect the device.  This step is omitted for 
+        dynamic devices (see note below).  This should "re-awaken" the device if necessary, and make it 
+        ready for immediate use.  
+
+        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.  
 
+        Note that the SpotifyConnectUsername, SpotifyConnectPassword, and SpotifyConnectLoginId arguments must 
+        be specified on the class contructor in order to use this method.  They are all required in order to 
+        reactivate a Spotify Connect device.
+                
         <details>
           <summary>Sample Code</summary>
         ```python
@@ -6378,14 +6385,10 @@ class SpotifyClient:
             
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
-            apiMethodParms.AppendKeyValue("verifyUserContext", verifyUserContext)
+            apiMethodParms.AppendKeyValue("verifyUserContext (deprecated)", verifyUserContext)
             apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Activating Spotify Connect Player Devices", apiMethodParms)
 
-            # validation - ensure spotify connect user context was specified on the class constructor.
-            if (self._SpotifyConnectUsername is None):
-                raise SpotifyZeroconfApiError(SAAppMessages.ARGUMENT_REQUIRED_ERROR % (apiMethodName, 'SpotifyConnectUsername'), logsi=_logsi)
-
             # validations.
             delay = validateDelay(delay, 0.25, 10)
             if (not isinstance(verifyUserContext, bool)):
@@ -6422,24 +6425,10 @@ class SpotifyClient:
 
                     # is this a dynamic device?  if so, then there is no need to activate it as it's already active.
                     if (discoverResult.IsDynamicDevice):
+                        
                         _logsi.LogVerbose("Activation not required for dynamic Spotify Connect device: '%s'" % (scDevice.Title))
-                        status = status + "dynamic device, cannot switch user context"
-                    
-                    # does our Spotify Connect user account need to take control of the device?
-                    # if not, then we are done.
-                    # this takes into account if the device is in the available device list, as well
-                    # as if the active user is not our user context.
-                    elif (info.IsInDeviceList == True) \
-                    and ((deviceActiveUser == self._SpotifyConnectUsername.lower()) or (deviceActiveUser == self.UserProfile.Id.lower())):
-                        _logsi.LogVerbose("User context '%s' was verified for Spotify Connect device '%s'; switch not necessary" % (deviceActiveUser, scDevice.Title))
-                        status = status + "user context switch not needed"
+                        status = status + "dynamic device, cannot switch user context; "
                     
-                    # did caller request user context switch bypass?
-                    # if so, then just return the device id.
-                    elif (info.HasActiveUser) and (not verifyUserContext):
-                        _logsi.LogVerbose("User context '%s' will be used for Spotify Connect device '%s', as user chose to bypass user context switch" % (deviceActiveUser, scDevice.Title))
-                        status = status + "caller bypassed user context switch"
-
                     else:
                         
                         zcfResult:ZeroconfResponse
@@ -6462,19 +6451,21 @@ class SpotifyClient:
                         if (info.BrandDisplayName != 'librespot'):
                             _logsi.LogVerbose("Issuing Disconnect to Spotify Connect device '%s' for current user context '%s'" % (scDevice.Title, deviceActiveUser))
                             zcfResult = zconn.Disconnect(delay)
-                            status = status + 'disconnected from user context "%s";' % deviceActiveUser
+                            status = status + 'disconnected from user context "%s"; ' % deviceActiveUser
+                        else:
+                            status = status + 'disconnect bypassed for librespot device; '
 
                         # 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("Issuing Connect to Spotify Connect device '%s' for user context '%s'" % (scDevice.Title, self._SpotifyConnectUsername))
+                        _logsi.LogVerbose("Issuing Connect to Spotify Connect device '%s' for user context '%s'" % (scDevice.Title, self._SpotifyConnectLoginId))
                         zcfResult = zconn.Connect(self._SpotifyConnectUsername, self._SpotifyConnectPassword, self._SpotifyConnectLoginId, delay=delay)
-                        status = status + 'connected to user context "%s"' % self._SpotifyConnectUsername
+                        status = status + 'connected to user context "%s"; ' % self._SpotifyConnectLoginId
                         
                         # indicate device was reconnected.
                         scDevice.WasReConnected = True
 
                         # trace.
-                        _logsi.LogVerbose("User context switch from '%s' to '%s' was requested for Spotify Connect device '%s'" % (deviceActiveUser, self._SpotifyConnectUsername, scDevice.Title))
+                        _logsi.LogVerbose("User context switched from '%s' to '%s' for Spotify Connect device '%s'" % (deviceActiveUser, self._SpotifyConnectLoginId, scDevice.Title))
 
                 # append device status to results.
                 result = "%s%s\n" % (result, MSG_RESULT % (info.RemoteName, info.DeviceId, info.ActiveUser, status))
@@ -8728,6 +8719,9 @@ class SpotifyClient:
             SpotifyZeroconfApiError:
                 If any Spotify Zeroconf API request failed.
             SpotifApiError: 
+                If the `spotifyConnectLoginId` argument was not specified for the class contructor.  
+                If the `spotifyConnectUsername` argument was not specified for the class contructor.  
+                If the `spotifyConnectPassword` argument was not specified for the class contructor.  
                 If the method fails for any other reason.
 
         The Spotify Connect discovery list is searched for the specified device value; the search will 
@@ -8773,6 +8767,11 @@ class SpotifyClient:
                 _logsi.LogVerbose("deviceValue not specified; active Spotify Player will be used")
                 return None
             
+            # was a Spotify Connect loginId specified on the class constructor?
+            # if not, then we cannot re-activate devices!
+            if (self._SpotifyConnectLoginId is None):
+                raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_ACTIVATE_CREDENTIAL_REQUIRED % ("SpotifyConnectLoginId"), logsi=_logsi)
+
             # validations.
             delay = validateDelay(delay, 0.25, 10)
             verifyTimeout = validateDelay(verifyTimeout, 5, 10)
@@ -8876,7 +8875,7 @@ class SpotifyClient:
                         )
                         
                         if not hasToken:
-                            _logsi.LogVerbose("Spotify Desktop Application Client oauth2 token was not found for Spotify LogiId: '%s'" % (self._SpotifyConnectLoginId))
+                            _logsi.LogVerbose("Spotify Desktop Application Client oauth2 token was not found for Spotify LoginId: '%s'" % (self._SpotifyConnectLoginId))
                             break
 
                     # store the currently active user of the device, in case we need to switch users later on.
@@ -8894,13 +8893,6 @@ class SpotifyClient:
 
                     zcfResult:ZeroconfResponse
                                           
-                    # was a Spotify Connect user account specified on the class constructor?
-                    # if not, then we cannot re-activate the device!
-                    if (self._SpotifyConnectUsername is None):
-                        raise SpotifyApiError("A SpotifyConnectUsername parameter was not supplied; could not reactivate Spotify Connect device '%s'" % (deviceResult.Title), logsi=_logsi)
-                        #_logsi.LogVerbose("A SpotifyConnectUsername parameter was not supplied; could not reactivate Spotify Connect device '%s'" % (deviceResult.Title))
-                        break
-                                       
                     # disconnect the device.
                     # we will bypass disconnects for librespot devices (e.g. spotifyd, etc), as the
                     # Spotify Connect Zeroconf `resetUsers` endpoint is not implemented and will
@@ -8911,14 +8903,14 @@ class SpotifyClient:
                     
                     # 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("Issuing Connect to Spotify Connect device '%s' for user context '%s'" % (deviceResult.Title, self._SpotifyConnectUsername))
+                    _logsi.LogVerbose("Issuing Connect to Spotify Connect device '%s' for user context '%s'" % (deviceResult.Title, self._SpotifyConnectLoginId))
                     zcfResult = zconn.Connect(self._SpotifyConnectUsername, self._SpotifyConnectPassword, self._SpotifyConnectLoginId)
                     
                     # indicate device was reconnected.
                     deviceResult.WasReConnected = True
                     
                     # trace.
-                    _logsi.LogVerbose("User context switch from '%s' to '%s' was requested for Spotify Connect device: '%s'" % (deviceActiveUser, self._SpotifyConnectUsername, deviceResult.Title))
+                    _logsi.LogVerbose("User context switched from '%s' to '%s' for Spotify Connect device: '%s'" % (deviceActiveUser, self._SpotifyConnectLoginId, deviceResult.Title))
 
                     loopTotalDelay:float = 0
                     LOOP_DELAY:float = 0.25
@@ -11385,17 +11377,18 @@ class SpotifyClient:
             relativePositionMS:int=0,
             ) -> None:
         """
-        Seeks to the given position in the user's currently playing track for the specified 
-        Spotify Connect device.
+        Seeks to the given absolute or relative position in the user's currently playing track 
+        for the specified Spotify Connect device.
         
         This method requires the `user-modify-playback-state` scope.
 
         Args:
             positionMS (int):
-                The position in milliseconds to seek to; must be a positive number.  
+                The absolute position in milliseconds to seek to; must be a positive number or
+                zero if the `relativePositionMS` argument is specified.  
                 Passing in a position that is greater than the length of the track will cause the 
-                player to start playing the next song.
-                Example: `25000`  
+                player to start playing the next song.  
+                Example = `25000` to start playing at the 25 second mark.  
             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.  
@@ -11407,10 +11400,10 @@ class SpotifyClient:
                 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`  
+                The relative position in milliseconds to seek to; can be a positive or negative number,
+                or zero if the `positionMS` argument is specified.  
+                Example = `-10000` to seek behind by 10 seconds.  
+                Example = `10000` to seek ahead by 10 seconds.  
                 
         Raises:
             SpotifyWebApiError: 
@@ -11423,12 +11416,15 @@ class SpotifyClient:
         
         The order of execution is not guaranteed when you use this API with other Player API endpoints.
         
+        If using relative positioning, the `positionMS` argument must be zero (or null); the `positionMS`
+        argument takes precedence if it and the `relativePositionMS` argument are specified. 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.
+
         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.
-        
+        argument was added to this API to support "skip" seeking.  
+                        
         <details>
           <summary>Sample Code</summary>
         ```python
@@ -11470,7 +11466,7 @@ class SpotifyClient:
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
             
             # was relative seeking specified?
-            if (relativePositionMS != 0) and (positionMS == 0):
+            if (relativePositionMS != 0) and ((positionMS is None) or (positionMS <= 0)):
                 
                 # get current track position.
                 playState:PlayerPlayState = self.GetPlayerPlaybackState()

spotifywebapipython/zeroconfapi/zeroconfconnect.py

@@ -408,10 +408,6 @@ class ZeroconfConnect:
             _logsi.LogMethodParmList(SILevel.Verbose, "Connecting device to Spotify Connect (ip=%s)" % self._HostIpAddress, apiMethodParms)
 
             # validations.
-            if (username is None) or (not isinstance(username,str)):
-                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.
@@ -551,10 +547,6 @@ class ZeroconfConnect:
                 'Connection': 'close'
             }
 
-            # create credentials and builder objects.
-            credentials:Credentials = Credentials(username, password, AuthenticationTypes.USER_PASS)
-            builder = BlobBuilder(credentials, info.DeviceId, info.PublicKey)
-
             # set defaults used by most manufacturers - we will tailor these in the
             # logic below for specific manufacturers / devices as required.
             # - exclude origin device information from the addUser request.
@@ -569,6 +561,16 @@ class ZeroconfConnect:
             # special processing for librespot, spotifyd.
             if info.ModelDisplayName == 'librespot':
 
+                # trace.
+                _logsi.LogVerbose("Spotify Connect token type is '%s' - using librespot authorization credentials to connect: '%s' (ip=%s)" % (info.TokenType, info.RemoteName, self._HostIpAddress))
+
+                # validations.
+                # note that userid and password are not needed by librespot, as both of those
+                # are contained in the librespot credentials object.  we only need the loginId
+                # value for the credentials lookup.
+                if (loginId is None) or (not isinstance(loginId,str)):
+                    raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_ACTIVATE_CREDENTIAL_REQUIRED % ("SpotifyConnectLoginId"), logsi=_logsi)
+
                 # we will use credentials from a librespot credentials.json file.
                 # this requires that the user copy the "credentials.json" file from the 
                 # librespot cache location (e.g. "/home/user/.cache/spotifyd/credentials.json", etc)
@@ -601,6 +603,18 @@ class ZeroconfConnect:
                 # trace.
                 _logsi.LogVerbose("Spotify Connect token type is '%s' - using Spotify Desktop Client OAuth2 token to connect: '%s' (ip=%s)" % (info.TokenType, info.RemoteName, self._HostIpAddress))
 
+                # validations.
+                if (loginId is None) or (not isinstance(loginId,str)):
+                    raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_ACTIVATE_CREDENTIAL_REQUIRED % ("SpotifyConnectLoginId"), logsi=_logsi)
+                if (username is None) or (not isinstance(username,str)):
+                    raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_ACTIVATE_CREDENTIAL_REQUIRED % ("SpotifyConnectUsername"), logsi=_logsi)
+                if (password is None) or (not isinstance(password,str)):
+                    raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_ACTIVATE_CREDENTIAL_REQUIRED % ("SpotifyConnectPassword"), logsi=_logsi)
+
+                # create credentials and builder objects.
+                credentials:Credentials = Credentials(username, password, AuthenticationTypes.USER_PASS)
+                builder = BlobBuilder(credentials, info.DeviceId, info.PublicKey)
+
                 # set defaults used by token type "authorization_code".
                 # - set the clientKey value to null, as it is not used to encrypt / decrypt anything.
                 # - include origin device information in the addUser request.
@@ -617,6 +631,18 @@ class ZeroconfConnect:
                 # trace.
                 _logsi.LogVerbose("Spotify Connect token type is '%s' - using Spotify username and password to connect: '%s' (ip=%s)" % (info.TokenType, info.RemoteName, self._HostIpAddress))
 
+                # validations.
+                if (loginId is None) or (not isinstance(loginId,str)):
+                    raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_ACTIVATE_CREDENTIAL_REQUIRED % ("SpotifyConnectLoginId"), logsi=_logsi)
+                if (username is None) or (not isinstance(username,str)):
+                    raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_ACTIVATE_CREDENTIAL_REQUIRED % ("SpotifyConnectUsername"), logsi=_logsi)
+                if (password is None) or (not isinstance(password,str)):
+                    raise SpotifyApiError(SAAppMessages.MSG_SPOTIFY_ACTIVATE_CREDENTIAL_REQUIRED % ("SpotifyConnectPassword"), logsi=_logsi)
+
+                # create credentials and builder objects.
+                credentials:Credentials = Credentials(username, password, AuthenticationTypes.USER_PASS)
+                builder = BlobBuilder(credentials, info.DeviceId, info.PublicKey)
+
                 # set defaults used by this token type:
                 # - clientKey should be the getInfo response PublicKey (base64 encoded).
                 # - exclude origin device information from the addUser request.