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

spotifywebapipython/models/spotifyconnectdevice.py

@@ -0,0 +1,93 @@
+# external package imports.
+from zeroconf import ServiceInfo
+
+# our package imports.
+from ..sautils import export
+from .zeroconfdiscoveryresult import ZeroconfDiscoveryResult
+from spotifywebapipython.zeroconfapi.zeroconfgetinfo import ZeroconfGetInfo
+
+@export
+class SpotifyConnectDevice():
+    """
+    Spotify Connect Device object.
+    
+    Information about the Spotify Connect device, which is a combination of the 
+    `ZeroconfDiscoveryResult` and `ZeroconfGetInfo` classes.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initializes a new instance of the class.
+        """
+        self._DiscoveryResult:ZeroconfDiscoveryResult = None
+        self._DeviceInfo:ZeroconfGetInfo = None
+
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def DiscoveryResult(self) -> ZeroconfDiscoveryResult:
+        """ 
+        Information about the Zeroconf entry for a SpotifyConnect device as found by Zeroconf (mDNS).
+        """
+        return self._DiscoveryResult
+    
+    @DiscoveryResult.setter
+    def DiscoveryResult(self, value:ZeroconfDiscoveryResult):
+        """ 
+        Sets the DiscoveryResult property value.
+        """
+        if isinstance(value, ZeroconfDiscoveryResult):
+            self._DiscoveryResult = value
+
+
+    @property
+    def DeviceInfo(self) -> ZeroconfGetInfo:
+        """ 
+        Spotify Zeroconf API GetInfo response object.
+        """
+        return self._DeviceInfo
+    
+    @DeviceInfo.setter
+    def DeviceInfo(self, value:ZeroconfGetInfo):
+        """ 
+        Sets the DeviceInfo property value.
+        """
+        if isinstance(value, ZeroconfGetInfo):
+            self._DeviceInfo = value
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'DeviceInfo': self._DeviceInfo.ToDictionary(),
+            'DiscoveryResult': self._DiscoveryResult.ToDictionary(),
+        }
+        return result
+        
+
+    def ToString(self, includeTitle:bool=True) -> str:
+        """
+        Returns a displayable string representation of the class.
+        
+        Args:
+            includeTitle (str):
+                True to include the class name title prefix.
+        """
+        msg:str = ''
+        if includeTitle: 
+            msg = 'Device: "%s" (%s)' % (self._DiscoveryResult.DeviceName, self._DeviceInfo.DeviceId)
+           
+        # build result.
+        msg = '%s\n %s\n' % (msg, str(self._DeviceInfo.ToString(True)))
+        msg = '%s\n %s\n' % (msg, str(self._DiscoveryResult.ToString(True)))
+        return msg 

spotifywebapipython/models/spotifyconnectdevices.py

@@ -0,0 +1,137 @@
+# external package imports.
+from typing import Iterator
+
+# our package imports.
+from ..sautils import export
+from .device import Device
+from .spotifyconnectdevice import SpotifyConnectDevice
+from spotifywebapipython.zeroconfapi import ZeroconfGetInfo, ZeroconfGetInfoAlias
+
+@export
+class SpotifyConnectDevices():
+    """
+    Spotify Connect Devices collection.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initializes a new instance of the class.
+        """
+        self._Items:list[SpotifyConnectDevice] = []
+
+
+    def __getitem__(self, key) -> SpotifyConnectDevice:
+        return self._Presets[key]
+
+
+    def __iter__(self) -> Iterator:
+        return iter(self._Items)
+
+
+    def __len__(self) -> int:
+        return len(self._Items)
+
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Items(self) -> list[SpotifyConnectDevice]:
+        """ 
+        Array of `SpotifyConnectDevice` objects.
+        """
+        return self._Items
+    
+
+    @property
+    def ItemsCount(self) -> int:
+        """ 
+        Number of objects in the `Items` property array.
+        """
+        if self._Items is not None:
+            return len(self._Items)
+        return 0
+    
+
+    def GetDeviceList(self) -> list[Device]:
+        """
+        Returns a list of `Device` objects that can be used to build a selection list
+        of available devices.  
+        
+        Note that the `Device` object has the following properties populated:
+        Id, Name, IsActive, Type.
+        """
+        result:list[Device] = []
+        
+        # process all discovered devices.
+        scDevice:SpotifyConnectDevice
+        for scDevice in self._Items:
+
+            # map device information details.
+            info:ZeroconfGetInfo = scDevice.DeviceInfo
+
+            # create new mock device.
+            device = Device()
+            device.IsActive = info.HasActiveUser
+            device.Type = info.DeviceType
+                
+            # are aliases being used (RemoteName is null if so)?
+            if info.RemoteName is None:
+                    
+                # if aliases are defined, then use the alias details.
+                infoAlias:ZeroconfGetInfoAlias
+                for infoAlias in info.Aliases:
+                    device.Id = infoAlias.Id
+                    device.Name = infoAlias.Name
+
+            else:
+
+                # if no aliases then use the remote name and id.
+                device.Id = info.DeviceId
+                device.Name = info.RemoteName
+
+            # append device to results.
+            result.append(device)
+
+        # sort items on Name property, ascending order.
+        if len(result) > 0:
+            result.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
+
+        return result
+    
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'ItemsCount': self.ItemsCount,
+            'Items': [ item.ToDictionary() for item in self._Items ],
+        }
+
+        return result
+        
+           
+    def ToString(self, includeItems:bool=False) -> str:
+        """
+        Returns a displayable string representation of the class.
+        
+        Args:
+            includeItems (bool):
+                True to include the Items collection of objects; otherwise, False
+                to only return base properties.
+        """
+        msg:str = 'Items Count=%s' % (str(self.ItemsCount))
+        
+        if (includeItems):
+            item:SpotifyConnectDevice
+            for item in self._Items:
+                msg = "%s\n- %s" % (msg, item.ToString(True))
+            
+        return msg 

spotifywebapipython/models/zeroconfdiscoveryresult.py

@@ -16,11 +16,6 @@ class ZeroconfDiscoveryResult:
     def __init__(self) -> None:
         """
         Initializes a new instance of the class.
-        
-        Args:
-            root (dict):
-                Spotify Web API JSON response in dictionary format, used to load object
-                attributes; otherwise, None to not load attributes.
         """
         self._DeviceName:str = None
         self._Domain:str = '.'

spotifywebapipython/spotifyclient.py

@@ -7890,6 +7890,87 @@ 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).
+                        
+        <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)
+            _logsi.LogVerbose("Get all available Spotify Connect devices")
+                
+            # 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)
+                
+            # 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: