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

spotifywebapipython/models/device.py

@@ -64,6 +64,24 @@ class Device:
         return self.ToString()
 
 
+    # implement sorting support.
+    def __eq__(self, other):
+        try:
+            return self.Name == other.Name
+        except Exception as ex:
+            if (isinstance(self, Device )) and (isinstance(other, Device )):
+                return self.Name == other.Name
+            return False
+
+    def __lt__(self, other):
+        try:
+            return self.Name < other.Name
+        except Exception as ex:
+            if (isinstance(self, Device )) and (isinstance(other, Device )):
+                return self.Name < other.Name
+            return False
+
+
     @property
     def Id(self) -> str:
         """ 
@@ -74,6 +92,14 @@ class Device:
         """
         return self._Id
 
+    @Id.setter
+    def Id(self, value:str):
+        """ 
+        Sets the Id property value.
+        """
+        if isinstance(value, str):
+            self._Id = value
+
 
     @property
     def IsActive(self) -> bool:
@@ -82,6 +108,14 @@ class Device:
         """
         return self._IsActive
 
+    @IsActive.setter
+    def IsActive(self, value:bool):
+        """ 
+        Sets the IsActive property value.
+        """
+        if isinstance(value, bool):
+            self._IsActive = value
+
 
     @property
     def IsMuted(self) -> bool:
@@ -122,6 +156,14 @@ class Device:
         """
         return self._Name
 
+    @Name.setter
+    def Name(self, value:str):
+        """ 
+        Sets the Name property value.
+        """
+        if isinstance(value, str):
+            self._Name = value
+
 
     @property
     def SelectItemNameAndId(self) -> str:
@@ -151,6 +193,14 @@ class Device:
         """
         return self._Type
 
+    @Type.setter
+    def Type(self, value:str):
+        """ 
+        Sets the Type property value.
+        """
+        if isinstance(value, str):
+            self._Type = value
+
 
     @property
     def VolumePercent(self) -> int:

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

@@ -146,7 +146,7 @@ class SpotifyClient:
         self._TokenStorageDir:str = tokenStorageDir
         self._TokenUpdater:Callable = tokenUpdater
         self._UserProfile:UserProfile = None
-        self._Zeroconf = zeroconfClient
+        self._ZeroconfClient = zeroconfClient
         
         # if pool manager instance is none or not a PoolManager instance, then create one.
         # we increase the maximum number of connections to keep in the pool (maxsize=) to avoid the following warnings:
@@ -165,7 +165,7 @@ class SpotifyClient:
         # create the zeroconf client if one was not specified.
         if zeroconfClient is None:
             _logsi.LogVerbose("Creating new Zeroconf instance for discovery")
-            self._Zeroconf = Zeroconf()
+            self._ZeroconfClient = Zeroconf()
         else:
             _logsi.LogObject(SILevel.Verbose, "Using existing Zeroconf instance for discovery", zeroconfClient)
         
@@ -299,6 +299,14 @@ class SpotifyClient:
         return self._UserProfile
     
 
+    @property
+    def ZeroconfClient(self) -> Zeroconf:
+        """ 
+        Zeroconf client instance that will be used to discover Spotify Connect devices.
+        """
+        return self._ZeroconfClient
+    
+
     def _CheckForNextPageWithOffset(self, 
                                     pageObj:PageObject,
                                     resultItemsCount,
@@ -6012,7 +6020,7 @@ class SpotifyClient:
             # 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._Zeroconf, printToConsole=False)
+            discovery:SpotifyDiscovery = SpotifyDiscovery(self._ZeroconfClient, printToConsole=False)
             discovery.DiscoverDevices(timeout=self._SpotifyConnectDiscoveryTimeout)
 
             # process all discovered devices.
@@ -7882,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:
@@ -10184,7 +10273,7 @@ class SpotifyClient:
             # 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._Zeroconf, printToConsole=False)
+            discovery:SpotifyDiscovery = SpotifyDiscovery(self._ZeroconfClient, printToConsole=False)
             discovery.DiscoverDevices(timeout=self._SpotifyConnectDiscoveryTimeout)
 
             # process all discovered devices.

spotifywebapipython/spotifydiscovery.py

@@ -65,7 +65,7 @@ class SpotifyDiscovery:
         self._DiscoveredDeviceNames:dict = {}
         self._DiscoveryResults:list[ZeroconfDiscoveryResult] = []
         self._PrintToConsole:bool = printToConsole
-        self._Zeroconf = zeroconfClient
+        self._ZeroconfClient = zeroconfClient
 
 
     def __getitem__(self, key):
@@ -113,6 +113,14 @@ class SpotifyDiscovery:
         return self._DiscoveryResults
 
 
+    @property
+    def ZeroconfClient(self) -> Zeroconf:
+        """ 
+        Zeroconf client instance that will be used to discover Spotify Connect devices.
+        """
+        return self._ZeroconfClient
+    
+
     def _OnServiceStateChange(self,
                               zeroconf:Zeroconf, 
                               service_type:str, 
@@ -234,7 +242,7 @@ class SpotifyDiscovery:
 
         # create the zeroconf service browser that will start device discovery.
         _logsi.LogVerbose("Discovery of Spotify Connect devices via Zeroconf is starting ...")
-        ServiceBrowser(self._Zeroconf, "_spotify-connect._tcp.local.", handlers=[self._OnServiceStateChange])
+        ServiceBrowser(self._ZeroconfClient, "_spotify-connect._tcp.local.", handlers=[self._OnServiceStateChange])
         
         try:
             # give the ServiceBrowser time to discover