spotifywebapiPython 1.0.147__py3-none-any.whl → 1.0.149__py3-none-any.whl

spotifywebapipython/spotifywebplayertoken.py

@@ -0,0 +1,344 @@
+# external package imports.
+from datetime import datetime, timedelta, timezone
+import json
+import os.path
+import platformdirs
+import requests
+import time
+from tokenize import TokenError
+
+# our package imports.
+from .const import (
+    SPOTIFY_WEBUI_URL_BASE,
+    SPOTIFYWEBAPIPYTHON_TOKEN_CACHE_FILE,
+)
+
+# get smartinspect logger reference; create a new session for this module name.
+from smartinspectpython.siauto import SIAuto, SILevel, SISession, SIMethodParmListContext
+import logging
+_logsi:SISession = SIAuto.Si.GetSession(__name__)
+if (_logsi == None):
+    _logsi = SIAuto.Si.AddSession(__name__, True)
+_logsi.SystemLogger = logging.getLogger(__name__)
+
+
+SPOTIFY_WEBUI_URL_GET_ACCESS_TOKEN = SPOTIFY_WEBUI_URL_BASE + "/get_access_token"
+""" Url used to get access token. """
+
+
+class SpotifyWebPlayerToken:
+    """
+    Represents a Spotify web player token for an account.
+    """
+
+    def __init__(
+        self, 
+        clientId:str=None,
+        profileId:str=None,
+        tokenProviderId:str=None,
+        tokenStorageDir:str=None,
+        tokenStorageFile:str=None,
+        ) -> None:
+        """
+        Initializes a new instance of the class.
+
+        Args:
+            clientId (str):
+                The unique identifier of the application.
+                A null value will default to `Shared`.  
+                Default: `Shared`
+            profileId (str):
+                Profile identifier used when loading / storing the token to disk.  
+                A null value will default to `Shared`.  
+                Default: `Shared`
+            tokenProviderId (str):
+                Provider identifier used when storing the token to disk.
+                A null value will default to `Shared`.  
+                Default: `Shared`
+            tokenStorageDir (str):
+                The directory path that will contain the Token Cache file.  
+                A null value will default to the platform specific storage location:  
+                Example for Windows OS = `C:\\ProgramData\\SpotifyWebApiPython`
+            tokenStorageFile (str):
+                The filename and extension of the Token Cache file.  
+                Default is `tokens.json`.
+        """
+        # validations.
+        if clientId is None:
+            clientId = "Shared"
+        if profileId is None:
+            profileId = 'Shared'
+
+        # verify token storage directory exists.
+        if tokenStorageDir is None:
+            tokenStorageDir = platformdirs.site_config_dir('SpotifyWebApiPython', ensure_exists=True, appauthor=False)
+        os.makedirs(tokenStorageDir, exist_ok=True)  # succeeds even if directory exists.
+
+        # verify token storage filename was specified.
+        if tokenStorageFile is None:
+            tokenStorageFile = SPOTIFYWEBAPIPYTHON_TOKEN_CACHE_FILE
+
+        # if token providerId not set, then default to shared.
+        if tokenProviderId is None:
+            tokenProviderId = 'SpotifyWebPlayerCookieCredentials'
+
+        # initializa storage.
+        self._AccessToken = None
+        self._ClientId:str = clientId
+        self._ExpiresAt:int = 0
+        self._ExpireDateTimeUtc:datetime = None
+        self._ExpiresIn:int = 0
+        self._IsAnonymous:bool = False
+        self._ProfileId:str = profileId
+        self._TokenProviderId:str = tokenProviderId
+        self._TokenStorageDir:str = tokenStorageDir
+        self._TokenStorageFile:str = tokenStorageFile
+        self._TokenStoragePath:str = os.path.join(tokenStorageDir, tokenStorageFile)
+
+        # load cookie credentials from the token storage file.
+        token:dict = self._LoadCookieCredentials()
+
+        # get Spotify Web Player access token from stored Spotify Web Player cookie credentials.
+        self.GetAccessTokenFromCookieCredentials()
+
+
+    @property
+    def AccessToken(self) -> str:
+        """ 
+        An access token that can be provided to a Spotify Web Player application.
+        """
+        return self._AccessToken
+
+
+    @property
+    def ClientId(self) -> str:
+        """
+        The unique identifier of the application.
+        """
+        return self._ClientId
+
+
+    @property
+    def ExpiresAt(self) -> int:
+        """ 
+        DateTime (in epoch seconds) that the authorization token will expire.
+        """
+        return self._ExpiresAt
+    
+
+    @property
+    def ExpireDateTimeUtc(self) -> datetime:
+        """ 
+        DateTime (in UTC format) that the authorization token will expire.
+        """
+        return self._ExpireDateTimeUtc
+
+
+    @property
+    def ExpiresIn(self) -> int:
+        """ 
+        The time period (in seconds) for which the access token is valid.
+        """
+        return self._ExpiresIn
+    
+
+    @property
+    def IsExpired(self) -> bool:
+        """ 
+        Returns true if the token has expired; otherwise, False if not expired.
+        """
+        if self._ExpiresAt is not None:
+            nowsecs:int = int(time.time())
+            # subtract 30 seconds in case we are right at the edge of expiring.
+            if (nowsecs + 30) > self._ExpiresAt:
+                return True
+        return False
+    
+
+    @property
+    def ProfileId(self) -> str:
+        """ 
+        Profile identifier used when loading / storing the token to disk.
+        """
+        return self._ProfileId
+    
+
+    def _LoadCookieCredentials(self) -> dict:
+        """
+        Loads a token from the token storage file for the ProviderId / ClientId key.
+        
+        Returns:
+            A token dictionary, if one was found in the token storage file for the
+            specified ProviderId and ClientId key; otherwise, null.
+        """
+        apiMethodName:str = '_LoadCookieCredentials'
+        apiMethodParms:SIMethodParmListContext = None
+        
+        try:
+
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Loading Spotify Web Player cookie credentials from token storage", apiMethodParms)
+                
+            # formulate token storage key.
+            tokenKey:str = f'{self._TokenProviderId}/{self._ClientId}/{self._ProfileId}'
+            _logsi.LogVerbose("Cookie credentials storage key: \"%s\"" % (tokenKey))           
+            _logsi.LogVerbose("Cookie credentials storage file path: \"%s\"" % (self._TokenStoragePath))
+            
+            # does the token storage file exist?
+            if os.path.exists(self._TokenStoragePath):
+
+                # open the token storage file, and load it's contents.
+                _logsi.LogVerbose("Opening cookie credentials token storage file")
+                with open(self._TokenStoragePath, 'r') as f:
+                    
+                    tokens = json.load(f)
+
+                    # if token key exists then load the token.
+                    if tokenKey in tokens:
+                        _logsi.LogDictionary(SILevel.Verbose, "Cookie credentials were loaded from token storage file for provider: \"%s\"" % (tokenKey), tokens[tokenKey], prettyPrint=True)
+
+                        # parse token for cookie data parameters.
+                        token:dict = tokens[tokenKey]
+                        self._sp_dc:str = token.get("sp_dc", None)
+                        self._sp_key:str = token.get("sp_key", None)
+
+                        # validation.
+                        if (self._sp_dc is None):
+                            raise TokenError("Cookie credentials storage key \"%s\" did not contain an \"sp_dc\" key value" % (tokenKey))
+                        if (self._sp_key is None):
+                            raise TokenError("Cookie credentials storage key \"%s\" did not contain an \"sp_key\" key value" % (tokenKey))
+
+                        # return token to caller.
+                        return tokens[tokenKey]
+                    
+            # if we make it here, then it denotes that a token was not found
+            # for the specified key.
+            raise TokenError("Cookie credentials storage key not found: \"%s\"" % (tokenKey))
+                        
+        except TokenError as ex:
+
+            # trace.
+            _logsi.LogException(str(ex), ex, logToSystemLogger=False)
+            raise
+
+        except Exception as ex:
+            
+            # trace.
+            _logsi.LogException("Could not load Spotify Web Player cookie credentials", ex, logToSystemLogger=False)
+            raise TokenError(str(ex))
+
+        finally:
+        
+            # trace.
+            _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
+    def GetAccessTokenFromCookieCredentials(self) -> None:
+        """ 
+        Get Spotify Web Player access token from stored Spotify Web Player cookie
+        credentials.
+
+        This will create a new session to the "https://open.spotify.com" url, passing
+        it the stored cookie credentials.
+        """
+        apiMethodName:str = 'GetAccessTokenFromCookieCredentials'
+        apiMethodParms:SIMethodParmListContext = None
+        tracePrefix:str = 'SpotifyWebPlayerAccessToken exchange'
+        
+        try:
+
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("sp_dc", self._sp_dc)
+            apiMethodParms.AppendKeyValue("sp_key", self._sp_key)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Exchange Spotify Web Player cookie credentials for OAuth2 authorization access token", apiMethodParms)
+
+            # create a session, using the specified header and generated cookie data.
+            session = requests.Session()
+            reqHeaders = {'user-agent': "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36"}
+            reqCookies = {'sp_dc': self._sp_dc, 'sp_key': self._sp_key}
+            reqParms={
+                "reason": "transport",
+                "productType": "web_player",
+            }
+
+            # trace.
+            _logsi.LogVerbose("Exchanging Spotify Web Player cookie credentials for OAuth2 authorization access token")
+            _logsi.LogDictionary(SILevel.Verbose, "%s http request: \"%s\" (cookies)" % (tracePrefix, SPOTIFY_WEBUI_URL_GET_ACCESS_TOKEN), reqCookies)
+            _logsi.LogDictionary(SILevel.Debug, "%s http request: \"%s\" (headers)" % (tracePrefix, SPOTIFY_WEBUI_URL_GET_ACCESS_TOKEN), reqHeaders)
+            _logsi.LogDictionary(SILevel.Verbose, "%s http request: \"%s\" (parms)" % (tracePrefix, SPOTIFY_WEBUI_URL_GET_ACCESS_TOKEN), reqParms)
+            
+            # convert the spotify web player cookie credentials to an access token.
+            response = session.get(
+                SPOTIFY_WEBUI_URL_GET_ACCESS_TOKEN, 
+                cookies=reqCookies,
+                headers=reqHeaders, 
+                params=reqParms,
+                allow_redirects=False,
+                )
+
+            # trace.
+            if _logsi.IsOn(SILevel.Debug):
+                _logsi.LogObject(SILevel.Debug, "%s http response object - type=\"%s\", module=\"%s\"" % (tracePrefix, type(response).__name__, type(response).__module__), response)
+
+            # trace.
+            if _logsi.IsOn(SILevel.Debug):
+                _logsi.LogObject(SILevel.Debug, "%s http response [%s-%s] (response)" % (tracePrefix, response.status_code, response.reason), response)
+                if (response.headers):
+                    _logsi.LogCollection(SILevel.Debug, "%s http response [%s-%s] (headers)" % (tracePrefix, response.status_code, response.reason), response.headers.items())
+
+            # raise exception if we could not get the access token, or if a redirect occured.
+            # the redirect usually indicates the sp_dc and sp_key are expired, and it's redirecting to a login page.
+            if (response.status_code == 302 and response.headers["Location"] == "/get_access_token?reason=transport&productType=web_player&_authfailed=1"):
+                _logsi.LogError("Unsuccessful token request, received code 302 and Location header %s. sp_dc and sp_key could be expired. Please update values in token storage file.", response.headers["Location"])
+                raise TokenError("Expired sp_dc, sp_key; please update values in token storage file")
+            if response.status_code != 200:
+                _logsi.LogVerbose("Unsuccessful token request, received code %i", response.status_code)
+                raise TokenError("Token exchange request failed: %s - %s" % (response.status_code, response.reason))
+
+            # load request response.
+            data = response.content.decode('utf-8')
+            responseData = json.loads(data)
+
+            # trace.
+            if _logsi.IsOn(SILevel.Verbose):
+                if isinstance(responseData, dict):
+                    _logsi.LogDictionary(SILevel.Verbose, "%s http response [%s-%s] (json dict)" % (tracePrefix, response.status_code, response.reason), responseData, prettyPrint=True)
+                elif isinstance(responseData, list):
+                    _logsi.LogArray(SILevel.Verbose, "%s http response [%s-%s] (json array)" % (tracePrefix, response.status_code, response.reason), responseData)
+                else:
+                    _logsi.LogObject(SILevel.Verbose, "%s http response [%s-%s] (json object)" % (tracePrefix, response.status_code, response.reason), responseData)
+
+            # process the access token information.
+            self._AccessToken = responseData.get('accessToken', None)
+            self._ExpiresAt = int(responseData.get('accessTokenExpirationTimestampMs', 0)) // 1000
+            self._ExpiresIn = self._ExpiresAt - int(time.time())
+            self._IsAnonymous = bool(responseData.get('isAnonymous', False))
+
+            # set non-JSON response properties.
+            # calculate expire time based on ExpiresAt (epoch) seconds.
+            self._ExpireDateTimeUtc = datetime.utcfromtimestamp(self._ExpiresAt)
+
+            # the following can be used if the `datetime.utcfromtimestamp` is ever removed from python:
+            # unix_epoch = datetime(1970, 1, 1)
+            # dtUtcNow:datetime = datetime.now(timezone.utc)
+            # self._ExpireDateTimeUtc = dtUtcNow + timedelta(seconds=self._ExpiresIn)
+
+            # trace.
+            _logsi.LogObject(SILevel.Verbose, "Spotify Web Player access token object", self, excludeNonPublic=True)
+
+        except requests.TooManyRedirects as ex:
+
+            _logsi.LogException("Could not get Spotify Web Player access token; sp_dc and sp_key could be expired; Please update values in token storage file", ex, logToSystemLogger=False)
+            raise TokenError("Expired sp_dc, sp_key")
+        
+        except Exception as ex: 
+
+            _logsi.LogException("Could not get Spotify Web Player access token", ex, logToSystemLogger=False)
+            raise TokenError("Could not get Spotify Web Player access token")
+
+        finally:
+
+            # trace.
+            _logsi.LeaveMethod(SILevel.Debug, apiMethodName)

spotifywebapipython/zeroconfapi/zeroconfgetinfo.py

@@ -31,7 +31,7 @@ class ZeroconfGetInfo(ZeroconfResponse):
         self._Availability:str = ""
         self._BrandDisplayName:str = None
         self._ClientId:str = None
-        self._DeviceId:str = None
+        self._DeviceId:str = ""
         self._DeviceType:str = None
         self._GroupStatus:str = None
         self._LibraryVersion:str = None
@@ -47,10 +47,6 @@ class ZeroconfGetInfo(ZeroconfResponse):
         self._Version:str = None
         self._VoiceSupport:str = None
         
-        # non-Spotify properties.
-        self._IsActiveDevice:bool = None
-        self._IsInDeviceList:bool = None
-        
         if (root is None):
 
             pass
@@ -62,7 +58,7 @@ class ZeroconfGetInfo(ZeroconfResponse):
             self._Availability = root.get('availability', "")
             self._BrandDisplayName = root.get('brandDisplayName', None)
             self._ClientId = root.get('clientID', None)
-            self._DeviceId = root.get('deviceID', None)
+            self._DeviceId = root.get('deviceID', "")
             self._DeviceType = root.get('deviceType', None)
             self._GroupStatus = root.get('groupStatus', None)
             self._LibraryVersion = root.get('libraryVersion', None)
@@ -121,7 +117,7 @@ class ZeroconfGetInfo(ZeroconfResponse):
         Sets the ActiveUser property value.
         """
         if (isinstance(value, str)) or (value is None):
-            self._ActiveUser = value
+            self._ActiveUser = value or ""
 
 
     @property
@@ -203,7 +199,7 @@ class ZeroconfGetInfo(ZeroconfResponse):
         Sets the DeviceId property value.
         """
         if (isinstance(value, str)) or (value is None):
-            self._DeviceId = value
+            self._DeviceId = value or ""
 
 
     @property
@@ -448,44 +444,6 @@ class ZeroconfGetInfo(ZeroconfResponse):
         return self._VoiceSupport
 
 
-    # non-Spotify properties.
-
-    @property
-    def IsActiveDevice(self) -> bool:
-        """ 
-        Returns True if this device is the currently active device;
-        otherwise, False.
-        """
-        return self._IsActiveDevice
-    
-    @IsActiveDevice.setter
-    def IsActiveDevice(self, value:bool):
-        """ 
-        Sets the IsActiveDevice property value.
-        """
-        if isinstance(value, bool):
-            self._IsActiveDevice = value
-
-
-    @property
-    def IsInDeviceList(self) -> bool:
-        """ 
-        Returns the status of active device list verification:  
-        * None - device list verification has not been performed for this device.  
-        * True - device is a member of the active device list.  
-        * False - device is NOT a member of the active device list.  
-        """
-        return self._IsInDeviceList
-    
-    @IsInDeviceList.setter
-    def IsInDeviceList(self, value:bool):
-        """ 
-        Sets the IsInDeviceList property value.
-        """
-        if isinstance(value, bool):
-            self._IsInDeviceList = value
-
-
     def Equals(self, obj) -> bool:
         """
         Returns true if the specified object instance contains the same argument
@@ -522,8 +480,6 @@ class ZeroconfGetInfo(ZeroconfResponse):
 
         # don't compare the following:
         # self._Aliases:list[ZeroconfGetInfoAlias] = []
-        # self._IsActiveDevice:bool = None
-        # self._IsInDeviceList:bool = None
         # self._SupportedDrmMediaFormats:list[ZeroconfGetInfoDrmMediaFormat] = []
         
         # objects attributes are equal.
@@ -566,8 +522,6 @@ class ZeroconfGetInfo(ZeroconfResponse):
             'HasAliases': self.HasAliases,
             'IsAvailable': self.IsAvailable,
             'IsBrandSonos': self.IsBrandSonos,
-            'IsActiveDevice': self._IsActiveDevice,
-            'IsInDeviceList': self._IsInDeviceList,
         }
         
         # combine base class results with these results.
@@ -614,6 +568,4 @@ class ZeroconfGetInfo(ZeroconfResponse):
         if self._TokenType is not None: msg = '%s\n TokenType="%s"' % (msg, str(self._TokenType))
         if self._Version is not None: msg = '%s\n Version="%s"' % (msg, str(self._Version))
         if self._VoiceSupport is not None: msg = '%s\n VoiceSupport="%s"' % (msg, str(self._VoiceSupport))
-        if self._IsActiveDevice is not None: msg = '%s\n IsActiveDevice="%s"' % (msg, str(self._IsActiveDevice))
-        if self._IsInDeviceList is not None: msg = '%s\n IsInDeviceList="%s"' % (msg, str(self._IsInDeviceList))
         return msg 

spotifywebapipython/zeroconfapi/zeroconfresponse.py

@@ -53,6 +53,14 @@ class ZeroconfResponse:
         """
         return self._ResponseSource
 
+    @ResponseSource.setter
+    def ResponseSource(self, value:str):
+        """ 
+        Sets the ResponseSource property value.
+        """
+        if (isinstance(value, str)) or (value is None):
+            self._ResponseSource = value or ""
+
 
     @property
     def SpotifyError(self) -> int: