spotifywebapiPython 1.0.42__py3-none-any.whl → 1.0.44__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -14,6 +14,7 @@ from lxml.etree import fromstring, Element
 from .oauthcli import AuthClient
 from .models import *
 from .models import UserProfile as UserProfileCurrentUser
+from .models.zeroconfblobbuilder import int_to_b64str
 from .sautils import export, GetUnixTimestampMSFromUtcNow, _xmlGetInnerText
 from .saappmessages import SAAppMessages
 from .spotifyapierror import SpotifyApiError
@@ -40,6 +41,8 @@ from .const import (
 CACHE_SOURCE_CACHED:str = "cached"
 CACHE_SOURCE_CURRENT:str = "current"
 
+SPOTIFY_DJ_PLAYLIST_ID = "37i9dqzf1eykqdzj48dyyq"
+
 # get smartinspect logger reference; create a new session for this module name.
 from smartinspectpython.siauto import SIAuto, SILevel, SISession, SIMethodParmListContext, SISourceId
 import logging
@@ -454,6 +457,19 @@ class SpotifyClient:
             
         elif responseData is not None:
             
+            # if response is a string (e.g. html response) and is not in the 2xx range then 
+            # we will assume it's an error, even though no json 'error' response body was returned!  
+            # this is usually due to a '503 Server Error' response.
+            if (response.status > 299) and (isinstance(responseData, str)):
+
+                errCode = response.status
+                errMessage = response.reason
+                
+                if responseUTF8 is not None:
+                    errMessage = responseUTF8
+
+                raise SpotifyWebApiError(errCode, errMessage, msg.MethodName, response.reason, _logsi)
+            
             # does json response contain error details?
             if CONST_ERROR in responseData:
                 
@@ -669,7 +685,8 @@ class SpotifyClient:
             uri:str = msg.Uri
             if (uri == self.SpotifyApiTokenUrl) \
             or (uri == self.SpotifyApiAuthorizeUrl) \
-            or (uri.startswith('https:')):
+            or (uri.startswith('https:')) \
+            or (uri.startswith('http:')):
                 url = uri
             else:
                 url = f'{self.SpotifyWebApiUrlBase}{uri}'
@@ -705,9 +722,13 @@ class SpotifyClient:
             # call the appropriate poolmanager request method.
             if msg.HasUrlParameters:
                 
-                # add querystring parameters to url.
+                # add querystring parameters to url; if url already has a partial parm
+                # string (e.g. has a '?xxx=...') then use the append separator (e.g. '...&xxx=...').
                 urlQS:str = urlencode(msg.UrlParameters)
-                url = url + '?' + urlQS
+                urlParmSep:str = '?'
+                if (url.find('?') > 0):
+                    urlParmSep = '&'
+                url = url + urlParmSep + urlQS
                 
                 _logsi.LogDictionary(SILevel.Verbose, "SpotifyClient http request: '%s' (with urlparms)" % (url), msg.UrlParameters, prettyPrint=True)
                 response = self._Manager.request_encode_url(method, url, headers=msg.RequestHeaders)
@@ -793,9 +814,10 @@ class SpotifyClient:
                 The uri of the item to add to the queue; must be a track or an episode uri.  
                 Example: `spotify:track:4iV5W9uYEdYUVa79Axb7Rh`
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
                 
         Raises:
             SpotifyWebApiError: 
@@ -826,6 +848,10 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
             _logsi.LogMethodParmList(SILevel.Verbose, "Add item to playback queue", apiMethodParms)
                 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
+            # build spotify web api request parameters.
             urlParms:dict = \
             {
                 'uri': uri
@@ -5826,7 +5852,7 @@ class SpotifyClient:
                     result = item
                     break
                 
-            # if no match by id, then try to macth by device name.
+            # if no match by id, then try to match by device name.
             if result is None:
                 for item in devices:
                     if deviceId == item.Name.lower():
@@ -5850,6 +5876,115 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
+    def PlayerConvertDeviceNameToId(self, 
+                                    value:str, 
+                                    refresh:bool=False
+                                    ) -> str:
+        """
+        Converts a Spotify Connect player device name to it's equivalent id value if
+        the value is a device name.  If the value is a device id, then the value is 
+        returned as-is.
+        
+        This method requires the `user-read-playback-state` scope.
+
+        Args:
+            value (str):
+                The device id or name value to check.
+            refresh (bool):
+                True to resolve the device real-time from the spotify web api device list; 
+                otherwise, False (default) to use the cached device list to resolve the device.
+                
+        Returns:
+            One of the following:  
+            - if value is a device id, then the value is returned as-is; no device list 
+              lookup is performed, and the value is assumed to be a valid device id.  
+            - if value is not a device id, then it is assumed to be a name; a device list
+              lookup is performed to retrieve it's device id.  if found, then the id is
+              returned; otherwise, the value is returned as-is with the understanding that
+              subsequent operations will fail since it's not in the device list.  
+                
+        Raises:
+            SpotifyWebApiError: 
+                If the Spotify Web API request was for a non-authorization service 
+                and the response contains error information.
+            SpotifApiError: 
+                If the method fails for any other reason.
+
+        The id for the first match found on the device name will be returned if multiple devices 
+        are found in the Spotify Connect player device list that have the same name (with different 
+        id's).  Care should be taken to make device names unique if using device names for
+        methods that require a device id or name.
+        
+        If the `refresh` argument is specified, then the `ConfigurationCache` is updated with 
+        the latest Spotify Connect player device list.  Use the `refresh` argument (with False 
+        value) to retrieve the cached value and avoid the spotify web api request.  This results 
+        in better performance.
+                        
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/PlayerConvertDeviceNameToId.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'PlayerConvertDeviceNameToId'
+        apiMethodParms:SIMethodParmListContext = None
+
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("value", value)
+            apiMethodParms.AppendKeyValue("refresh", refresh)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Checking Spotify Connect Player device for name", apiMethodParms)
+
+            # if nothing specified then just use it as-is.
+            if (value is None) or (len(value.strip()) == 0):
+                _logsi.LogVerbose("Device ID not specified; active device will be used")
+                return value
+
+            try:
+            
+                # is this a hex string value?
+                intValue:int = int(str(value), 16)
+            
+                # if it IS a hex string, then it should have been converted to a number.
+                # at this point we can assume it's a device id.  in this case, just return it.
+                # note that we will NOT perform a lookup in the device list 
+                _logsi.LogVerbose("Device id '%s' was specified, and will be used as-is" % value)
+                if intValue is not None:
+                    return value
+                return value
+            
+            except Exception:
+            
+                # the above will fail if it's a device name.
+                pass
+
+            # try resolving the device name to a device id value.
+            device:Device = self.GetPlayerDevice(value, refresh)
+            if device is not None:
+                _logsi.LogVerbose("Converted device name '%s' to device id '%s'" % (value, device.Id))
+                return device.Id
+
+            # if a name could not be found in the Spotify Connect Player devices then just 
+            # return the value as-is.
+            _logsi.LogVerbose("Device name '%s' could not be found in the Spotify Connect Device list; subsequent actions will probably fail using this device name" % value)
+            return value
+
+        except SpotifyWebApiError: raise  # pass handled exceptions on thru
+        except SpotifyWebApiAuthenticationError: 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 GetPlayerDevices(self, 
                          refresh:bool=True
                          ) -> list[Device]:
@@ -6437,6 +6572,27 @@ class SpotifyClient:
                 
             # ensure market was either supplied or implied; default if neither.
             market = self._ValidateMarket(market)
+            
+            # was the Spotify DJ playlist specified?
+            # the DJ is not fully integrated with the playlist API, so the GET request will fail.
+            # we will manually build a basic playlist object to return for the playlist.
+            if (playlistId is not None) and (playlistId.lower() == SPOTIFY_DJ_PLAYLIST_ID):
+                
+                # build basic playlist response.
+                result = Playlist()
+                result._Collaborative = False
+                result._Description = 'Spotify DJ Playlist'
+                result._ExternalUrls._Spotify = 'https://open.spotify.com/playlist/%s' % playlistId
+                result._Id = playlistId
+                result._Name = 'DJ'
+                result._Public = False
+                result._Type = 'playlist'
+                result._Uri = 'spotify:playlist:%s' % playlistId
+                               
+                # trace.
+                _logsi.LogVerbose("Spotify DJ Playlist detected; request will be bypassed, and a basic PlayList object returned")
+                _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
+                return result
 
             # build spotify web api request parameters.
             urlParms:dict = {}
@@ -8868,9 +9024,10 @@ class SpotifyClient:
 
         Args:
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -8909,6 +9066,9 @@ class SpotifyClient:
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             urlParms:dict = {}
             if deviceId is not None:
@@ -8979,9 +9139,10 @@ class SpotifyClient:
                 Default is `0`.  
                 Example: `25000`  
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -9038,6 +9199,9 @@ class SpotifyClient:
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             reqData:dict = \
             {
@@ -9093,9 +9257,10 @@ class SpotifyClient:
         
         Args:
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             shuffle (bool):
                 True to set player shuffle mode to on; otherwise, False for no shuffle.
             delay (float):
@@ -9150,6 +9315,9 @@ class SpotifyClient:
             for trackSaved in tracks.Items:
                 arrUris.append(trackSaved.Track.Uri)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # set desired shuffle mode.
             self.PlayerSetShuffleMode(shuffle, deviceId, delay)
 
@@ -9198,9 +9366,10 @@ class SpotifyClient:
                 Default is `0`.  
                 Example: `25000`  
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -9251,6 +9420,9 @@ class SpotifyClient:
                 for idx in range(0, len(arrUris)):
                     arrUris[idx] = arrUris[idx].strip()
                 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             reqData:dict = \
             {
@@ -9303,9 +9475,10 @@ class SpotifyClient:
 
         Args:
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -9344,6 +9517,9 @@ class SpotifyClient:
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             urlParms:dict = {}
             if deviceId is not None:
@@ -9395,9 +9571,10 @@ class SpotifyClient:
                 player to start playing the next song.
                 Example: `25000`  
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -9437,6 +9614,9 @@ class SpotifyClient:
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             urlParms:dict = \
             {
@@ -9484,9 +9664,10 @@ class SpotifyClient:
 
         Args:
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -9525,6 +9706,9 @@ class SpotifyClient:
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             urlParms:dict = {}
             if deviceId is not None:
@@ -9569,9 +9753,10 @@ class SpotifyClient:
 
         Args:
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -9610,6 +9795,9 @@ class SpotifyClient:
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             urlParms:dict = {}
             if deviceId is not None:
@@ -9661,9 +9849,10 @@ class SpotifyClient:
                 - `off`     - will turn repeat off.
                 Default: `off`  
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -9703,6 +9892,9 @@ class SpotifyClient:
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             urlParms:dict = \
             {
@@ -9756,9 +9948,10 @@ class SpotifyClient:
                 - `False` - Do not shuffle user's playback.
                 Default: `False`  
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -9798,6 +9991,9 @@ class SpotifyClient:
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             urlParms:dict = \
             {
@@ -9850,9 +10046,10 @@ class SpotifyClient:
                 Must be a value from 0 to 100 inclusive.
                 Example: `50`
             deviceId (str):
-                The id of the device this command is targeting.  
+                The id or name of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             delay (float):
                 Time delay (in seconds) to wait AFTER issuing the command to the player.  
                 This delay will give the spotify web api time to process the change before 
@@ -9892,6 +10089,9 @@ class SpotifyClient:
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
 
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
+
             # build spotify web api request parameters.
             urlParms:dict = \
             {
@@ -9940,8 +10140,9 @@ class SpotifyClient:
 
         Args:
             deviceId (str):
-                The id of the device on which playback should be started/transferred.
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                The id or name of the device on which playback should be started/transferred.
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
+                Example: `Web Player (Chrome)`  
             play (bool):
                 The transfer method:  
                 - `True`  - ensure playback happens on new device.   
@@ -9985,6 +10186,9 @@ class SpotifyClient:
             
             # validations.
             delay = self._ValidateDelay(delay, 0.50, 10)
+            
+            # check for device name; convert to an id if a name was supplied.
+            deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
             # build spotify web api request parameters.
             reqData:dict = \
@@ -10038,8 +10242,8 @@ class SpotifyClient:
         Args:
             defaultDeviceId (str):
                 The id of the device on which playback should be started/transferred if there is
-                currently no active device.
-                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+                currently no active device.  
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`  
             play (bool):
                 The transfer method:  
                 - `True`  - ensure playback happens on new device.   
@@ -13615,3 +13819,251 @@ class SpotifyClient:
         
             # trace.
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
+
+    def ZeroconfGetInformation(self, 
+                               actionUrl:str,
+                               ) -> ZeroconfGetInfo:
+        """
+        Retrieve Spotify Connect device information from the Spotify Zeroconf API `getInfo` endpoint.
+        
+        Args:
+            actionUrl (str):  
+                The Zeroconf action url to issue the request to.  
+                Example: `http://192.168.1.80:8200/zc?action=getInfo`
+                
+        Returns:
+            An `ZeroconfGetInfo` object that contains the response.
+                
+        Raises:
+            SpotifyWebApiError: 
+                If the Spotify Web API request was for a non-authorization service 
+                and the response contains error information.
+            SpotifApiError: 
+                If the method fails for any other reason.
+
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/ZeroconfGetInformation.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'ZeroconfGetInformation'
+        apiMethodParms:SIMethodParmListContext = None
+        result:ZeroconfGetInfo = None
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("actionUrl", actionUrl)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify Zeroconf getInfo response", apiMethodParms)
+                
+            # execute spotify zeroconf api request.
+            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, actionUrl)
+            self.MakeRequest('GET', msg)
+
+            # process results.
+            result = ZeroconfGetInfo(root=msg.ResponseData)
+        
+            # trace.
+            _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
+            return result
+
+        except SpotifyWebApiError: raise  # pass handled exceptions on thru
+        except SpotifyWebApiAuthenticationError: 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 ZeroconfResetUsers(self, 
+                           actionUrl:str,
+                           ) -> ZeroconfResponse:
+        """
+        Reset users for a Spotify Connect device by calling the Spotify Zeroconf API `resetUsers` endpoint.
+        
+        Args:
+            actionUrl (str):  
+                The Zeroconf action url to issue the request to.  
+                Example: `http://192.168.1.80:8200/zc?action=resetUsers`
+                
+        Returns:
+            An `ZeroconfResponse` object that contains the response.
+                
+        Raises:
+            SpotifyWebApiError: 
+                If the Spotify Web API request was for a non-authorization service 
+                and the response contains error information.
+            SpotifApiError: 
+                If the method fails for any other reason.
+
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/ZeroconfResetUsers.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'ZeroconfResetUsers'
+        apiMethodParms:SIMethodParmListContext = None
+        result:ZeroconfResponse = None
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("actionUrl", actionUrl)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify Zeroconf GetInfo response", apiMethodParms)
+                
+            # execute spotify zeroconf api request.
+            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, actionUrl)
+            self.MakeRequest('GET', msg)
+
+            # process results.
+            result = ZeroconfResponse(root=msg.ResponseData)
+        
+            # trace.
+            _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
+            return result
+
+        except SpotifyWebApiError: raise  # pass handled exceptions on thru
+        except SpotifyWebApiAuthenticationError: 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 ZeroconfAddUser(self, 
+                        actionUrl:str,
+                        getInfoResponse:ZeroconfGetInfo,
+                        username:str,
+                        password:str,
+                        ) -> ZeroconfResponse:
+        """
+        Add a user to a Spotify Connect device by calling the Spotify Zeroconf API `addUser` endpoint.
+        
+        Args:
+            actionUrl (str):  
+                The Zeroconf action url to issue the request to.  
+                Example: `http://192.168.1.80:8200/zc?action=addUser&version=1.0`
+                
+        Returns:
+            An `ZeroconfResponse` object that contains the response.
+                
+        Raises:
+            SpotifyWebApiError: 
+                If the Spotify Web API request was for a non-authorization service 
+                and the response contains error information.
+            SpotifApiError: 
+                If the method fails for any other reason.
+
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/ZeroconfGetInformation.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'ZeroconfAddUser'
+        apiMethodParms:SIMethodParmListContext = None
+        result:ZeroconfResponse = None
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("actionUrl", actionUrl)
+            apiMethodParms.AppendKeyValue("getInfoResponse", getInfoResponse)
+            apiMethodParms.AppendKeyValue("username", username)
+            apiMethodParms.AppendKeyValue("password", password)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify Zeroconf addUser response", apiMethodParms)
+            
+            raise NotImplemented()
+
+            # build credentials object.
+            self.credentials = ZeroconfCredentials(username, password)
+
+            # build authentication blob.
+            builder = ZeroconfBlobBuilder(self.credentials, getInfoResponse.DeviceId, getInfoResponse.PublicKey)
+            blob = builder.build()
+
+            # # call zeroconf to add the user to the device.
+            # r = self._add_user(
+            #     self.credentials.username.decode('ascii'),
+            #     int_to_b64str(builder.dh_keys.public_key),
+            #     blob)
+
+        # def _add_user(self, username: str, client_key: str, blob: str): # -> bool
+        #     respone = requests.post(
+        #         self.uri,
+        #         headers={
+        #             'Content-Type': 'application/x-www-form-urlencoded'
+        #         },
+        #         params={
+        #             'action': 'addUser',
+        #             'userName': username,
+        #             'clientKey': client_key,
+        #             'blob': blob
+        #         }
+        #     )
+        #     return respone
+
+            # build spotify zeroconf addUser parameters.
+            urlParms:dict = \
+            {
+                'userName': self.credentials.username.decode('ascii'),
+                'clientKey': int_to_b64str(builder.dh_keys.public_key),
+                'blob': blob,
+                'deviceId': getInfoResponse.DeviceId,
+                'deviceName': getInfoResponse.RemoteName,
+                'loginId': 'xxxxxxxxxxx',
+            }
+
+    # let params = [
+    #   3  ("action", "addUser"),
+    #   3  ("userName", username),
+    #   3  ("blob", blob),
+    #   3  ("clientKey", my_public_key),
+    #     ("deviceId", &device_id),
+    #     ("deviceName", "spotify-connect"),
+    #     ("loginId", &login_id),
+        
+            
+            # execute spotify zeroconf api request.
+            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, actionUrl)
+            msg.UrlParameters = urlParms
+            self.MakeRequest('POST', msg)
+
+            # process results.
+            result = ZeroconfResponse(root=msg.ResponseData)
+
+            # trace.
+            _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
+            return result
+
+        except SpotifyWebApiError: raise  # pass handled exceptions on thru
+        except SpotifyWebApiAuthenticationError: 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)