spotifywebapiPython 1.0.39__py3-none-any.whl → 1.0.41__py3-none-any.whl

spotifywebapipython/spotifyclient.py

@@ -1,17 +1,20 @@
 # external package imports.
 import base64
+from datetime import datetime
 import json
 from io import BytesIO
 from oauthlib.oauth2 import BackendApplicationClient, WebApplicationClient
+import time
 from typing import Tuple, Callable
 from urllib3 import PoolManager, Timeout, HTTPResponse
 from urllib.parse import urlencode
+from lxml.etree import fromstring, Element
 
 # our package imports.
 from .oauthcli import AuthClient
 from .models import *
 from .models import UserProfile as UserProfileCurrentUser
-from .sautils import export, GetUnixTimestampMSFromUtcNow
+from .sautils import export, GetUnixTimestampMSFromUtcNow, _xmlGetInnerText
 from .saappmessages import SAAppMessages
 from .spotifyapierror import SpotifyApiError
 from .spotifyapimessage import SpotifyApiMessage
@@ -29,6 +32,7 @@ from .const import (
     TRACE_METHOD_RESULT_TYPE_PAGE,
     TRACE_MSG_AUTHTOKEN_CREATE,
     TRACE_MSG_AUTOPAGING_NEXT,
+    TRACE_MSG_DELAY_DEVICE,
     TRACE_MSG_USERPROFILE,
     TRACE_WARN_SPOTIFY_SEARCH_NO_MARKET,
 )
@@ -37,7 +41,7 @@ CACHE_SOURCE_CACHED:str = "cached"
 CACHE_SOURCE_CURRENT:str = "current"
 
 # get smartinspect logger reference; create a new session for this module name.
-from smartinspectpython.siauto import SIAuto, SILevel, SISession, SIMethodParmListContext
+from smartinspectpython.siauto import SIAuto, SILevel, SISession, SIMethodParmListContext, SISourceId
 import logging
 _logsi:SISession = SIAuto.Si.GetSession(__name__)
 if (_logsi == None):
@@ -409,10 +413,7 @@ class SpotifyClient:
                     # no - treat it as utf-8 encoded data.
                     responseUTF8 = response.data.decode('utf-8')
                     _logsi.LogText(SILevel.Error, "SpotifyClient http response [%s-%s]: '%s' (utf-8)" % (response.status, response.reason, responseUrl), responseUTF8)
-
-                    # at this point we don't know what Spotify Web Api returned, so let's 
-                    # just raise a new exception with the non-JSON response data.
-                    #raise SpotifyWebApiError(response.status, responseUTF8, msg.MethodName, response.reason, _logsi)
+                    responseData = responseUTF8
 
         except SpotifyWebApiError: raise  # pass handled exceptions on thru
         except Exception as ex:
@@ -548,6 +549,32 @@ class SpotifyClient:
         return result
     
 
+    def _ValidateDelay(self, delay:float, default:float=0.5, maxDelay:float=10) -> float:
+        """
+        Validates a delay value.
+        
+        Args:
+            delay (int):
+                The delay value to validate.
+            default (int):
+                The default delay value to set if the user-input delay is not valid.
+            maxDelay (int):
+                The maximum delay value allowed.  
+                Default is 10.
+        """
+        if (isinstance(delay,int)): 
+            delay = float(delay)
+            
+        if (not isinstance(delay,float)) or (delay < 0): 
+            result = default
+        elif (delay > maxDelay): 
+            result = maxDelay
+        else:
+            result = delay
+            
+        return result
+
+
     def _ValidateMarket(self, 
                         market:str,
                         ) -> str:
@@ -640,7 +667,9 @@ class SpotifyClient:
             # formulate the request url.
             url:str = None
             uri:str = msg.Uri
-            if (uri == self.SpotifyApiTokenUrl) or (uri == self.SpotifyApiAuthorizeUrl):
+            if (uri == self.SpotifyApiTokenUrl) \
+            or (uri == self.SpotifyApiAuthorizeUrl) \
+            or (uri.startswith('https:')):
                 url = uri
             else:
                 url = f'{self.SpotifyWebApiUrlBase}{uri}'
@@ -3168,6 +3197,254 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
         
 
+    def GetArtistInfo(self, 
+                      artistId:str, 
+                      ) -> ArtistInfo:
+        """
+        Get artist about information from the Spotify Artist Biography page for the
+        specified Spotify artist ID.
+        
+        Args:
+            artistId (str):  
+                The Spotify ID of the artist.  
+                Example: `6APm8EjxOHSYM5B4i3vT3q`
+                
+        Returns:
+            An `ArtistInfo` object that contains the artist info details.
+                
+        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/GetArtistInfo.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'GetArtistInfo'
+        apiMethodParms:SIMethodParmListContext = None
+        result:ArtistInfo = None
+        
+        ABOUT_MONTHLY_LISTENERS:str = ' monthly listeners'
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("artistId", artistId)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify catalog information for a single artist", apiMethodParms)
+                
+            # execute spotify web api request.
+            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/artists/{id}'.format(id=artistId))
+            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+            self.MakeRequest('GET', msg)
+
+            # process results.
+            artist = Artist(root=msg.ResponseData)
+            _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(artist).__name__), artist, excludeNonPublic=True)
+        
+            # create base result.
+            result = ArtistInfo(artist.Id, artist.Name, artist.Type, artist.Uri, artist.ImageUrl)
+            
+            # does artist have a bio information url?  if not then we are done.
+            if (artist.Href is None) or (len(artist.Href.strip()) == 0):
+                _logsi.LogVerbose("No html returned for artist details page: '%s'" % (artist.ExternalUrls.Spotify))
+                return result
+
+            # was a Spotify external url specified for the artist?  if not then we are done.
+            if artist.ExternalUrls is None or artist.ExternalUrls.Spotify is None:
+                return artist
+            
+            # retrieve artist details page.
+            msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, artist.ExternalUrls.Spotify)
+            msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
+            self.MakeRequest('GET', msg)
+                
+            # log html response.
+            #_logsi.LogHtml(SILevel.Verbose, "GetArtistInfo response HTML", msg.ResponseData)
+            _logsi.LogSource(SILevel.Verbose, "GetArtistInfo response Text", msg.ResponseData, SISourceId.Html)
+                
+            # if no response data then we are done.
+            if not msg.HasResponseData:
+                _logsi.LogVerbose("No html returned for artist details page: '%s'" % (artist.ExternalUrls.Spotify))
+                return result
+                
+            # find the starting <html> tag.
+            # ElementTree fromstring method will fail if initial tag is "<!doctype html>".
+            html:str = msg.ResponseData
+            if html is None:
+                return result
+            if not html.startswith('<html'):
+                idx:int = html.find('<html')
+                if idx == -1:
+                    _logsi.LogVerbose("<html> tag could not be found for artist details page: '%s'" % (artist.ExternalUrls.Spotify))
+                    return result
+                html = html[idx:]
+                _logsi.LogSource(SILevel.Verbose, "GetArtistInfo response Text (starting from '<html')", html, SISourceId.Html)
+                    
+            # log formatted html response.
+            _logsi.LogXml(SILevel.Verbose, "GetArtistInfo response Text (formatted)", html, prettyPrint=True)
+                
+            # load html element tree so we can parse it.
+            doc:Element = fromstring(html)
+            _logsi.LogObject(SILevel.Verbose, "doc Element object", doc)
+                               
+            attrXPath:str = None
+            elm:Element = None
+            elmChild:Element = None
+            innerText:str = None
+
+            # about information - image (button / bio page):
+            attrXPath = './/button[@type="button"]/descendant-or-self::img'
+            _logsi.LogVerbose("Element search 'image button': '%s'" % attrXPath)
+            attrElements:list[Element] = doc.xpath(attrXPath)
+            for elm in attrElements:
+                _logsi.LogObject(SILevel.Verbose, "Element match: '%s'" % attrXPath, elm)
+                attrValue:str = elm.get('src', None)
+                if attrValue is not None:
+                    result.ImageUrl = attrValue
+                    break
+
+            # about information - image (entity-id):
+            # use the internal `_ImageUrl` attribute value to check, as the `ImageUrl` property
+            # will return the `ImageUrlDefault` if `_ImageUrl` attribute was not set.
+            # <img data-testid="artist-entity-image" src="https://i.scdn.co/image/ab6761610000517446196125b56397cd4e0d9c4b" />
+            if result._ImageUrl is None:
+                attrXPath = './/attribute::data-testid[contains(., "artist-entity-image")]/../@src'
+                _logsi.LogVerbose("Element search 'image entity': '%s'" % attrXPath)
+                elmChild = doc.xpath(attrXPath)
+                if elmChild is not None:
+                    _logsi.LogVerbose("Element match: '%s'" % elmChild[0])
+                    result.ImageUrl = elmChild[0]
+                
+            # about information - monthly listeners:
+            # <div data-testid="monthly-listeners-label">2,707,252 monthly listeners</div>
+            attrXPath = './/attribute::data-testid[contains(., "monthly-listeners-label")]/../text()'
+            _logsi.LogVerbose("Element search 'monthly listeners': '%s'" % attrXPath)
+            elmChild = doc.xpath(attrXPath)
+            if elmChild is not None:
+                _logsi.LogVerbose("Element match: '%s'" % elmChild[0])
+                attrValue = elmChild[0].replace(ABOUT_MONTHLY_LISTENERS,'')
+                attrValue = attrValue.replace(',','')
+                attrValue = attrValue.strip()
+                if attrValue.isnumeric:
+                    result.MonthlyListeners = int(attrValue)
+
+            # about information - bio:
+            # <div data-testid="expandable-description">
+            #    <div>
+            #       <div>
+            #          <span>MercyMe is a contemporary Christian music band ...</span>
+            #       </div>
+            #    </div>
+            # </div>                
+            attrXPath = './/attribute::data-testid[contains(., "expandable-description")]/..'
+            _logsi.LogVerbose("Element search 'bio': '%s'" % attrXPath)
+            attrElements:list[Element] = doc.xpath(attrXPath)
+            for elm in attrElements:
+                innerText = _xmlGetInnerText(elm)
+                _logsi.LogObject(SILevel.Verbose, "Element match: '%s' (innerText=%s)" % (attrXPath, innerText), elm)
+                result.Bio = innerText
+                break
+                
+            # about information - on tour dates:
+            # <h2>On tour</h2>
+            # <div><ul><li>
+            #   <a draggable="false" class="x" href="/concert/1plBKlFD04tlsD1ky081qL">
+            #      <time class="x" dateTime="2024-04-04T19:00-07:00">
+            #         <h5 class="x" data-encore-id="type">Apr</h5>
+            #         <h1 class="x" data-encore-id="type">5</h1>
+            #      </time>
+            #      <div class="x">
+            #         <h3 class="x" data-encore-id="type">MercyMe with David Leonard and Newsboys</h3>
+            #         <p class="x" data-encore-id="type"><time class="cR3tL5CgXmgwfJDDKQ2A">Fri, Apr 5</time>accesso ShoWare Center, Kent</p>
+            #      </div>
+            #   </a>
+            # </li></ul></div>
+            attrXPath = './/h2[text()="On tour"]/following-sibling::*/descendant-or-self::a'
+            _logsi.LogVerbose("Element search 'On tour': '%s'" % attrXPath)
+            attrElements:list[Element] = doc.xpath(attrXPath)
+            for elm in attrElements:
+                innerText = _xmlGetInnerText(elm)
+                if innerText is not None:
+                    if innerText.lower() == 'see all':
+                        break
+                _logsi.LogObject(SILevel.Verbose, "Element match: '%s' (innerText=%s)" % (attrXPath, innerText), elm)
+                event:ArtistInfoTourEvent = ArtistInfoTourEvent() 
+                elmChild = elm.xpath('.//time/@dateTime')
+                if elmChild is not None:
+                    try:
+                        attrValue = str(elmChild[0])
+                        idx:int = attrValue.rfind('-')
+                        if idx > 15:  # drop timezone portion of the datetime.
+                            event.EventDateTime = datetime.fromisoformat(attrValue[:idx])
+                    except Exception as ex:
+                        _logsi.LogException("Element value '%s' (%s) could not be parsed to a datetime object" % (elmChild[0], attrValue), ex, logToSystemLogger=False)
+                        event.EventDateTime = None
+                elmChild = elm.xpath('.//h3/text()')
+                if elmChild is not None:
+                    event.Title = elmChild[0]
+                elmChild = elm.xpath('.//p/text()')
+                if elmChild is not None:
+                    event.VenueName = elmChild[0]
+                result.TourEvents.append(event)
+                _logsi.LogObject(SILevel.Verbose, '%s: "%s" (%s)' % (type(event).__name__, event.Title, event.EventDateTime), event, excludeNonPublic=True)
+
+            # about information - links.
+            result.AboutUrlFacebook = self._GetArtistInfoAboutLink(doc,"Facebook")
+            result.AboutUrlInstagram = self._GetArtistInfoAboutLink(doc,"Instagram")
+            result.AboutUrlTwitter = self._GetArtistInfoAboutLink(doc,"Twitter")
+            result.AboutUrlWikipedia = self._GetArtistInfoAboutLink(doc,"Wikipedia")
+                
+            # 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 _GetArtistInfoAboutLink(self, 
+                                doc:Element,
+                                linkTitle:str, 
+                                ) -> str:
+        """
+        Searches artist about page for the specified link title and returns the HREF 
+        attribute value if found; otherwise, null is returned.
+        """
+        result:str = None 
+        
+        # about information - link.
+        # <a href="https://facebook.com/mercyme">
+        #     <div>Facebook</div>
+        # </a>
+        attrXPath:str = './/div[text()="%s"]/parent::a' % linkTitle
+        _logsi.LogVerbose("Element search '%s link': '%s'" % (linkTitle, attrXPath))
+        attrElements:list[Element] = doc.xpath(attrXPath)
+        for elm in attrElements:
+            _logsi.LogObject(SILevel.Verbose, "Element match: '%s'" % attrXPath, elm)
+            attrValue:str = elm.get('href', None)
+            if attrValue is not None:
+                result = attrValue
+                break
+            
+        return result
+                
+
     def GetArtistRelatedArtists(self, 
                                 artistId:str, 
                                 ) -> list[Artist]:
@@ -5689,7 +5966,8 @@ class SpotifyClient:
                 properly handles cases of new types in the future by checking against the type field of each object.
                 
         Returns:
-            A `PlayerPlayState` object that contains the currently playing media, or null if nothing is playing.
+            A `PlayerPlayState` object that contains player state details as well as
+            currently playing content.
                 
         Raises:
             SpotifyWebApiError: 
@@ -5780,7 +6058,8 @@ class SpotifyClient:
                 properly handles cases of new types in the future by checking against the type field of each object.
                 
         Returns:
-            A `PlayerPlayState` object that contains the currently playing media state.
+            A `PlayerPlayState` object that contains player state details as well as
+            currently playing content.
                 
         Raises:
             SpotifyWebApiError: 
@@ -8579,7 +8858,8 @@ class SpotifyClient:
 
 
     def PlayerMediaPause(self, 
-                         deviceId:str=None
+                         deviceId:str=None,
+                         delay:float=0.50
                          ) -> None:
         """
         Pause media play for the specified Spotify Connect device.
@@ -8591,7 +8871,12 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
-                
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
+                                
         Raises:
             SpotifyWebApiError: 
                 If the Spotify Web API request was for a non-authorization service 
@@ -8618,8 +8903,12 @@ class SpotifyClient:
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device pause playback", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
             # build spotify web api request parameters.
             urlParms:dict = {}
             if deviceId is not None:
@@ -8631,6 +8920,11 @@ class SpotifyClient:
             msg.UrlParameters = urlParms
             self.MakeRequest('PUT', 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
@@ -8653,7 +8947,8 @@ class SpotifyClient:
                                offsetUri:str=None,
                                offsetPosition:int=None,
                                positionMS:int=0,
-                               deviceId:str=None
+                               deviceId:str=None,
+                               delay:float=0.50
                                ) -> None:
         """
         Start playing one or more tracks of the specified context on a Spotify Connect device.
@@ -8687,6 +8982,11 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -8732,8 +9032,12 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("offsetPosition", offsetPosition)
             apiMethodParms.AppendKeyValue("positionMS", positionMS)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device play context", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
             # build spotify web api request parameters.
             reqData:dict = \
             {
@@ -8756,6 +9060,102 @@ class SpotifyClient:
             msg.RequestJson = reqData
             self.MakeRequest('PUT', 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
+
+        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 PlayerMediaPlayTrackFavorites(self, 
+                                      deviceId:str=None,
+                                      shuffle:bool=True,
+                                      delay:float=0.50
+                                      ) -> None:
+        """
+        Get a list of the tracks saved in the current Spotify user's 'Your Library'
+        and starts playing them.
+        
+        Args:
+            deviceId (str):
+                The id of the device this command is targeting.  
+                If not supplied, the user's currently active device is the target.  
+                Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            shuffle (bool):
+                True to set player shuffle mode to on; otherwise, False for no shuffle.
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
+                
+        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.
+
+        This API only works for users who have Spotify Premium. 
+        
+        This method simply calls the `GetTrackFavorites` method to retrieve the current users
+        favorite tracks (200 max), then calls the `PlayerMediaPlayTracks` method to play them.  
+        
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/PlayerMediaPlayTrackFavorites.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'PlayerMediaPlayTrackFavorites'
+        apiMethodParms:SIMethodParmListContext = None
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("shuffle", shuffle)
+            apiMethodParms.AppendKeyValue("delay", delay)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device play track favorites", apiMethodParms)
+                
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
+            # get current users favorite tracks.
+            tracks:TrackPageSaved = self.GetTrackFavorites(limitTotal=200)
+            if (tracks.ItemsCount == 0):
+                _logsi.LogVerbose("Current user has no favorite tracks; nothing to do")
+                return
+
+            # build a list of all item uri's.
+            arrUris:list[str] = []
+            trackSaved:TrackSaved
+            for trackSaved in tracks.Items:
+                arrUris.append(trackSaved.Track.Uri)
+
+            # play the tracks.
+            self.PlayerMediaPlayTracks(arrUris, deviceId=deviceId, delay=delay)
+            
+            # set desired shuffle mode.
+            self.PlayerSetShuffleMode(shuffle, deviceId)
+
             # process results.
             # no results to process - this is pass or fail.
             return
@@ -8776,7 +9176,8 @@ class SpotifyClient:
     def PlayerMediaPlayTracks(self, 
                               uris:list[str],
                               positionMS:int=0,
-                              deviceId:str=None
+                              deviceId:str=None,
+                              delay:float=0.50
                               ) -> None:
         """
         Start playing one or more tracks on the specified Spotify Connect device.
@@ -8800,6 +9201,11 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -8829,8 +9235,12 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("uris", uris)
             apiMethodParms.AppendKeyValue("positionMS", positionMS)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device play tracks", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
             # build a list of all item uri's.
             # remove any leading / trailing spaces in case user put a space between the items.
             arrUris:list[str] = None
@@ -8860,6 +9270,11 @@ class SpotifyClient:
             msg.RequestJson = reqData
             self.MakeRequest('PUT', 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
@@ -8878,7 +9293,8 @@ class SpotifyClient:
 
 
     def PlayerMediaResume(self, 
-                          deviceId:str=None
+                          deviceId:str=None,
+                          delay:float=0.50
                           ) -> None:
         """
         Resume media play for the specified Spotify Connect device.
@@ -8890,6 +9306,11 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -8917,8 +9338,13 @@ class SpotifyClient:
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device resume playback", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
+            # build spotify web api request parameters.
             urlParms:dict = {}
             if deviceId is not None:
                 urlParms['device_id'] = deviceId
@@ -8929,6 +9355,11 @@ class SpotifyClient:
             msg.UrlParameters = urlParms
             self.MakeRequest('PUT', 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
@@ -8948,7 +9379,8 @@ class SpotifyClient:
 
     def PlayerMediaSeek(self, 
                         positionMS:int=0,
-                        deviceId:str=None
+                        deviceId:str=None,
+                        delay:float=0.50
                         ) -> None:
         """
         Seeks to the given position in the user's currently playing track for the specified 
@@ -8966,6 +9398,11 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -8994,8 +9431,13 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("positionMS", positionMS)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device seek position", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
+            # build spotify web api request parameters.
             urlParms:dict = \
             {
                 'position_ms': positionMS
@@ -9009,6 +9451,11 @@ class SpotifyClient:
             msg.UrlParameters = urlParms
             self.MakeRequest('PUT', 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
@@ -9027,7 +9474,8 @@ class SpotifyClient:
 
 
     def PlayerMediaSkipNext(self, 
-                            deviceId:str=None
+                            deviceId:str=None,
+                            delay:float=0.50
                             ) -> None:
         """
         Skips to next track in the user's queue for the specified Spotify Connect device.
@@ -9039,6 +9487,11 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -9066,8 +9519,13 @@ class SpotifyClient:
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device skip next", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
+            # build spotify web api request parameters.
             urlParms:dict = {}
             if deviceId is not None:
                 urlParms['device_id'] = deviceId
@@ -9078,6 +9536,11 @@ class SpotifyClient:
             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
@@ -9096,7 +9559,8 @@ class SpotifyClient:
 
 
     def PlayerMediaSkipPrevious(self, 
-                                deviceId:str=None
+                                deviceId:str=None,
+                                delay:float=0.50
                                 ) -> None:
         """
         Skips to previous track in the user's queue for the specified Spotify Connect device.
@@ -9108,6 +9572,11 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -9135,8 +9604,13 @@ class SpotifyClient:
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Spotify Connect device skip previous", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
+            # build spotify web api request parameters.
             urlParms:dict = {}
             if deviceId is not None:
                 urlParms['device_id'] = deviceId
@@ -9147,6 +9621,11 @@ class SpotifyClient:
             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
@@ -9166,7 +9645,8 @@ class SpotifyClient:
 
     def PlayerSetRepeatMode(self, 
                              state:str='off',
-                             deviceId:str=None
+                             deviceId:str=None,
+                             delay:float=0.50
                              ) -> None:
         """
         Set repeat mode for the specified Spotify Connect device.
@@ -9184,6 +9664,11 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -9212,8 +9697,12 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("state", state)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Set Spotify Connect device set repeat mode", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
             # build spotify web api request parameters.
             urlParms:dict = \
             {
@@ -9228,6 +9717,11 @@ class SpotifyClient:
             msg.UrlParameters = urlParms
             self.MakeRequest('PUT', 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
@@ -9247,7 +9741,8 @@ class SpotifyClient:
 
     def PlayerSetShuffleMode(self, 
                              state:bool=False,
-                             deviceId:str=None
+                             deviceId:str=None,
+                             delay:float=0.50
                              ) -> None:
         """
         Set shuffle mode for the specified Spotify Connect device.
@@ -9264,6 +9759,11 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -9292,8 +9792,12 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("state", state)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Set Spotify Connect device set shuffle mode", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
             # build spotify web api request parameters.
             urlParms:dict = \
             {
@@ -9308,6 +9812,11 @@ class SpotifyClient:
             msg.UrlParameters = urlParms
             self.MakeRequest('PUT', 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
@@ -9327,7 +9836,8 @@ class SpotifyClient:
 
     def PlayerSetVolume(self, 
                         volumePercent:int,
-                        deviceId:str=None
+                        deviceId:str=None,
+                        delay:float=0.50
                         ) -> None:
         """
         Set volume level for the specified Spotify Connect device.
@@ -9343,6 +9853,11 @@ class SpotifyClient:
                 The id of the device this command is targeting.  
                 If not supplied, the user's currently active device is the target.  
                 Example: `0d1841b0976bae2a3a310dd74c0f3df354899bc8`
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -9371,8 +9886,12 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("volumePercent", volumePercent)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Set Spotify Connect device set volume level", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
             # build spotify web api request parameters.
             urlParms:dict = \
             {
@@ -9387,6 +9906,11 @@ class SpotifyClient:
             msg.UrlParameters = urlParms
             self.MakeRequest('PUT', 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
@@ -9407,6 +9931,7 @@ class SpotifyClient:
     def PlayerTransferPlayback(self, 
                                deviceId:str=None,
                                play:bool=True,
+                               delay:float=0.50
                                ) -> None:
         """
         Transfer playback to a new Spotify Connect device and optionally begin playback.
@@ -9422,6 +9947,11 @@ class SpotifyClient:
                 - `True`  - ensure playback happens on new device.   
                 - `False` - keep the current playback state.  
                 Default: `True`  
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Raises:
             SpotifyWebApiError: 
@@ -9450,8 +9980,12 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
             apiMethodParms.AppendKeyValue("play", play)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Transfer playback to a new Spotify Connect device", apiMethodParms)
-                
+            
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
             # build spotify web api request parameters.
             reqData:dict = \
             {
@@ -9466,6 +10000,11 @@ class SpotifyClient:
             msg.RequestJson = reqData
             self.MakeRequest('PUT', 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
@@ -9486,6 +10025,7 @@ class SpotifyClient:
     def PlayerVerifyDeviceDefault(self, 
                                   defaultDeviceId:str=None,
                                   play:bool=False,
+                                  delay:float=0.50
                                   ) -> PlayerPlayState:
         """
         Checks to see if there is an active Spotify Connect device, and if not to make one active.
@@ -9505,9 +10045,15 @@ class SpotifyClient:
                 - `True`  - ensure playback happens on new device.   
                 - `False` - keep the current playback state.  
                 Default: `False`  
+            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 
+                another command is issued.  
+                Default is 0.50; value range is 0 - 10.
                 
         Returns:
-            A `PlayerPlayState` object that contains the currently playing media, or null if nothing is playing.
+            A `PlayerPlayState` object that contains player state details as well as
+            currently playing content.
                 
         Raises:
             SpotifyWebApiError: 
@@ -9533,20 +10079,24 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("defaultDeviceId", defaultDeviceId)
             apiMethodParms.AppendKeyValue("play", play)
+            apiMethodParms.AppendKeyValue("delay", delay)
             _logsi.LogMethodParmList(SILevel.Verbose, "Checks if a Spotify Connect device is active, and activate one if not", apiMethodParms)
                 
+            # validations.
+            delay = self._ValidateDelay(delay, 0.50, 10)
+
             # get current Spotify Connect player state.
             result = self.GetPlayerPlaybackState()
             
             # is there an active device set?
-            if (result is None) \
-            or (result.CurrentlyPlayingType is None and result.Context is None) \
-            or (result.Device is None):
+            if (result.CurrentlyPlayingType is None and result.Context is None) \
+            or (result.Device is None) \
+            or (result.Device.Id is None):
                 
                 _logsi.LogVerbose('No active Spotify Connect device was found - activating device "%s"' % defaultDeviceId)
                 
                 # no - transfer control to the default device.
-                self.PlayerTransferPlayback(defaultDeviceId, play)
+                self.PlayerTransferPlayback(defaultDeviceId, play, delay)
                 
                 # get current Spotify Connect player state.
                 result = self.GetPlayerPlaybackState()
@@ -9814,6 +10364,72 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
+    def RemovePlaylist(self, 
+                       playlistId:str, 
+                       ) -> None:
+        """
+        Remove a user's playlist (calls the `UnfollowPlaylist` method).
+        
+        This method requires the `playlist-modify-public` and `playlist-modify-private` scope.
+        
+        Args:
+        
+            playlistId (str):  
+                The Spotify ID of the playlist.
+                Example: `5AC9ZXA7nJ7oGWO911FuDG`
+                
+        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.
+        
+        There is no Spotify Web API endpoint for deleting a playlist.  The notion of deleting a playlist is 
+        not relevant within the Spotify playlist system. Even if you are the playlist owner and you choose 
+        to manually remove it from your own list of playlists, you are simply unfollowing it. Although this 
+        behavior may sound strange, it means that other users who are already following the playlist can keep 
+        enjoying it. 
+        
+        [Manually restoring a deleted playlist](https://www.spotify.com/us/account/recover-playlists/) through 
+        the Spotify Accounts Service is the same thing as following one of your own playlists that you have 
+        previously unfollowed.
+
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/RemovePlaylist.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'RemovePlaylist'
+        apiMethodParms:SIMethodParmListContext = None
+        result:str = None
+        
+        try:
+
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("playlistId", playlistId)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Remove (by unfollowing) a user's playlist", apiMethodParms)
+            
+            # unfollow the playlist for the specified user.
+            return self.UnfollowPlaylist(playlistId)
+                
+        except SpotifyApiError: raise  # pass handled exceptions on thru
+        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 RemovePlaylistItems(self, 
                             playlistId:str, 
                             uris:str=None,
@@ -9839,6 +10455,7 @@ class SpotifyClient:
                 The API will validate that the specified items exist and in the specified positions and 
                 make the changes, even if more recent changes have been made to the playlist.
                 If null, the current playlist is updated.  
+                Example: `MTk3LGEzMjUwZGYwODljNmI5ZjAxZTRjZThiOGI4NzZhM2U5M2IxOWUyMDQ`
                 Default is null.
                 
         Returns:
@@ -10126,6 +10743,7 @@ class SpotifyClient:
             snapshotId (str):  
                 The playlist's snapshot ID against which you want to make the changes.  
                 If null, the current playlist is updated.  
+                Example: `MTk3LGEzMjUwZGYwODljNmI5ZjAxZTRjZThiOGI4NzZhM2U5M2IxOWUyMDQ`
                 Default is null.
                 
         Returns: