spotifywebapiPython 1.0.162__py3-none-any.whl → 1.0.164__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -4,11 +4,9 @@ from datetime import datetime
 import json
 from io import BytesIO
 from oauthlib.oauth2 import BackendApplicationClient, WebApplicationClient
-import socket
 from soco import SoCo
 from soco.core import (
     PLAY_MODE_BY_MEANING as SONOS_PLAY_MODE_BY_MEANING,
-    PLAY_MODES as SONOS_PLAY_MODES,
 )
 from soco.plugins.sharelink import ShareLinkPlugin
 import time
@@ -16,7 +14,7 @@ from typing import Tuple, Callable, Union
 from urllib3 import PoolManager, Timeout, HTTPResponse
 from urllib.parse import urlencode
 import urllib.parse
-from lxml.etree import fromstring, Element, tostring
+from lxml.etree import fromstring, Element
 from lxml import etree
 from zeroconf import Zeroconf
 
@@ -202,6 +200,7 @@ class SpotifyClient:
         self._AuthClient:AuthClient = None
         self._ConfigurationCache:dict = {}
         self._DefaultDeviceId:str = None
+        self._IsDisposed:bool = False
         self._Manager:PoolManager = manager
         self._SpotifyConnectUsername:str = spotifyConnectUsername
         self._SpotifyConnectPassword:str = spotifyConnectPassword
@@ -243,7 +242,7 @@ class SpotifyClient:
         Finalizes the instance of the class.
         """
         try:
-            self.StopSpotifyConnectDirectoryTask()
+            self.Dispose()
         except:
             # ignore exceptions since we are shutting down.
             pass
@@ -257,7 +256,7 @@ class SpotifyClient:
     def __exit__(self, etype, value, traceback) -> None:
         # if called via a context manager (e.g. "with" statement).
         try:
-            self.StopSpotifyConnectDirectoryTask()
+            self.Dispose()
         except:
             # ignore exceptions since we are shutting down.
             pass
@@ -487,7 +486,7 @@ class SpotifyClient:
 
             # 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.")
+                raise SpotifyConnectDeviceNotFound("There is no active Spotify player device, and a default player device was not configured.")
             else:
                 raise SpotifyConnectDeviceNotFound("Spotify Player device \"%s\" was not found in the Spotify Connect device list; verify the device is discoverable via Zeroconf on the local network." % (deviceId))
 
@@ -976,6 +975,51 @@ class SpotifyClient:
         return SPOTIFY_DEFAULT_MARKET
 
 
+    def Dispose(self) -> None:
+        """
+        Releases all resources of this instance.
+
+        This method stops the Spotify Connect Directory task, and ensures
+        that any event wirings are removed.
+        """
+        apiMethodName:str = 'Dispose'
+
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Disposing of SpotifyClient instance", apiMethodParms)
+
+            # are we already disposed? if so, then don't do it again!
+            if (self._IsDisposed == True):
+                _logsi.LogVerbose("SpotifyClient instance is already disposed")
+                return
+            else:
+                # indicate we are disposed (or in the process thereof).
+                self._IsDisposed = True
+
+            # shut down the directory task.
+            try:
+                self.StopSpotifyConnectDirectoryTask()
+            except Exception as ex:
+                pass  # ignore exceptions as they have already been logged.
+
+            # trace.
+            _logsi.LogVerbose("Disposal of SpotifyClient instance completed successfully")
+
+        except Exception as ex:
+            
+            # log unhandled exception.
+            _logsi.LogException(SAAppMessages.UNHANDLED_EXCEPTION.format(apiMethodName, str(ex)), ex)
+
+            # ignore exceptions as we are disposing!
+
+        finally:
+
+            # trace.
+            _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
     def MakeRequest(
         self, 
         method:str, 
@@ -1191,10 +1235,7 @@ class SpotifyClient:
                 not be resolved or activated.
                 Examples are `0d1841b0976bae2a3a310dd74c0f3df354899bc8`, `Office`, `*`, None.  
             verifyDeviceId (bool):
-                DEPRECATED - deviceId is automatically verified as of v1.0.149.
-                True to verify a device id is active; otherwise, false to assume that a
-                device id is already active.  
-                Default is True.  
+                DEPRECATED - no longer used, but left here to maintain compatibility.
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the add request.  This delay will give the 
                 Spotify web api time to process the queue change before another command is issued.  
@@ -2039,10 +2080,10 @@ class SpotifyClient:
                 The Spotify ID of the playlist.  
                 Example: `3cEYpjA9oz9GiPac4AsH4n`
             userIds (str):  
+                DEPRECATED - A single item list containing current user's Spotify Username; Maximum of 1 id.
                 A comma-separated list of Spotify User ID's to check.  
                 Maximum: 5 ID's.  
                 Example: `1kWUud3vY5ij5r62zxpTRy,2takcwOaAZWiXQijPHIx7B`  
-                DEPRECATED - A single item list containing current user's Spotify Username; Maximum of 1 id.
                 
         Returns:
             Array of boolean, containing a single boolean status that indicates 
@@ -9593,19 +9634,13 @@ class SpotifyClient:
                 The device id / name value to check.
             verifyUserContext (bool):
                 DEPRECATED - no longer used, but left here to maintain compatibility.
-                If True, the active user context of the resolved device is checked to ensure it
-                matches the user context specified on the class constructor.
-                If False, the user context will not be checked.
-                Default is True.
             verifyTimeout (float):
                 Maximum time to wait (in seconds) for the device to become active in the Spotify
                 Connect device list.  This value is only used if a Connect command has to be
                 issued to activate the device.
                 Default is 5; value range is 0 - 10.
             refreshDeviceList (bool):
-                True to refresh the Spotify Connect device list; otherwise, False to use the 
-                Spotify Connect device list cache.  
-                Default is False.  
+                DEPRECATED - no longer used, but left here to maintain compatibility.
             activateDevice (bool):
                 True to activate the device if necessary; otherwise, False.  
                 Default is True.  
@@ -9664,7 +9699,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("deviceValue", deviceValue)
             apiMethodParms.AppendKeyValue("verifyUserContext (DEPRECATED)", verifyUserContext)
             apiMethodParms.AppendKeyValue("verifyTimeout", verifyTimeout)
-            apiMethodParms.AppendKeyValue("refreshDeviceList", refreshDeviceList)
+            apiMethodParms.AppendKeyValue("refreshDeviceList (DEPRECATED)", refreshDeviceList)
             apiMethodParms.AppendKeyValue("activateDevice", activateDevice)
             apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify Connect Device object for deviceValue \"%s\"" % (deviceValue), apiMethodParms)
@@ -9674,8 +9709,6 @@ class SpotifyClient:
             verifyTimeout = validateDelay(verifyTimeout, 5, 10)
             if (activateDevice is None):
                 activateDevice = True
-            if (refreshDeviceList is None):
-                refreshDeviceList = False
 
             # resolve the device id from the specified device value.
             # returned value will be null if the device could not be resolved!
@@ -9802,9 +9835,9 @@ class SpotifyClient:
                 if sonosMusicSource != "SPOTIFY_CONNECT":
                     _logsi.LogVerbose("Sonos device %s music source after Connect is not SPOTIFY_CONNECT; it will probably fail to play" % (scDevice.Title))
 
-                # at this point the Sonos music source should be set to SPOTIFY_CONNECT, and control
-                # transferred to the device.  note that the Sonos device will still NOT appear in the 
-                # player device list, but SHOULD be the active (restricted) device in player state.
+            # at this point the Sonos music source should be set to SPOTIFY_CONNECT, and control
+            # transferred to the device.  note that the Sonos device will still NOT appear in the 
+            # player device list, but SHOULD be the active (restricted) device in player state.
                 
             # wait for the device to enter the Spotify Web API player device list, or
             # to become the active device.  
@@ -9876,10 +9909,7 @@ class SpotifyClient:
                 True (default) to return real-time information about devices and update the cache;
                 otherwise, False to just return the cached value.
             sortResult (bool):
-                DEPRECATED - no longer used, as the collection is always sorted by default.
-                True to sort the items by name; otherwise, False to leave the items in the same order they 
-                were returned in by the Spotify Web API.  
-                Default: True
+                DEPRECATED - no longer used, but left here to maintain compatibility.
         
         Returns:
             A `SpotifyConnectDevices` object that contain Spotify Connect devices that are registered
@@ -11661,9 +11691,10 @@ class SpotifyClient:
 
         Args:
             contextUri (str):
-                Spotify URI of the context to play.  
+                Spotify URI (or URL) of the context to play.  
                 Valid contexts are albums, artists & playlists.  
                 Example: `spotify:album:6vc9OTcyd3hyzabCmsdnwE`.   
+                Example: `https://open.spotify.com/playlist/4ufyQwaLq1MR49KvGRCNAo`.   
             offsetUri (str):
                 Indicates from what Uri in the context playback should start.  
                 Only available when contextUri corresponds to an artist, album or playlist.  
@@ -11696,10 +11727,7 @@ class SpotifyClient:
                 another command is issued.  
                 Default is 0.50; value range is 0 - 10.
             resolveDeviceId (bool):
-                DEPRECATED - device id resolution is now automatic.
-                True to resolve the supplied `deviceId` value; otherwise, False not resolve the `deviceId`
-                value as it has already been resolved.  
-                Default is True.  
+                DEPRECATED - no longer used, but left here to maintain compatibility.
                 
         Raises:
             SpotifyWebApiError: 
@@ -11921,10 +11949,7 @@ class SpotifyClient:
                 another command is issued.  
                 Default is 0.50; value range is 0 - 10.
             resolveDeviceId (bool):
-                DEPRECATED - device id resolution is now automatic.
-                True to resolve the supplied `deviceId` value; otherwise, False not resolve the `deviceId`
-                value as it has already been resolved.  
-                Default is True.  
+                DEPRECATED - no longer used, but left here to maintain compatibility.
             limitTotal (int):
                 The maximum number of items to retrieve from favorites.  
                 Default is 200; value range is 1 - 750.  
@@ -12058,10 +12083,7 @@ class SpotifyClient:
                 another command is issued.  
                 Default is 0.50; value range is 0 - 10.
             resolveDeviceId (bool):
-                DEPRECATED - device id resolution is now automatic.
-                True to resolve the supplied `deviceId` value; otherwise, False not resolve the `deviceId`
-                value as it has already been resolved.  
-                Default is True.  
+                DEPRECATED - no longer used, but left here to maintain compatibility.
                 
         Raises:
             SpotifyWebApiError: 
@@ -13124,9 +13146,7 @@ class SpotifyClient:
                 another command is issued.  
                 Default is 0.50; value range is 0 - 10.
             refreshDeviceList (bool):
-                True to refresh the Spotify Connect device list; otherwise, False to use the 
-                Spotify Connect device list cache.  
-                Default is True.  
+                DEPRECATED - no longer used, but left here to maintain compatibility.
             forceActivateDevice (bool):
                 True to issue a Spotify Connect Disconnect call prior to transfer, which will
                 force the device to reconnect to Spotify Connect; otherwise, False to not
@@ -13177,7 +13197,7 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
             apiMethodParms.AppendKeyValue("play", play)
             apiMethodParms.AppendKeyValue("delay", delay)
-            apiMethodParms.AppendKeyValue("refreshDeviceList", refreshDeviceList)
+            apiMethodParms.AppendKeyValue("refreshDeviceList (DEPRECATED)", refreshDeviceList)
             apiMethodParms.AppendKeyValue("forceActivateDevice", forceActivateDevice)
             apiMethodParms.AppendKeyValue("deviceIdFrom", deviceIdFrom)
             _logsi.LogMethodParmList(SILevel.Verbose, "Transfer playback to a new Spotify Connect device", apiMethodParms)
@@ -13186,8 +13206,6 @@ class SpotifyClient:
             delay = validateDelay(delay, 0.50, 10)
             if (play is None):
                 play = True
-            if (refreshDeviceList is None):
-                refreshDeviceList = True
             if (forceActivateDevice is None):
                 forceActivateDevice = True
 

spotifywebapipython/spotifyconnect/spotifyconnectdirectorytask.py

@@ -346,6 +346,23 @@ class SpotifyConnectDirectoryTask(threading.Thread):
 
         finally:
 
+            try:
+
+                # unwire event handlers.
+                _logsi.LogVerbose("%s - Unwiring event handlers" % (self.name))
+                if (self.DeviceAdded is not None):
+                    self.DeviceAdded -= self.OnDeviceAdded
+                if (self.DeviceRemoved is not None):
+                    self.DeviceRemoved -= self.OnDeviceRemoved
+                if (self.DeviceUpdated is not None):
+                    self.DeviceUpdated -= self.OnDeviceUpdated
+
+            except:
+
+                # trace.
+                _logsi.LogException("%s - An unhandled exception occured while unwiring event handlers: %s" % (self.name, str(ex)), ex, logToSystemLogger=False)
+                # ignore exceptions, since we are shutting down.
+
             try:
 
                 # stop spotify connect zeroconf discovery browser.