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

spotifywebapipython/spotifyclient.py

@@ -5946,7 +5946,7 @@ class SpotifyClient:
             self, 
             verifyUserContext:bool=False,
             delay:float=0.50,
-            ) -> None:
+            ) -> str:
         """
         Activates all Spotify Connect player devices, and (optionally) switches the active user
         context to the current user context.
@@ -5963,6 +5963,9 @@ class SpotifyClient:
                 another command is issued.  
                 Default is 0.50; value range is 0 - 10.
                 
+        Returns:
+            A string that contains status text.
+                
         Raises:
             SpotifyWebApiError: 
                 If the Spotify Web API request was for a non-authorization service 
@@ -6015,40 +6018,38 @@ class SpotifyClient:
 
             deviceActiveUser:str = None
             deviceIdResult:str = None
-                
-            # discover Spotify Connect devices on the network, waiting up to the specified timeout 
-            # for all devices to be discovered.  this will return all Spotify Connect devices that
-            # are currently powered on, and are registered to Zeroconf / mDNS.
-            _logsi.LogVerbose("Discovering Spotify Connect devices on the local network")
-            discovery:SpotifyDiscovery = SpotifyDiscovery(self._ZeroconfClient, printToConsole=False)
-            discovery.DiscoverDevices(timeout=self._SpotifyConnectDiscoveryTimeout)
+            discoverResult:ZeroconfDiscoveryResult
+            info:ZeroconfGetInfo
+            scDevice:SpotifyConnectDevice
+            
+            # get all Spotify Connect available devices on the network.
+            scDevices:SpotifyConnectDevices = self.GetSpotifyConnectDevices()
 
             # process all discovered devices.
-            discoverResult:ZeroconfDiscoveryResult
-            for discoverResult in discovery.DiscoveryResults:
+            for scDevice in scDevices:
                 
-                # get the id from the device via the zeroconf API getInfo endpoint, as the id is not 
-                # returned in the zeroconf discovery result.
-                zconn:ZeroconfConnect = ZeroconfConnect(discoverResult.HostIpv4Address, 
-                                                        discoverResult.HostIpPort, 
-                                                        discoverResult.SpotifyConnectCPath,
-                                                        useSSL=False)
-                info:ZeroconfGetInfo = zconn.GetInformation()
+                discoverResult = scDevice.DiscoveryResult
+                info = scDevice.DeviceInfo
 
                 # store the currently active user of the device, in case we need to switch users later on.
                 deviceActiveUser = info.ActiveUser.lower()
                 deviceIdResult = info.DeviceId
                 
-                status:str = "INACTIVE"
+                status:str = "INACTIVE, "
                 if (info.HasActiveUser):
                     status = "ACTIVE, "
                 
                 # did we resolve the device id?
                 if deviceIdResult is not None:
                     
+                    # is this a dynamic device?  if so, then we can't control it.
+                    if (discoverResult.IsDynamicDevice):
+                        _logsi.LogVerbose("Spotify Connect Device id '%s' (%s) is a dynamic device; we cannot control it" % (deviceIdResult, info.RemoteName))
+                        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.
-                    if (deviceActiveUser == self._SpotifyConnectUsername.lower()):  # or (deviceActiveUser == self.UserProfile.Id.lower()):
+                    elif (deviceActiveUser == self._SpotifyConnectUsername.lower()):  # or (deviceActiveUser == self.UserProfile.Id.lower()):
                         _logsi.LogVerbose("Spotify Connect user context '%s' was verified for Device id '%s'; switch not necessary" % (deviceActiveUser, deviceIdResult))
                         status = status + "user context switch not needed"
                     
@@ -6060,6 +6061,12 @@ class SpotifyClient:
 
                     else:
                         zcfResult:ZeroconfResponse
+
+                        # create a ZeroconfConnect object to access the device.
+                        zconn:ZeroconfConnect = ZeroconfConnect(discoverResult.HostIpv4Address, 
+                                                                discoverResult.HostIpPort, 
+                                                                discoverResult.SpotifyConnectCPath,
+                                                                useSSL=False)
                     
                         # if a different user context has control of the device then we need to disconnect 
                         # the current user context before connecting a different user.
@@ -7890,6 +7897,102 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
+    def GetSpotifyConnectDevices(
+            self, 
+            ) -> SpotifyConnectDevices:
+        """
+        Get information about all available Spotify Connect player devices.
+        
+        Returns:
+            A `SpotifyConnectDevices` object that contain the discovery results
+            as well as the `getInfo` result for each found device.
+                
+        Raises:
+            SpotifyWebApiError: 
+                If the Spotify Web API request was for a non-authorization service 
+                and the response contains error information.
+            SpotifyZeroconfApiError:
+                If the Spotify Zeroconf API request faild for any reason.
+            SpotifApiError: 
+                If the method fails for any other reason.
+
+        This method is similar to the `GetPlayerDevices` method, but it contains ALL
+        available Spotify Connect devices that are known to the local network (versus
+        just the devices known to a specific user).
+        
+        It will also call the `GetPlayerDevices` method, in case we have any dynamic devices.
+        Dynamic devices are Spotify Connect devices that are not found in Zeroconf discovery
+        process, but still 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>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/GetSpotifyConnectDevices.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'GetSpotifyConnectDevices'
+        result:SpotifyConnectDevices = SpotifyConnectDevices()
+        
+        try:
+            
+            # trace.
+            _logsi.EnterMethod(SILevel.Debug, apiMethodName)
+                
+            # discover Spotify Connect devices on the network, waiting up to the specified timeout 
+            # for all devices to be discovered.  this will return all Spotify Connect devices that
+            # are currently powered on, and are registered to Zeroconf / mDNS.
+            _logsi.LogVerbose("Discovering Spotify Connect devices on the local network")
+            discovery:SpotifyDiscovery = SpotifyDiscovery(self._ZeroconfClient, printToConsole=False)
+            discovery.DiscoverDevices(timeout=self._SpotifyConnectDiscoveryTimeout)
+
+            # process all discovered devices.
+            discoverResult:ZeroconfDiscoveryResult
+            for discoverResult in discovery.DiscoveryResults:
+
+                # get the id from the device via the zeroconf API getInfo endpoint, as the id is not 
+                # returned in the zeroconf discovery result.
+                zconn:ZeroconfConnect = ZeroconfConnect(discoverResult.HostIpv4Address, 
+                                                        discoverResult.HostIpPort, 
+                                                        discoverResult.SpotifyConnectCPath,
+                                                        useSSL=False)
+                info:ZeroconfGetInfo = zconn.GetInformation()
+
+                # create new spotify connect device object.
+                scDevice:SpotifyConnectDevice = SpotifyConnectDevice()
+                scDevice.DiscoveryResult = discoverResult
+                scDevice.DeviceInfo = info
+                result.Items.append(scDevice)
+                
+            # we will also call the GetPlayerDevices method, in case we have any dynamic devices.
+            # dynamic devices are Spotify Connect devices that are not found in Zeroconf discovery
+            # process, but still exist in the player device list.  these are usually Spotify Connect
+            # web or mobile players with temporary device id's.
+            devices:list[Device] = self.GetPlayerDevices(True)
+          
+            device:Device
+            for device in devices:
+                if not result.ContainsDeviceId(device.Id):
+                    result.AddDynamicDevice(device, self.UserProfile.Id)
+
+            # trace.
+            _logsi.LogArray(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result)
+            return result
+
+        except SpotifyZeroconfApiError: raise  # pass handled exceptions on thru
+        except SpotifyApiError: 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 GetTrack(self, 
                  trackId:str, 
                  ) -> Track:
@@ -10185,33 +10288,27 @@ class SpotifyClient:
             # determine if the device value specified is a name (e.g. "Bose-ST10-1") or 
             # an id (e.g. "30fbc80e35598f3c242f2120413c943dfd9715fe").
             isDeviceId:bool = SpotifyClient.IsDeviceId(deviceValue)
+
             deviceValueCompare:str = deviceValue.lower()
             deviceActiveUser:str = None
-                
-            # discover Spotify Connect devices on the network, waiting up to the specified timeout 
-            # for all devices to be discovered.  this will return all Spotify Connect devices that
-            # are currently powered on, and are registered to Zeroconf / mDNS.
-            _logsi.LogVerbose("Discovering Spotify Connect devices on the local network")
-            discovery:SpotifyDiscovery = SpotifyDiscovery(self._ZeroconfClient, printToConsole=False)
-            discovery.DiscoverDevices(timeout=self._SpotifyConnectDiscoveryTimeout)
+            discoverResult:ZeroconfDiscoveryResult
+            info:ZeroconfGetInfo
+            scDevice:SpotifyConnectDevice
+
+            # get all Spotify Connect available devices on the network.
+            scDevices:SpotifyConnectDevices = self.GetSpotifyConnectDevices()
 
             # process all discovered devices.
-            discoverResult:ZeroconfDiscoveryResult
-            for discoverResult in discovery.DiscoveryResults:
+            for scDevice in scDevices:
                 
-                # get the id from the device via the zeroconf API getInfo endpoint, as the id is not 
-                # returned in the zeroconf discovery result.
-                zconn:ZeroconfConnect = ZeroconfConnect(discoverResult.HostIpv4Address, 
-                                                        discoverResult.HostIpPort, 
-                                                        discoverResult.SpotifyConnectCPath,
-                                                        useSSL=False)
-                info:ZeroconfGetInfo = zconn.GetInformation()
+                discoverResult = scDevice.DiscoveryResult
+                info = scDevice.DeviceInfo
 
                 # store the currently active user of the device, in case we need to switch users later on.
                 deviceActiveUser = info.ActiveUser.lower()
 
                 # are aliases being used (RemoteName is null if so)?
-                if info.RemoteName is None:
+                if info.HasAliases:
                     
                     # if aliases are defined for the device, then we have to check each alias for a match.
                     infoAlias:ZeroconfGetInfoAlias
@@ -10244,6 +10341,11 @@ class SpotifyClient:
                 # did we resolve the device id?
                 if deviceIdResult is not None:
                     
+                    # is this a dynamic device?  if so, then we can't control it.
+                    if (discoverResult.IsDynamicDevice):
+                        _logsi.LogVerbose("Spotify Connect Device '%s' (%s) is a dynamic device; we cannot control it" % (info.RemoteName, deviceIdResult))
+                        break
+                    
                     # did caller request user context switch bypass?
                     # if so, then just return the device id.
                     if (not verifyUserContext):
@@ -10264,6 +10366,12 @@ class SpotifyClient:
                     
                     zcfResult:ZeroconfResponse
                     
+                    # create a ZeroconfConnect object to access the device.
+                    zconn:ZeroconfConnect = ZeroconfConnect(discoverResult.HostIpv4Address, 
+                                                            discoverResult.HostIpPort, 
+                                                            discoverResult.SpotifyConnectCPath,
+                                                            useSSL=False)
+
                     # if a different user context has control of the device then we need to disconnect 
                     # the current user context before connecting a different user.
                     if (info.HasActiveUser):

spotifywebapipython/zeroconfapi/zeroconfgetinfo.py

@@ -109,6 +109,14 @@ class ZeroconfGetInfo(ZeroconfResponse):
         This value will be an empty string if there is no user logged into the device.
         """
         return self._ActiveUser
+    
+    @ActiveUser.setter
+    def ActiveUser(self, value:str):
+        """ 
+        Sets the ActiveUser property value.
+        """
+        if isinstance(value, str):
+            self._ActiveUser = value
 
 
     @property
@@ -158,6 +166,14 @@ class ZeroconfGetInfo(ZeroconfResponse):
         Unique device ID used for ZeroConf logins (e.g. "30fbc80e35598f3c242f2120413c943dfd9715fe").
         """
         return self._DeviceId
+    
+    @DeviceId.setter
+    def DeviceId(self, value:str):
+        """ 
+        Sets the DeviceId property value.
+        """
+        if isinstance(value, str):
+            self._DeviceId = value
 
 
     @property
@@ -182,6 +198,14 @@ class ZeroconfGetInfo(ZeroconfResponse):
         - kSpDeviceTypeChromebook	Chromebook.        
         """
         return self._DeviceType
+    
+    @DeviceType.setter
+    def DeviceType(self, value:str):
+        """ 
+        Sets the DeviceType property value.
+        """
+        if isinstance(value, str):
+            self._DeviceType = value
 
 
     @property
@@ -253,6 +277,14 @@ class ZeroconfGetInfo(ZeroconfResponse):
         Please refer to the `Aliases` property for more information.
         """
         return self._RemoteName
+    
+    @RemoteName.setter
+    def RemoteName(self, value:str):
+        """ 
+        Sets the RemoteName property value.
+        """
+        if isinstance(value, str):
+            self._RemoteName = value
 
 
     @property

spotifywebapipython/zeroconfapi/zeroconfresponse.py

@@ -57,6 +57,14 @@ class ZeroconfResponse:
         The last error code returned by a Spotify API call or the SpCallbackError() callback (e.g. 0, -119, etc).
         """
         return self._SpotifyError
+    
+    @SpotifyError.setter
+    def SpotifyError(self, value:int):
+        """ 
+        Sets the SpotifyError property value.
+        """
+        if isinstance(value, int):
+            self._SpotifyError = value
 
 
     @property
@@ -65,6 +73,14 @@ class ZeroconfResponse:
         A code indicating the result of the operation (e.g. 101, 402, etc).
         """
         return self._Status
+    
+    @Status.setter
+    def Status(self, value:int):
+        """ 
+        Sets the Status property value.
+        """
+        if isinstance(value, int):
+            self._Status = value
 
 
     @property
@@ -73,6 +89,14 @@ class ZeroconfResponse:
         The string describing the status code (e.g. "OK", "ERROR-SPOTIFY-ERROR", etc).
         """
         return self._StatusString
+    
+    @StatusString.setter
+    def StatusString(self, value:str):
+        """ 
+        Sets the StatusString property value.
+        """
+        if isinstance(value, str):
+            self._StatusString = value
 
 
     def ToDictionary(self) -> dict: