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

spotifywebapipython/oauthcli/authclient.py

@@ -35,13 +35,12 @@ class AuthClient:
     Enter the authorization code: 
     """
 
-    _DEFAULT_AUTH_PROMPT_MESSAGE = ("Please visit this URL to authorize this application: {url}")
+    _DEFAULT_AUTH_PROMPT_MESSAGE = "Please visit this URL to authorize this application: {url}"
     """
     Please visit this URL to authorize this application: {url}
     """
 
-    _DEFAULT_WEB_SUCCESS_MESSAGE = ("The authentication flow has completed; you may close this window (or tab)."
-    )
+    _DEFAULT_WEB_SUCCESS_MESSAGE = "The authentication flow has completed; you may close this window (or tab)." #</br>Auth Token:</br>%s"
     """
     The authentication flow has completed; you may close this window (or tab).
     """
@@ -58,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.
@@ -94,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`
+                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.  
@@ -111,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'
@@ -129,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
@@ -381,9 +389,101 @@ class AuthClient:
         raise ConnectionError('Could not find an open port on localhost address "%s", in the range of "%s" to "%s"' % (localhostIp, portStart, portStop))
         
 
+    @staticmethod
+    def HasTokenForKey(
+        clientId:str=None,
+        tokenProviderId:str=None,
+        tokenProfileId:str=None,
+        tokenStorageDir:str=None,
+        tokenStorageFile:str=None,
+        ) -> bool:
+        """
+        Checks if a token exists in the token storage file for the ProviderId / ClientId key.
+        
+        Args:
+            clientId (str):
+                The unique identifier of the application.
+            tokenProviderId (str):
+                Provider identifier used when storing the token to disk.
+            tokenProfileId (str):
+                Profile identifier used when storing the token to disk.  
+            tokenStorageDir (str):
+                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
+            specified ProviderId and ClientId key; otherwise, null.
+        """
+        apiMethodName:str = 'HasTokenForKey'
+        apiMethodParms:SIMethodParmListContext = None
+        
+        try:
+
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Checking if token exists in token storage file", apiMethodParms)
+            
+            # verify token storage directory exists.
+            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'
+
+            # if token profileId not set, then default to shared.
+            if tokenProfileId is None:
+                tokenProfileId = 'Shared'
+
+            # formulate token storage path.
+            tokenStoragePath:str = os.path.join(tokenStorageDir, tokenStorageFile)
+            
+            # formulate token storage key.
+            tokenKey:str = f'{tokenProviderId}/{clientId}/{tokenProfileId}'
+            _logsi.LogVerbose('Token storage key: "%s"' % (tokenKey))           
+            _logsi.LogVerbose('Token storage file path: "%s"' % (tokenStoragePath))
+            
+            # does the token storage file exist?
+            if os.path.exists(tokenStoragePath):
+
+                # open the token storage file, and load it's contents.
+                _logsi.LogVerbose('Opening token storage file')
+                with open(tokenStoragePath, 'r') as f:
+                    
+                    tokens = json.load(f)
+
+                    # return if token key exists or not.
+                    if tokenKey in tokens:
+                        _logsi.LogDictionary(SILevel.Verbose, 'Token was found in token storage file for provider: "%s"' % (tokenKey), tokens[tokenKey], prettyPrint=True)
+                        return True
+        
+            # indicate token was not found.
+            return False
+        
+        except Exception as ex:
+            
+            # trace.
+            _logsi.LogException('Could not verify OAuth2 Token from token storage file: "%s"' % (tokenStoragePath), ex)
+            raise
+
+        finally:
+        
+            # trace.
+            _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
     def _LoadToken(self) -> dict:
         """
-        Loads a token from the token storage file for the ProviderId \ ClientId key.
+        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
@@ -436,7 +536,7 @@ class AuthClient:
 
     def _SaveToken(self, token:dict=None) -> None:
         """
-        Saves a token to the token storage file (e.g. disk) for the ProviderId \ ClientId key.
+        Saves a token to the token storage file (e.g. disk) for the ProviderId / ClientId key.
         
         Args:
             token (dict):
@@ -475,14 +575,14 @@ class AuthClient:
                     
             if token is None:
                 
-                # if token not specified, then remove the existing token for the providerId \ clientId.
+                # if token not specified, then remove the existing token for the providerId / clientId.
                 _logsi.LogVerbose('Removing token from token storage file')
                 if tokenKey in tokens:
                     del tokens[tokenKey]
                     
             else:
                 
-                # store the token for the providerId \ clientId.
+                # store the token for the providerId / clientId.
                 _logsi.LogVerbose('Storing token in token storage file')
                 tokens[tokenKey] = token
 
@@ -776,7 +876,7 @@ class AuthClient:
         authorization_prompt_message: Optional[str] = _DEFAULT_AUTH_PROMPT_MESSAGE,
         success_message: str = _DEFAULT_WEB_SUCCESS_MESSAGE,
         open_browser: bool = True,
-        redirect_uri_trailing_slash: bool = True,
+        redirect_uri_path: str = '/',
         timeout_seconds: Optional[int] = 120,
         token_audience: Optional[str] = None,
         force: bool = False,
@@ -819,10 +919,10 @@ class AuthClient:
             open_browser (bool):  
                 True to open the authorization URL in the user's browser; otherwise, False
                 to not open a browser.
-            redirect_uri_trailing_slash (bool):  
-                True to add trailing slash when constructing the redirect_uri; otherwise,
-                False to not add a trailing slash.  
-                Default value is True.
+            redirect_uri_path (str):  
+                Path value to add when constructing the redirect_uri; otherwise,
+                None to not add a path value.  
+                Default value is '/'.
             timeout_seconds (int):  
                 If set, an error will be raised after the timeout value if the user did not
                 respond to the authorization request.  The value is in seconds.  
@@ -860,7 +960,7 @@ class AuthClient:
             apiMethodParms.AppendKeyValue("authorization_prompt_message", authorization_prompt_message)
             apiMethodParms.AppendKeyValue("success_message", success_message)
             apiMethodParms.AppendKeyValue("open_browser", open_browser)
-            apiMethodParms.AppendKeyValue("redirect_uri_trailing_slash", redirect_uri_trailing_slash)
+            apiMethodParms.AppendKeyValue("redirect_uri_path", redirect_uri_path)
             apiMethodParms.AppendKeyValue("timeout_seconds", timeout_seconds)
             apiMethodParms.AppendKeyValue("token_audience", token_audience)
             apiMethodParms.AppendKeyValue("force", force)
@@ -894,8 +994,8 @@ class AuthClient:
             # construct the redirect uri, which is where the user is redirected after 
             # authentication success or failure.
             redirectUri:str = 'http://{}:{}'.format(host, wsgiServer.server_port)
-            if redirect_uri_trailing_slash:
-                redirectUri = redirectUri + '/'
+            if redirect_uri_path is not None:
+                redirectUri = redirectUri + redirect_uri_path
             self._Session.redirect_uri = redirectUri
         
             # construct the authorization url and state values.

spotifywebapipython/saappmessages.py

@@ -38,4 +38,24 @@ class SAAppMessages:
     MSG_SPOTIFY_WEB_API_AUTH_ERROR:str = "SAM1002E - Spotify Web API returned an authorization error status while processing the \"{methodname}\" method.\nHTTP Status: {httpstatus} - {httpreason}\nError: {error}\nError Description: \"{errordescription}\""
     """
     SAM1002E - Spotify Web API returned an authorization error status while processing the \"{methodname}\" method.\nHTTP Status: {httpstatus} - {httpreason}\nError: {error}\nError Description: \"{errordescription}\"
-    """
+    """
+    
+    MSG_SPOTIFY_ZEROCONF_API_ERROR:str = "SAM1003E - Spotify ZeroConf API returned an error status while processing the \"{methodname}\" method.\nStatus: {status} - {httpreason}\nMessage: \"{message}\""
+    """
+    SAM1001E - Spotify ZeroConf API returned an error status while processing the \"{methodname}\" method.\nStatus: {status} - {httpreason}\nMessage: \"{message}\"
+    """
+    
+    MSG_SPOTIFY_ACCOUNT_REQUIRED_FOR_NOWPLAYING:str = "SAM1004E - A Spotify Free or Premium level membership is required to get currently playing item information."
+    """
+    SAM1004E - A Spotify Premium level membership is required to get currently playing item information.
+    """
+    
+    MSG_SPOTIFY_ACTIVATE_CREDENTIAL_REQUIRED:str = "SAM1005E - The \"%s\" configuration option was not supplied, which is required in order to reactivate a Spotify Connect device."
+    """
+    SAM1005E - The \"%s\" configuration option was not supplied, which is required in order to reactivate a Spotify Connect device.
+    """
+       
+    MSG_SPOTIFY_DEPRECATED_ENDPOINT:str = "SAM1010E - The \"%s\" endpoint has been deprecated by Spotify without prior notice as of November 27th 2024, and the supporting functionality is no longer available."
+    """
+    SAM1010E - The \"%s\" endpoint has been deprecated by Spotify without prior notice as of November 27th 2024, and the supporting functionality is no longer available.
+    """

