spotifywebapiPython 1.0.85__py3-none-any.whl → 1.0.87__py3-none-any.whl

spotifywebapipython/oauthcli/authclient.py

@@ -57,7 +57,8 @@ class AuthClient:
                  tokenProviderId:str=None,
                  tokenProfileId:str=None,
                  tokenStorageDir:str=None,
-                 tokenUpdater:Callable=None
+                 tokenStorageFile:str=None,
+                 tokenUpdater:Callable=None,
                  ) -> None:
         """
         Initializes a new instance of the class.
@@ -93,9 +94,12 @@ class AuthClient:
                 A null value will default to `Shared`.  
                 Default: `Shared`
             tokenStorageDir (str):
-                The directory path that will contain the `tokens.json` file.  
+                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`.
             tokenUpdater (Callable):
                 A method to call when a token needs to be refreshed by an external provider.  
                 The defined method is called with no parameters, and should return a token dictionary.  
@@ -110,6 +114,10 @@ class AuthClient:
             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 = 'tokens.json'
+
         # if token providerId not set, then default to shared.
         if tokenProviderId is None:
             tokenProviderId = 'Shared'
@@ -128,7 +136,8 @@ class AuthClient:
         self._Session:OAuth2Session = oauth2Session
         self._TokenProviderId:str = tokenProviderId
         self._TokenStorageDir:str = tokenStorageDir
-        self._TokenStoragePath:str = os.path.join(tokenStorageDir, 'tokens.json')
+        self._TokenStorageFile:str = tokenStorageFile
+        self._TokenStoragePath:str = os.path.join(tokenStorageDir, tokenStorageFile)
         self._TokenUpdater:Callable = tokenUpdater
         self._TokenUrl:str = tokenUrl
         self._TokenProfileId:str = tokenProfileId
@@ -383,9 +392,10 @@ class AuthClient:
     @staticmethod
     def HasTokenForKey(
         clientId:str=None,
+        tokenProviderId:str=None,
         tokenProfileId:str=None,
         tokenStorageDir:str=None,
-        tokenProviderId:str=None,
+        tokenStorageFile:str=None,
         ) -> bool:
         """
         Checks if a token exists in the token storage file for the ProviderId \ ClientId key.
@@ -401,6 +411,9 @@ class AuthClient:
                 The directory path that will contain the `tokens.json` 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`.
         
         Returns:
             True if the token was found in the token storage file for the
@@ -419,6 +432,10 @@ class AuthClient:
             if tokenStorageDir is None:
                 tokenStorageDir = platformdirs.site_config_dir('SpotifyWebApiPython', ensure_exists=True, appauthor=False)
 
+            # verify token storage filename was specified.
+            if tokenStorageFile is None:
+                tokenStorageFile = 'tokens.json'
+
             # if token providerId not set, then default to shared.
             if tokenProviderId is None:
                 tokenProviderId = 'Shared'
@@ -428,7 +445,7 @@ class AuthClient:
                 tokenProfileId = 'Shared'
 
             # formulate token storage path.
-            tokenStoragePath:str = os.path.join(tokenStorageDir, 'tokens.json')
+            tokenStoragePath:str = os.path.join(tokenStorageDir, tokenStorageFile)
             
             # formulate token storage key.
             tokenKey:str = f'{tokenProviderId}/{clientId}/{tokenProfileId}'

spotifywebapipython/spotifyclient.py

@@ -32,6 +32,7 @@ from .const import (
     SPOTIFY_DESKTOP_APP_CLIENT_ID,
     SPOTIFY_DEFAULT_MARKET,
     SPOTIFY_WEBAPI_URL_BASE,
+    SPOTIFYWEBAPIPYTHON_TOKEN_CACHE_FILE,
     TRACE_METHOD_RESULT,
     TRACE_METHOD_RESULT_TYPE,
     TRACE_METHOD_RESULT_TYPE_CACHED,
@@ -77,6 +78,7 @@ class SpotifyClient:
     def __init__(self, 
                  manager:PoolManager=None,
                  tokenStorageDir:str=None,
+                 tokenStorageFile:str=None,
                  tokenUpdater:Callable=None,
                  zeroconfClient:Zeroconf=None,
                  spotifyConnectUsername:str=None,
@@ -91,9 +93,12 @@ class SpotifyClient:
             manager (urllib3.PoolManager):
                 The manager for HTTP requests to the device.
             tokenStorageDir (str):
-                The directory path that will contain the `tokens.json` file.  
+                The directory path that will contain the authorization 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 authorization Token Cache file.  
+                Default is `SpotifyWebApiPython_tokens.json`.
             tokenUpdater (Callable):
                 A method to call when a token needs to be refreshed by an external provider.  
                 The defined method is called with no parameters, and should return a token dictionary.  
@@ -143,15 +148,22 @@ class SpotifyClient:
             if (spotifyConnectPassword is None) or (not isinstance(spotifyConnectPassword,str)):
                 raise SpotifyApiError(SAAppMessages.ARGUMENT_REQUIRED_ERROR % ("__init__", 'spotifyConnectPassword'), logsi=_logsi)
 
+        # verify token storage filename was specified.
+        if tokenStorageFile is None:
+            tokenStorageFile = SPOTIFYWEBAPIPYTHON_TOKEN_CACHE_FILE
+
+        # initialize storage.
         self._AuthToken:SpotifyAuthToken = None
         self._AuthClient:AuthClient = None
         self._ConfigurationCache:dict = {}
+        self._DefaultDeviceId:str = None
         self._Manager:PoolManager = manager
         self._SpotifyConnectUsername:str = spotifyConnectUsername
         self._SpotifyConnectPassword:str = spotifyConnectPassword
         self._SpotifyConnectLoginId:str = spotifyConnectLoginId
         self._SpotifyConnectDiscoveryTimeout:float = float(spotifyConnectDiscoveryTimeout)
         self._TokenStorageDir:str = tokenStorageDir
+        self._TokenStorageFile:str = tokenStorageFile
         self._TokenUpdater:Callable = tokenUpdater
         self._UserProfile:UserProfile = None
         self._ZeroconfClient = zeroconfClient
@@ -262,6 +274,28 @@ class SpotifyClient:
         return None
 
 
+    @property
+    def DefaultDeviceId(self):
+        """
+        Default device id (or name) to use for player transport methods that do not specify a device id and 
+        there is no active player detected (e.g. "Office", "5d4931f9d0684b625d702eaa24137b2c1d99539c", etc).  
+        
+        Set this value to null to use the Spotify player active device.
+        """
+        return self._DefaultDeviceId
+
+    @DefaultDeviceId.setter
+    def DefaultDeviceId(self, value:str):
+        """ 
+        Sets the DefaultDeviceId property value.
+        """
+        if (value is None) or (isinstance(value,str)):
+            if value.strip() == '':
+                self._DefaultDeviceId = None
+            else:
+                self._DefaultDeviceId = value
+
+
     @property
     def Manager(self) -> PoolManager:
         """ 
@@ -294,6 +328,14 @@ class SpotifyClient:
         return self._TokenStorageDir
     
 
+    @property
+    def TokenStorageFile(self) -> str:
+        """ 
+        The filename and extension of the authorization token cache file.  
+        """
+        return self._TokenStorageFile
+    
+
     @property
     def UserProfile(self) -> UserProfile:
         """ 
@@ -949,6 +991,10 @@ class SpotifyClient:
             apiMethodParms.AppendKeyValue("deviceId", deviceId)
             _logsi.LogMethodParmList(SILevel.Verbose, "Add item to playback queue", apiMethodParms)
                 
+            # if deviceId was not specified, then verify that there is an active player device.
+            if deviceId is None:
+                deviceId:str = self.VerifyPlayerActiveDeviceId()
+
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
@@ -5963,6 +6009,56 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
+    def VerifyPlayerActiveDeviceId(self) -> str:
+        """
+        Verifies that there is an active Spotify player device id, and returns the `DefaultDeviceId` 
+        value if there is not; otherwise, a null is returned to indicate that the currently active
+        Spotify player will be used.
+
+        Note that if there is no active player and there was no `DefaultDeviceId` defined, then 
+        subsequent calls to the Spotify Web API player endpoints will probably fail with a 
+        "No Active Device" exception.
+    
+        Returns:
+            A device id or null value.
+        """
+        apiMethodName:str = 'VerifyPlayerActiveDeviceId'
+        
+        try:
+            
+            # trace.
+            _logsi.EnterMethod(SILevel.Debug, apiMethodName)
+            _logsi.LogVerbose("Verifying active Spotify player device id")
+
+            # get current playback state.
+            playState:PlayerPlayState = self.GetPlayerPlaybackState()
+        
+            # is there an active device?
+            if (playState.Device.Id is None):
+            
+                # no - use the `DefaultDeviceId` property value so the Spotify Web API can 
+                # re-activate it prior to playing.
+                if self._DefaultDeviceId is not None:
+                    _logsi.LogVerbose("Active Spotify player device was not found - using DefaultDeviceId value: '%s'" % self._DefaultDeviceId)
+                    return self._DefaultDeviceId
+                
+            # otherwise return null, which will use the active Spotify player device for 
+            # subsequent calls to the Spotify Web API player endpoints.
+            return None
+    
+        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 GetPlayerDevice(self, 
                         deviceId:str, 
                         refresh:bool=True
@@ -6192,7 +6288,8 @@ class SpotifyClient:
                                                                 discoverResult.HostIpPort, 
                                                                 discoverResult.SpotifyConnectCPath,
                                                                 useSSL=False,
-                                                                tokenStorageDir=self.TokenStorageDir)
+                                                                tokenStorageDir=self.TokenStorageDir,
+                                                                tokenStorageFile=self.TokenStorageFile)
                     
                         # if a different user context has control of the device then we need to disconnect 
                         # the current user context before connecting a different user.
@@ -8252,7 +8349,8 @@ class SpotifyClient:
                                                             discoverResult.HostIpPort, 
                                                             discoverResult.SpotifyConnectCPath,
                                                             useSSL=False,
-                                                            tokenStorageDir=self.TokenStorageDir)
+                                                            tokenStorageDir=self.TokenStorageDir,
+                                                            tokenStorageFile=self.TokenStorageFile)
 
                     # if we did not refresh the device list, then query the device for real-time status; just in
                     # case the device was disconnected after the last cache refresh.  note that we only do this
@@ -8270,9 +8368,10 @@ class SpotifyClient:
                         # check if the Spotify Desktop Application Client oauth2 token is defined.
                         hasToken:bool = AuthClient.HasTokenForKey(
                             clientId=SPOTIFY_DESKTOP_APP_CLIENT_ID,
-                            tokenStorageDir=self.TokenStorageDir,
                             tokenProviderId='SpotifyWebApiAuthCodePkce',
                             tokenProfileId=self._SpotifyConnectLoginId,
+                            tokenStorageDir=self.TokenStorageDir,
+                            tokenStorageFile=self.TokenStorageFile,
                         )
                         
                         if not hasToken:
@@ -8501,7 +8600,8 @@ class SpotifyClient:
                                                     discoverResult.HostIpPort, 
                                                     discoverResult.SpotifyConnectCPath,
                                                     useSSL=False,
-                                                    tokenStorageDir=self.TokenStorageDir)
+                                                    tokenStorageDir=self.TokenStorageDir,
+                                                    tokenStorageFile=self.TokenStorageFile)
                             info = zconn.GetInformation()
                     
                         except Exception as ex:
@@ -8516,7 +8616,8 @@ class SpotifyClient:
                                                         discoverResult.HostIpPort, 
                                                         discoverResult.SpotifyConnectCPath,
                                                         useSSL=False,
-                                                        tokenStorageDir=self.TokenStorageDir)
+                                                        tokenStorageDir=self.TokenStorageDir,
+                                                        tokenStorageFile=self.TokenStorageFile)
                                 info = zconn.GetInformation()
                                 
                                 # update HostIpAddress in discovery result so it knows to use the alias
@@ -10071,6 +10172,10 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
+            # if deviceId was not specified, then verify that there is an active player device.
+            if deviceId is None:
+                deviceId:str = self.VerifyPlayerActiveDeviceId()
+
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
@@ -10593,6 +10698,10 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
+            # if deviceId was not specified, then verify that there is an active player device.
+            if deviceId is None:
+                deviceId:str = self.VerifyPlayerActiveDeviceId()
+
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
@@ -10690,6 +10799,10 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
+            # if deviceId was not specified, then verify that there is an active player device.
+            if deviceId is None:
+                deviceId:str = self.VerifyPlayerActiveDeviceId()
+
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
@@ -10782,6 +10895,10 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
+            # if deviceId was not specified, then verify that there is an active player device.
+            if deviceId is None:
+                deviceId:str = self.VerifyPlayerActiveDeviceId()
+
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
@@ -10871,6 +10988,10 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
+            # if deviceId was not specified, then verify that there is an active player device.
+            if deviceId is None:
+                deviceId:str = self.VerifyPlayerActiveDeviceId()
+
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
@@ -11082,6 +11203,10 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
+            # if deviceId was not specified, then verify that there is an active player device.
+            if deviceId is None:
+                deviceId:str = self.VerifyPlayerActiveDeviceId()
+
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
@@ -11181,6 +11306,10 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
+            # if deviceId was not specified, then verify that there is an active player device.
+            if deviceId is None:
+                deviceId:str = self.VerifyPlayerActiveDeviceId()
+
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
@@ -11279,6 +11408,10 @@ class SpotifyClient:
             # validations.
             delay = validateDelay(delay, 0.50, 10)
 
+            # if deviceId was not specified, then verify that there is an active player device.
+            if deviceId is None:
+                deviceId:str = self.VerifyPlayerActiveDeviceId()
+
             # check for device name; convert to an id if a name was supplied.
             deviceId = self.PlayerConvertDeviceNameToId(deviceId)
 
@@ -14438,6 +14571,7 @@ class SpotifyClient:
                 clientSecret=clientSecret,
                 oauth2Client=WebApplicationClient(client_id=clientId),  # required for grant_type = authorization_code
                 tokenStorageDir=self._TokenStorageDir,
+                tokenStorageFile=self._TokenStorageFile,
                 tokenProviderId='SpotifyWebApiAuthCode',
                 tokenProfileId=tokenProfileId,
                 tokenUpdater=self._TokenUpdater
@@ -14620,6 +14754,7 @@ class SpotifyClient:
                 clientSecret=None,  # client_secret not used for authorization code with pkce type
                 oauth2Client=WebApplicationClient(client_id=clientId),  # required for grant_type = authorization_code
                 tokenStorageDir=self._TokenStorageDir,
+                tokenStorageFile=self._TokenStorageFile,
                 tokenProviderId='SpotifyWebApiAuthCodePkce',
                 tokenProfileId=tokenProfileId,
                 tokenUpdater=self._TokenUpdater
@@ -14737,6 +14872,7 @@ class SpotifyClient:
                 clientSecret=clientSecret,
                 oauth2Client=BackendApplicationClient(client_id=clientId),  # required for grant_type = client_credentials
                 tokenStorageDir=self._TokenStorageDir,
+                tokenStorageFile=self._TokenStorageFile,
                 tokenProviderId='SpotifyWebApiClientCredentials',
                 tokenProfileId=tokenProfileId,
                 tokenUpdater=self._TokenUpdater
@@ -14835,6 +14971,7 @@ class SpotifyClient:
                 scope=token.get('scope'),
                 clientId=clientId,
                 tokenStorageDir=self._TokenStorageDir,
+                tokenStorageFile=self._TokenStorageFile,
                 tokenProviderId='SpotifyWebApiOAuth2Token',
                 tokenProfileId=tokenProfileId,
                 tokenUpdater=self._TokenUpdater
@@ -14894,6 +15031,7 @@ class SpotifyClient:
         msg:str = 'SpotifyClient:'
         msg = "%s\n ConfigurationCache key count=%d" % (msg, len(self._ConfigurationCache))
         msg = "%s\n TokenStorageDir='%s'" % (msg, self._TokenStorageDir)
+        msg = "%s\n TokenStorageFile='%s'" % (msg, self._TokenStorageFile)
         if self._UserProfile is not None:
             msg = "%s\n User DisplayName='%s' (%s)" % (msg, self._UserProfile.DisplayName, self._UserProfile.Id)
         return msg

spotifywebapipython/zeroconfapi/zeroconfconnect.py

@@ -21,6 +21,7 @@ from ..const import (
     SPOTIFY_API_AUTHORIZE_URL,
     SPOTIFY_API_TOKEN_URL,
     SPOTIFY_DESKTOP_APP_CLIENT_ID,
+    SPOTIFYWEBAPIPYTHON_TOKEN_CACHE_FILE,
     TRACE_METHOD_RESULT,
     TRACE_MSG_DELAY_DEVICE,
 )
@@ -61,6 +62,7 @@ class ZeroconfConnect:
                  version:str=None,
                  useSSL:bool=False,
                  tokenStorageDir:str=None,
+                 tokenStorageFile:str=None,
                  tokenAuthInBrowser:bool=False,
                  ) -> None:
         """
@@ -83,10 +85,13 @@ class ZeroconfConnect:
                 otherwise, False to utilize HTTP.  
                 Default is False (HTTP).
             tokenStorageDir (str):
-                The directory path that will contain the `tokens.json` cache file.  
+                The directory path that will contain the Token Cache file.  
                 This is used for Spotify Connect devices that utilize the `authorization_code` token type.
                 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 `SpotifyWebApiPython_tokens.json`.
             tokenAuthInBrowser (bool):
                 True to allow authorization access token to be authorized if necessary via an
                 interactive browser; otherwise, False.  
@@ -103,11 +108,16 @@ class ZeroconfConnect:
         if (version is None) or (not isinstance(version,str)):
             version = ZeroconfConnect.SPOTIFY_CONNECT_CLIENT_VERSION_DEFAULT
             
+        # verify token storage filename was specified.
+        if tokenStorageFile is None:
+            tokenStorageFile = SPOTIFYWEBAPIPYTHON_TOKEN_CACHE_FILE
+
         # initialize storage.
         self._CPath:str = cpath
         self._HostIpPort:int = hostIpPort
         self._HostIpAddress:str = hostIpAddress
         self._TokenStorageDir:str = tokenStorageDir
+        self._TokenStorageFile:str = tokenStorageFile
         self._TokenAuthInBrowser:str = tokenAuthInBrowser
         self._UseSSL:bool = useSSL
         self._Version:str = version
@@ -159,6 +169,14 @@ class ZeroconfConnect:
         return self._TokenStorageDir
     
 
+    @property
+    def TokenStorageFile(self) -> str:
+        """ 
+        The filename and extension of the authorization token cache file.  
+        """
+        return self._TokenStorageFile
+    
+
     @property
     def Uri(self) -> str:
         """ 
@@ -677,6 +695,7 @@ class ZeroconfConnect:
                 scope=SPOTIFY_SCOPES,
                 clientId=SPOTIFY_DESKTOP_APP_CLIENT_ID,
                 tokenStorageDir=self.TokenStorageDir,
+                tokenStorageFile=self.TokenStorageFile,
                 tokenProviderId='SpotifyWebApiAuthCodePkce',
                 tokenProfileId=loginId,
             )