spotifywebapiPython 1.0.154__py3-none-any.whl → 1.0.156__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -24,7 +24,7 @@ from zeroconf import Zeroconf
 from .oauthcli import AuthClient
 from .models import *
 from .models import UserProfile as UserProfileCurrentUser
-from .spotifyconnect import SpotifyConnectDirectoryTask
+from .spotifyconnect import SpotifyConnectDirectoryTask, SpotifyConnectDeviceNotFound
 from .saappmessages import SAAppMessages
 from .spotifyapierror import SpotifyApiError
 from .spotifyapimessage import SpotifyApiMessage
@@ -473,6 +473,25 @@ class SpotifyClient:
         return self._ZeroconfClient
     
 
+    def _CheckForDeviceNotFound(
+        self,
+        scDevice:SpotifyConnectDevice,
+        deviceId:str,
+        ) -> None:
+        """
+        Called to raise a SpotifyConnectDeviceNotFound exception when a Spotify Connect 
+        device could not be found and there is no active player.
+        """
+        # was a device resolved?
+        if (scDevice is None):
+
+            # if deviceId could not be resolved, then it's an error.
+            if (deviceId is None) or (deviceId == "*"):
+                raise SpotifyConnectDeviceNotFound("There is no active Spotify player, and a default player device was not configured; select a player device and try again.")
+            else:
+                raise SpotifyConnectDeviceNotFound("Spotify Player device \"%s\" was not found, and there is no active Spotify player; verify the device is active and available on the local network, and try again." % (deviceId))
+
+
     def _CheckForNextPageWithOffset(
         self, 
         pageObj:PageObject,
@@ -1191,6 +1210,9 @@ class SpotifyClient:
         This API only works for users who have Spotify Premium. 
         
         The order of execution is not guaranteed when you use this API with other Player API endpoints.
+
+        For Sonos devices, items are added to the end of the device local queue.
+        For non-Sonos devices, items are added to the end of the user's current playback queue. 
         
         The Spotify Web API endpoint is called to add each item individually.  
         The Spotify Web API does not currently support adding more than 1 item to the queue at a time.
@@ -1228,32 +1250,59 @@ class SpotifyClient:
                 for idx in range(0, len(arrUris)):
                     arrUris[idx] = arrUris[idx].strip()
                 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
-                
-            # process all uri's.
-            for idx in range(0, len(arrUris)):
-                
-                # build spotify web api request parameters.
-                urlParms:dict = \
-                {
-                    'uri': arrUris[idx]
-                }
-                if (scDevice is not None):
-                    urlParms['device_id'] = scDevice.Id
 
-                # execute spotify web api request.
-                msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/queue')
-                msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
-                msg.UrlParameters = urlParms
-                self.MakeRequest('POST', msg)
+            # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
+            if (scDevice is not None) and (scDevice.IsSonos):
 
-                # give spotify web api time to process the change.
-                if delay > 0:
-                    _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % delay)
-                    time.sleep(delay)
+                # trace.
+                _logsi.LogVerbose("Items will be added to Sonos local queue for device: %s" % (scDevice.Title))
+
+                # get the Sonos Controller player instance.
+                sonosPlayer:SoCo = self.SpotifyConnectDirectory.GetSonosPlayer(scDevice)
+
+                # add all track items to the Sonos local queue.
+                sharelink = ShareLinkPlugin(sonosPlayer)
+                for idx in range(0, len(arrUris)):
+
+                    # add track to the Sonos local queue.
+                    uri = arrUris[idx].strip()
+                    _logsi.LogVerbose("Issuing command to Sonos device \"%s\": ADD_SHARE_LINK_TO_QUEUE (uri=%s)" % (scDevice.Name, uri))
+                    sharelink.add_share_link_to_queue(uri)
+
+            else:
+
+                # trace.
+                _logsi.LogVerbose("Items will be added to playback queue for device: %s" % (scDevice.Title))
+                
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
+                # process all uri's.
+                for idx in range(0, len(arrUris)):
+                
+                    # build spotify web api request parameters.
+                    urlParms:dict = \
+                    {
+                        'uri': arrUris[idx]
+                    }
+                    if (scDevice is not None):
+                        urlParms['device_id'] = scDevice.Id
+
+                    # execute spotify web api request.
+                    msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/me/player/queue')
+                    msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+                    msg.UrlParameters = urlParms
+                    self.MakeRequest('POST', msg)
+
+                    # give spotify web api time to process the change.
+                    if delay > 0:
+                        _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE % delay)
+                        time.sleep(delay)
 
-            
             # process results.
             # no results to process - this is pass or fail.
             return
@@ -11544,10 +11593,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: PAUSE" % (scDevice.Title))
@@ -11556,6 +11606,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = {}
                 if (scDevice is not None):
@@ -11703,10 +11757,11 @@ class SpotifyClient:
             if (offsetPosition is None) or (offsetPosition < 0):
                 offsetPosition = 0
 
-            # resolve / activate the device object if needed.
-            scDevice = self._ResolveDeviceObject(deviceId, False)
+            # resolve the device object from the device idl activate if it's dormant.
+            scDevice = self._ResolveDeviceObject(deviceId, True)
 
-            # is this a Sonos device?
+            # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 # trace.
@@ -11783,6 +11838,10 @@ class SpotifyClient:
                 # trace.
                 _logsi.LogVerbose("Context will be played on the Spotify Connect device via Spotify Web API")
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 reqData:dict = \
                 {
@@ -11925,7 +11984,7 @@ class SpotifyClient:
             for trackSaved in tracks.Items:
                 arrUris.append(trackSaved.Track.Uri)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice = self._ResolveDeviceObject(deviceId, False)
 
             # set desired shuffle mode.
@@ -12048,10 +12107,11 @@ class SpotifyClient:
                 for idx in range(0, len(arrUris)):
                     arrUris[idx] = arrUris[idx].strip()
         
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id; activate if it's dormant.
             scDevice = self._ResolveDeviceObject(deviceId, True)
 
-            # is this a Sonos device?
+            # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 # trace.
@@ -12104,6 +12164,10 @@ class SpotifyClient:
                 # trace.
                 _logsi.LogVerbose("Track list will be played on the Spotify Connect device via Spotify Web API")
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 reqData:dict = \
                 {
@@ -12203,10 +12267,12 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
-            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
+            # resolve the device object from the device id; activate if it's dormant.
+            # we activate the device here, as it may have been paused for a long time.
+            scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, True)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: PLAY (RESUME)" % (scDevice.Title))
@@ -12215,6 +12281,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = {}
                 if (scDevice is not None):
@@ -12341,7 +12411,7 @@ class SpotifyClient:
             if (relativePositionMS is None):
                 relativePositionMS = 0
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
            
             # was relative seeking specified?
@@ -12359,6 +12429,7 @@ class SpotifyClient:
                     positionMS = newPositionMS
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 sonosPosition:str = mediaPositionHMS_fromSeconds(positionMS / 1000)    # convert from milliseconds to Sonos H:MM:SS format
@@ -12368,6 +12439,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = \
                 {
@@ -12462,10 +12537,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: NEXT" % (scDevice.Title))
@@ -12474,6 +12550,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = {}
                 if (scDevice is not None):
@@ -12565,10 +12645,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: PREVIOUS" % (scDevice.Title))
@@ -12577,6 +12658,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = {}
                 if (scDevice is not None):
@@ -12676,10 +12761,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 # get current Spotify Connect player state.
@@ -12705,6 +12791,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = \
                 {
@@ -12806,10 +12896,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 # get current Spotify Connect player state.
@@ -12836,6 +12927,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = \
                 {
@@ -12936,10 +13031,11 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id.
             scDevice:SpotifyConnectDevice = self._ResolveDeviceObject(deviceId, False)
 
             # is this an active Sonos device?
+            # Sonos device can still be active, even if there is no active device in Spotify playstate.
             if (scDevice is not None) and (scDevice.IsSonos):
 
                 _logsi.LogVerbose("Issuing command to Sonos device %s: VOLUME = %s" % (scDevice.Title, volumePercent))
@@ -12948,6 +13044,10 @@ class SpotifyClient:
 
             else:
 
+                # was the deviceId resolved? 
+                # if not, then raise an exception as the Spotify Web API request will fail anyway.
+                self._CheckForDeviceNotFound(scDevice, deviceId)
+
                 # build spotify web api request parameters.
                 urlParms:dict = \
                 {
@@ -13104,7 +13204,7 @@ class SpotifyClient:
                 if (scDeviceFrom is not None) and (scDeviceFrom.IsSonos):
                     self.PlayerMediaPause(scDeviceFrom)
 
-            # resolve / activate the device object if needed.
+            # resolve the device object from the device id; activate if it's dormant.
             # for transfer playback, we will always activate the device.
             scDevice = self._ResolveDeviceObject(deviceId, True)
 

spotifywebapipython/spotifyconnect/__init__.py

@@ -4,7 +4,7 @@ from .spotifyconnectdirectorytask import SpotifyConnectDirectoryTask
 from .spotifyconnectzeroconfcastapptask import SpotifyConnectZeroconfCastAppTask
 from .spotifyconnectzeroconfcastcontroller import SpotifyConnectZeroconfCastController
 from .spotifyconnectzeroconfcastlistener import SpotifyConnectZeroconfCastListener
-from .spotifyconnectzeroconfexceptions import SpotifyConnectZeroconfLaunchError, SpotifyConnectZeroconfPlaybackTransferError
+from .spotifyconnectzeroconfexceptions import SpotifyConnectZeroconfLaunchError, SpotifyConnectZeroconfPlaybackTransferError, SpotifyConnectDeviceNotFound
 from .spotifyconnectzeroconflistener import SpotifyConnectZeroconfListener
 
 # all classes to import when "import *" is specified.
@@ -15,5 +15,5 @@ __all__ = [
     'SpotifyConnectZeroconfCastListener',
     'SpotifyConnectDirectoryTask', 
     'SpotifyConnectZeroconfListener',
-    'SpotifyConnectZeroconfLaunchError', 'SpotifyConnectZeroconfPlaybackTransferError',
+    'SpotifyConnectZeroconfLaunchError', 'SpotifyConnectZeroconfPlaybackTransferError', 'SpotifyConnectDeviceNotFound',
 ]

spotifywebapipython/spotifyconnect/spotifyconnectdirectorytask.py

@@ -1308,7 +1308,7 @@ class SpotifyConnectDirectoryTask(threading.Thread):
 
             # if playerState object not supplied, then go get it.
             if (playerState is None):
-                playerState:PlayerPlayState = self._SpotifyClientInstance.GetPlayerPlaybackState()
+                playerState:PlayerPlayState = self._SpotifyClientInstance.GetPlayerPlaybackState(additionalTypes='episode')
 
             # if valid object then process it.
             if (isinstance(playerState, PlayerPlayState)):