spotifywebapiPython 1.0.150__py3-none-any.whl → 1.0.152__py3-none-any.whl

spotifywebapipython/spotifyconnect/spotifyconnectdirectorytask.py

@@ -6,12 +6,14 @@ from datetime import datetime
 import hashlib
 from pychromecast import CastBrowser, CastInfo, Chromecast, get_chromecast_from_cast_info
 import socket
+from soco import SoCo
 import threading
 import time
 from uuid import UUID
 from zeroconf import Zeroconf, ServiceBrowser
 
 # our package imports.
+from .spotifyconnectzeroconfexceptions import SpotifyConnectDeviceNotFound
 from .spotifyconnectzeroconfcastapptask import SpotifyConnectZeroconfCastAppTask
 from .spotifyconnectzeroconfcastlistener import SpotifyConnectZeroconfCastListener
 from .spotifyconnectdeviceeventargs import SpotifyConnectDeviceEventArgs
@@ -101,6 +103,7 @@ class SpotifyConnectDirectoryTask(threading.Thread):
         self._CastBrowser:CastBrowser = None
         self._InitialDiscoveryTimeout = initialDiscoveryTimeout
         self._IsStopRequested:bool = False
+        self._SonosPlayers:dict = {}
         self._SpotifyClientInstance = spotifyClientInstance
         self._SpotifyConnectBrowser:ServiceBrowser = None
         self._SpotifyConnectDevices:SpotifyConnectDevices = SpotifyConnectDevices()
@@ -731,33 +734,42 @@ class SpotifyConnectDirectoryTask(threading.Thread):
         self,
         value:str,
         refreshDynamicDevices:bool=True,
+        raiseExceptionIfNotFound:bool=True,
         ) -> SpotifyConnectDevice:
         """
-        Returns a `SpotifyConnectDevice` object for the specified device name / id if found;
-        otherwise, an exception is returned indicating a device was not found.
+        Returns a `SpotifyConnectDevice` object for the specified device name / id if found
+        in the devices collection. otherwise, returns the currently active player
+        `SpotifyConnectDevice` object is returned.  otherwise, null is returned.
 
         Args:
-            value (str):
-                Spotify Connect device name or id value used to identify the device,
-                or null to retrieve the currently active Spotify Player device,
-                or an asterisk (*) to use the SpotifyPlus configured default device.
+            value (str | None):
+                The target player device identifier.
+                This could be an id, name, a default device indicator (e.g. "*"), or null
+                to utilize the active player device.  
+                Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             refreshDynamicDevices (bool):
                 True to refresh the list of dynamically added devices and the active player
                 state from real-time Spotify Web API data; otherwise, false to use the
                 current cached state and device list.
                 Default is True.
+            raiseExceptionIfNotFound (bool):
+                True to raise an exception if a device could not be resolved;
+                otherwise, False to just return a null value.  
+                Default is True.
 
         Returns:
-            A `SpotifyConnectDevice` object for the specified device name / id.
+            A `SpotifyConnectDevice` object for the specified device name / id if found;
+            otherwise, null.
 
         Raises:
+            SpotifyConnectDeviceNotFound:
+                If the `raiseExceptionIfNotFound` argument value is True, and the specified 
+                device value was not found or there was no default device found.
             SpotifyApiError: 
-                If the specified device value was not found.
-                If there was no defaualt device found.
                 If an error occured while obtaining current Spotify Web API Player device data.
 
-        The object returned is a copy of the internal master device entry; any changes made
-        to the copy do not affect the internal master device entry.
+        If a SpotifyConnectDevice object is returned, it will be a copy of the internal master 
+        device entry; any changes made to the copy do not affect the internal master device entry.
 
         <details>
           <summary>Sample Code</summary>
@@ -788,6 +800,8 @@ class SpotifyConnectDirectoryTask(threading.Thread):
                     value = None
                 if (not isinstance(refreshDynamicDevices, bool)):
                     refreshDynamicDevices = True
+                if (not isinstance(raiseExceptionIfNotFound, bool)):
+                    raiseExceptionIfNotFound = True
                 valueOriginal:str = value
 
                 # get currently active player device.
@@ -804,6 +818,10 @@ class SpotifyConnectDirectoryTask(threading.Thread):
                         _logsi.LogObject(SILevel.Verbose, "Spotify Player device \"%s\" (%s) was found in the Spotify Connect Devices collection (by Active PlayerState)" % (scActiveDevice.Name, scActiveDevice.Id), scActiveDevice, excludeNonPublic=True)
                         return scActiveDevice
 
+                    # if no active player device, then let's use the default device value.
+                    _logsi.LogVerbose("Spotify Player has no active device; defaulting device selection to use DefaultDeviceId: \"%s\"" % (self.SpotifyClientInstance.DefaultDeviceId))
+                    value = self.SpotifyClientInstance.DefaultDeviceId
+
                 # was a default device value specified?
                 # if so, then use the `defaultDeviceId` value; if the `defaultDeviceId` value is not in the device list, 
                 # then we will catch it with the `GetDeviceById` / `GetDeviceByName` logic.
@@ -822,7 +840,7 @@ class SpotifyConnectDirectoryTask(threading.Thread):
                             _logsi.LogObject(SILevel.Verbose, "Spotify Player default device (*) was not configured; using active player device: %s" % (scActiveDevice.Title), scActiveDevice, excludeNonPublic=True)
                             return scActiveDevice
                         # if no default device and no active player, then it's an error!
-                        raise SpotifyApiError("Spotify Player default device (*) was not configured, and there is no active Spotify Player device", logsi=_logsi)
+                        #raise SpotifyApiError("Spotify Player default device (*) was not configured, and there is no active Spotify Player device", logsi=_logsi)
                     
                     # assign default device value.
                     _logsi.LogVerbose("Spotify Player device default \"%s\" will be used for selecting a device (by default *)" % (defaultDeviceId))
@@ -858,8 +876,13 @@ class SpotifyConnectDirectoryTask(threading.Thread):
                         _logsi.LogObject(SILevel.Verbose, "Spotify Player default device \"%s\" was not found in the Spotify Connect Devices collection; using active player device: %s" % (value, scActiveDevice.Title), scActiveDevice, excludeNonPublic=True)
                         return scActiveDevice
 
-                # at this point we could not resolve the device name / id!
-                raise SpotifyApiError("Spotify Player device \"%s\" was not found in the Spotify Connect Devices collection" % (value), logsi=_logsi)
+                # at this point we could not resolve the device name / id, and there is no active player
+                # available; raise exception / return null as requested by the caller.
+                if (raiseExceptionIfNotFound):
+                    raise SpotifyConnectDeviceNotFound("Spotify Player device \"%s\" was not found, and there is no active Spotify player" % (value))
+                else:
+                    _logsi.LogVerbose("Spotify Player device \"%s\" was not found, and there is no active Spotify player" % (value))
+                    return None
 
             except SpotifyApiError: raise  # pass handled exceptions on thru
             except Exception as ex:
@@ -957,6 +980,50 @@ class SpotifyConnectDirectoryTask(threading.Thread):
             return result
 
 
+    def GetSonosPlayer(
+        self, 
+        device:SpotifyConnectDevice,
+        ) -> SoCo:
+        """ 
+        Returns the Sonos Controller instance for the specified Spotify Connect device.
+        Returns the Sonos player instance for the specified Spotify Connect Sonos device.
+        
+        Args:
+            device (SpotifyConnectDevice):
+                Spotify Connect device instance used to identify the Sonos player.
+
+        Returns:
+            The Sonos Controller instance for the specified Spotify Connect device.
+
+        Raises:
+            SpotifyApiError:
+                If a Sonos Controller instance could not be found for the device id.
+
+        You should invoke "if (scDevice.IsSonos):" logic prior to calling this method, as
+        a Sonos Controller instance will not be created for non-Sonos devices and an exception
+        will be raised!
+        """
+        apiMethodName:str = "GetSonosPlayer"
+
+        # syncronize access via lock, as we are accessing the collection.
+        with self._SpotifyConnectDevices_RLock:
+
+            result:SpotifyConnectDevice = None
+
+            # validations.
+            if (device is None):
+                raise SpotifyApiError(SAAppMessages.ARGUMENT_REQUIRED_ERROR % (apiMethodName, 'device'), logsi=_logsi)
+
+            # get Sonos Controller instance for device name.
+            sonosPlayer:SoCo = self._SonosPlayers.get(device.DiscoveryResult.HostIpAddress, None)
+
+            # if not found then it's an error.
+            if (sonosPlayer is None):
+                raise SpotifyApiError("Could not find Sonos Controller instance for device: %s" % (device.Title), None, logsi=_logsi)
+
+            return sonosPlayer
+
+
     def GetSpotifyDeviceIDFromName(
         self, 
         name:str
@@ -1013,9 +1080,9 @@ class SpotifyConnectDirectoryTask(threading.Thread):
 
                 # trace.
                 if (scDevice is None):
-                    _logsi.LogVerbose("Spotify Player playstate active device is not present; no active device")
+                    _logsi.LogVerbose("Spotify Player playstate device is not present; no active device")
                 else:
-                    _logsi.LogObject(SILevel.Verbose, "Spotify Player playstate active device instance %s" % (scDevice.Title), scDevice, excludeNonPublic=True)
+                    _logsi.LogObject(SILevel.Verbose, "Spotify Player playstate active device instance: %s" % (scDevice.Title), scDevice, excludeNonPublic=True)
 
                 # return real-time active Spotify Player device.
                 return scDevice
@@ -1738,6 +1805,21 @@ class SpotifyConnectDirectoryTask(threading.Thread):
                     if (len(self._SpotifyConnectDevices.Items) > 0):
                         self._SpotifyConnectDevices.Items.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
 
+                    try:
+
+                        # if new device is a Sonos, then create a Sonos Controller instance for the device.
+                        # use device ip address as the key, as Spotify Web API reports id=null for restricted devices in playerstate!
+                        if (scDevice.IsSonos):
+                            _logsi.LogVerbose("Sonos device detected; creating Sonos Controller instance for device: %s (ip=%s)" % (scDevice.Title, zeroconfDiscoveryResult.HostIpAddress))
+                            self._SonosPlayers[zeroconfDiscoveryResult.HostIpAddress] = SoCo(zeroconfDiscoveryResult.HostIpAddress)
+
+                    except:
+
+                        # trace.
+                        _logsi.LogException("%s - Could not create Sonos Control API reference: %s" % (self.name, str(ex)), ex, logToSystemLogger=False)
+            
+                        # ignore exceptions, as there is nothing we can do at this point.
+
                     # raise event.
                     self._RaiseDeviceAdded(scDevice)
 

spotifywebapipython/spotifyconnect/spotifyconnectzeroconfexceptions.py

@@ -1,3 +1,7 @@
+# our package imports.
+from spotifywebapipython import SpotifyApiError
+
+
 class SpotifyConnectZeroconfLaunchError(Exception):
     """
     Exception raised when a cast app fails to launch.
@@ -8,3 +12,9 @@ class SpotifyConnectZeroconfPlaybackTransferError(Exception):
     """
     Exception raised when a cast app fails to receive transfer of playback control.
     """
+
+
+class SpotifyConnectDeviceNotFound(SpotifyApiError):
+    """
+    Exception raised when a Spotify Connect device could not be resolved.
+    """