spotifywebapipython/sautils.py

@@ -32,6 +32,28 @@ def GetUnixTimestampMSFromUtcNow(days:int=0,
     return dtUtcUnixTSMS
 
 
+def passwordMaskString(inputObj:str) -> str:
+    """
+    Checks a string for a password value and masks the value so that the password is not displayed 
+    in a trace file.
+
+    Args:
+        inputObj (str):
+            String object to check.
+    
+    Returns:
+        A copy of the `inputObj` value with password masked.
+    """
+    # if input is null then don't bother.
+    if (inputObj is None):
+        return inputObj
+    
+    # create a new value.
+    result:str = ''.ljust(len(inputObj), '*')
+                
+    return result
+
+
 def static_init(cls):
     """
     Define the decorator used to call an initializer for a class with all static methods.
@@ -56,6 +78,66 @@ def export(fn):
     return fn
     
 
+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 _xmlGetInnerText(elmNode, default:str=None) -> str:
+    """
+    Finds the specified xml node inner text from the root Element object and returns its value
+    as a string.  The default argument is returned if the xml node name is not found.
+    
+    Args:
+        root (xml.etree.ElementTree.Element)
+            The Element object to search.
+        default (str):
+            A default value to assign if the xml node does not contain innerText.
+            
+    Returns:
+        The string value if innerText was found; 
+        otherwise, the default value.
+    """
+    if elmNode is None:
+        return default
+    
+    # get text of all child nodes.
+    innertext:str = (elmNode.text or '') + ''.join(_xmlGetInnerText(e) for e in elmNode) + (elmNode.tail or '')
+    
+    # did we find anything?  if not, then return default.
+    if innertext is None:
+        return default
+    
+    # return found inner text.
+    return innertext
+
+
 class Event:
     """
     C# like event processing in Python3.
@@ -97,9 +179,14 @@ class Event:
     def fire(self, *args, **kargs):
         """
         Calls (i.e. "fires") all method handlers defined for this event.
+
+        Exceptions will be ignored for individual handlers.
         """
         for handler in self.handlers:
-            handler(*args, **kargs)
+            try:
+                handler(*args, **kargs)
+            except:
+                pass
 
     def getHandlerCount(self):
         """

spotifywebapipython/spotifyapimessage.py

@@ -42,6 +42,7 @@ class SpotifyApiMessage:
         self._RequestHeaders:Mapping[str, str] = requestHeaders
         self._RequestJson:dict = None
         self._ResponseData = {}
+        self._IgnoreResponseErrors:bool = False
         self._IsRequestDataEncoded:bool = False
         self._Uri:str = uri
         self._UrlParameters:dict = urlParameters
@@ -99,6 +100,22 @@ class SpotifyApiMessage:
         return self._RequestData is not None
 
 
+    @property
+    def IgnoreResponseErrors(self) -> bool:
+        """ 
+        Indicates if request response errors are ignored (True) or not (False, default).  
+        If not, an exception will be thrown with the error details.
+        """
+        return self._IgnoreResponseErrors
+
+    @IgnoreResponseErrors.setter
+    def IgnoreResponseErrors(self, value:bool):
+        """ 
+        Sets the IgnoreResponseErrors property value.
+        """
+        self._IgnoreResponseErrors = value
+
+
     @property
     def IsRequestDataEncoded(self) -> bool:
         """ 
@@ -109,7 +126,7 @@ class SpotifyApiMessage:
     @IsRequestDataEncoded.setter
     def IsRequestDataEncoded(self, value:bool):
         """ 
-        Sets the MethodName property value.
+        Sets the IsRequestDataEncoded property value.
         """
         self._IsRequestDataEncoded = value
 

spotifywebapipython/spotifyauthtoken.py

@@ -1,5 +1,6 @@
 # external package imports.
 from datetime import datetime, timedelta
+from pprint import pformat
 import time
 
 # our package imports.
@@ -221,6 +222,31 @@ class SpotifyAuthToken:
         return self._TokenType
     
 
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'access_token': self._AccessToken,
+            'expires_at': self._ExpiresAt,
+            'expires_in': self._ExpiresIn,
+            'refresh_token': self._RefreshToken,
+            'scope': self.Scopes,
+            'token_type': self._TokenType,
+        }
+        return result
+        
+
+    def ToDictionaryString(self) -> dict:
+        """
+        Returns a dictionary string representation of the class.
+        """
+        oDict:dict = self.ToDictionary()
+        result:str = pformat(oDict,indent=2,width=132,sort_dicts=False)
+        return result
+        
+
     def ToString(self) -> str:
         """
         Returns a displayable string representation of the class.