spotifywebapiPython 1.0.242__py3-none-any.whl

spotifywebapipython/saappmessages.py

@@ -0,0 +1,86 @@
+# external package imports.
+# none
+
+# our package imports.
+from .sautils import export
+
+
+@export
+class SAAppMessages:
+    """
+    A strongly-typed resource class, for looking up localized strings, etc.
+    
+    Threadsafety:
+        This class is fully thread-safe.
+    """
+
+    UNHANDLED_EXCEPTION:str = "SAM0001E - An unhandled exception occured while processing method \"{0}\".\n{1}"
+    """
+    SAM0001E - An unhandled exception occured while processing method \"{0}\".
+    {1}
+    """
+
+    ARGUMENT_REQUIRED_ERROR:str = "SAM0002E - The \"%s\" method \"%s\" argument is required, and cannot be null or None."
+    """
+    SAM0002E - The \"%s\" method \"%s\" argument is required, and cannot be null or None.
+    """
+
+    ARGUMENT_TYPE_ERROR:str = "SAM0003E - The \"%s\" method \"%s\" argument must be of type \"%s\"; the \"%s\" type is not supported for this argument."
+    """
+    SAM0003E - The \"%s\" method \"%s\" argument must be of type \"%s\"; the \"%s\" type is not supported for this argument.
+    """
+
+    MSG_SPOTIFY_WEB_API_ERROR:str = "SAM1001E - Spotify Web API returned an error status while processing the \"{methodname}\" method.\nStatus: {status} - {httpreason}\nMessage: \"{message}\""
+    """
+    SAM1001E - Spotify Web API returned an error status while processing the \"{methodname}\" method.\nStatus: {status} - {httpreason}\nMessage: \"{message}\"
+    """
+    
+    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_WEB_API_RETRY_REQUEST_DELAY:str = "Delaying for %s seconds before retry to allow Spotify Gateway to become available"
+    """
+    Delaying for %s seconds before retry to allow Spotify Gateway to become available
+    """
+
+    MSG_SPOTIFY_WEB_API_RETRY_RESPONSE_STATUS:str = "Spotify Web API request returned with a %s status (%s); request will be retried"
+    """
+    Spotify Web API request returned with a %s status (%s); request will be retried
+    """
+
+    MSG_SPOTIFY_WEB_API_RETRY_TIMEOUT:str = "Timed out waiting for Spotify Gateway to become available; gave up after %f seconds from initial request."
+    """
+    Timed out waiting for Spotify Gateway to become available; gave up after %f seconds from initial request.
+    """
+
+    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.
+    """
+
+    MSG_SPOTIFY_WEB_PLAYER_TOKEN_INUSE:str = "Spotify Web Player authorization access token will be used for accessing Spotify Web API endpoint."
+    """
+    Spotify Web Player authorization access token will be used for accessing Spotify Web API endpoint.
+    """
+
+    MSG_SPOTIFY_WEB_PLAYER_TOKEN_REFRESHED:str = "Converting Spotify Web Player cookie credentials to an access token for loginId \"%s\"."
+    """
+    Converting Spotify Web Player cookie credentials to an access token for loginId \"%s\".
+    """

spotifywebapipython/sautils.py

@@ -0,0 +1,285 @@
+# external package imports.
+from datetime import datetime, timedelta, timezone
+import sys
+
+"""
+Utility module of helper functions.
+"""
+
+SONOS_NOT_IMPLEMENTED:str = 'NOT_IMPLEMENTED'
+
+
+def GetUnixTimestampMSFromUtcNow(days:int=0,
+                                 hours:int=0,
+                                 minutes:int=0,
+                                 seconds:int=0,
+                                 ) -> int:
+    """
+    Returns a Unix millisecond timestamp value from the current utc datetime for the
+    difference specified by input arguments.
+    
+    """
+    # get current utc datetime (in a timezone aware datetime instance).
+    dtUtc:datetime = datetime.now(timezone.utc)
+    
+    # get offset timedelta.
+    dtUtcOffset = (dtUtc + timedelta(days=days, hours=hours, minutes=minutes, seconds=seconds))
+    
+    # convert to unix timestamp (# of seconds since epoch date of 1970/01/01).
+    dtUtcUnixTS:float = dtUtcOffset.timestamp()
+
+    # convert to milliseconds.
+    dtUtcUnixTSMS:int = int(dtUtcUnixTS * 1000)
+    
+    # return unix milliseconds timestamp value.
+    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 mediaPositionHMS_fromSeconds(
+    position:int, 
+    ) -> float:
+    """
+    Converts an integer media position value from seconds to a string value in H:MM:SS format.
+        
+    Args:
+        position (int):
+            The position value (as specified in seconds) to convert.
+    """
+    result:str = '0:00:00'
+    
+    # validations.
+    if (isinstance(position, float)):
+        position = int(position)
+    if (position is None) or (position < 1):
+        return result            
+
+    # convert seconds to H:MM:SS string format.
+    nSeconds = int(position)
+    mm, ss = divmod(nSeconds, 60)            # get minutes and seconds first
+    hh, mm= divmod(mm, 60)                   # get hours next
+    result = "%d:%02d:%02d" % (hh, mm, ss)   # format to hh:mm:ss
+    
+    # return result to caller.
+    return result
+
+
+def mediaPositionHMS_toSeconds(
+    timestr:str
+    ) -> int:
+    """
+    Convert an "HH:MM:SS" string value to total number of seconds.
+        
+    Args:
+        timestr (int):
+            The position value (as specified in H:MM:SS) to convert.
+    """
+    if (timestr is None) or (timestr == '') or (timestr == SONOS_NOT_IMPLEMENTED): 
+        return 0
+        
+    seconds= 0
+    for part in timestr.split(':'):
+        seconds= seconds*60 + int(part, 10)
+    return seconds
+
+
+def static_init(cls):
+    """
+    Define the decorator used to call an initializer for a class with all static methods.
+    This allows static variables to be initialized one time for the class.
+    """
+    if getattr(cls, "static_init", None):
+        cls.static_init()
+    return cls
+
+
+def export(fn):
+    """
+    Define the decorator used to modify a module's "__all__" variable.
+    This avoids us having to manually modify a module's "__all__" variable when adding new classes.
+    """
+    mod = sys.modules[fn.__module__]
+    if hasattr(mod, '__all__'):
+        mod.__all__.append(fn.__name__)
+    else:
+        mod.__all__ = [fn.__name__]
+
+    return fn
+    
+
+def validateDelay(
+        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.
+
+    <details>
+        <summary>View Sample Code</summary>
+    ```python
+    # Define the class that will be raising events:
+    class MyFileWatcher:
+        def __init__(self):
+            self.fileChanged = Event()      # define event
+
+        def watchFiles(self):
+            source_path = "foo"
+            self.fileChanged(source_path)   # fire event
+
+    def log_file_change(source_path):       # event handler 1
+        print "%r changed." % (source_path,)
+
+    def log_file_change2(source_path):      # event handler 2
+        print "%r changed!" % (source_path,)
+
+    # Define the code that will be handling raised events.
+    watcher              = MyFileWatcher()
+    watcher.fileChanged += log_file_change2
+    watcher.fileChanged += log_file_change
+    watcher.fileChanged -= log_file_change2
+    watcher.watchFiles()
+    ```
+    </details>
+    """
+
+    def __init__(self, *args) -> None:
+        """
+        Initializes a new instance of the class.
+        """
+        self.handlers = set()
+
+    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:
+            try:
+                handler(*args, **kargs)
+            except:
+                pass
+
+    def getHandlerCount(self):
+        """
+        Returns the number of method handlers defined for this event.
+        """
+        return len(self.handlers)
+
+    def handle(self, handler):
+        """
+        Adds a method handler for this event.
+        """
+        self.handlers.add(handler)
+        return self
+
+    def unhandle(self, handler):
+        """
+        Removes the specified method handler for this event.
+
+        Args:
+            handler (object):
+                The method handler to remove.
+
+        This method will not throw an exception.
+        """
+        try:
+            self.handlers.remove(handler)
+        except:
+            pass   # ignore exceptions.
+        return self
+
+    def unhandle_all(self):
+        """
+        Removes all method handlers (if any) for this event.
+
+        This method will not throw an exception.
+        """
+        try:
+            self.handlers.clear()
+        except:
+            pass   # ignore exceptions.
+        return self
+
+    # alias method definitions.
+    __iadd__ = handle
+    __isub__ = unhandle
+    __call__ = fire
+    __len__  = getHandlerCount

spotifywebapipython/spotifyapierror.py

@@ -0,0 +1,66 @@
+# external package imports.
+from smartinspectpython.sisession import SISession
+
+# our package imports.
+from .sautils import export
+
+
+@export
+class SpotifyApiError(Exception):
+    """
+    Exception thrown when a SpotifyApi error occurs.
+    """
+    
+    def __init__(self, message:str, ex:Exception=None, logsi:SISession=None) -> None:
+        """
+        Initializes a new instance of the class.
+
+        Args:
+            message (str):
+                A short description of the cause of the error.
+            ex (Exception):
+                Inner exception that caused the current exception.  
+                Default is None.
+            logsi (SISession):
+                Trace session object that this exception will be logged to, or null to bypass trace logging.  
+                Default is None.
+        """
+        
+        # initialize base class.
+        super().__init__(message)
+        
+        # initialize class instance.
+        self._Message:str = message
+
+        # trace.
+        if logsi is not None:
+            if (isinstance(logsi, SISession)):
+                if ex is None:
+                    logsi.LogError(self.ToString())
+                else:
+                    logsi.LogException(message, ex, logToSystemLogger=False)
+
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Message(self) -> str:
+        """ 
+        A description of the cause of the error.
+        """
+        return self._Message
+
+
+    def ToString(self) -> str:
+        """
+        Returns a displayable string representation of the class.
+        """
+        msg:str = 'SpotifyApiError:'
+        if self._Message is not None: msg = '%s %s' % (msg, str(self._Message))
+        return msg 

spotifywebapipython/spotifyapimessage.py

@@ -0,0 +1,269 @@
+# external package imports.
+from typing import Mapping
+
+# our package imports.
+from .sautils import export
+
+@export
+class SpotifyApiMessage:
+    """
+    A class representing an exchange object between a client and the Spotify Web API.
+    """
+    
+    def __init__(self, methodName:str, uri:str, urlParameters:dict=None, requestData:dict=None, requestHeaders:dict=None) -> None:
+        """
+        Initializes a new instance of the class.
+        
+        Args:
+            methodName (str):
+                Name of the client method that executed the request.
+            uri (str):
+                Target uri which should be queried.
+            urlParameters (dict):
+                Parameter values to be placed into the http request url, if the specified
+                uri service requires it; otherwise, None.
+            requestData (dict):
+                Request data that is to be placed into the http request body, if the specified
+                uri service requires it; otherwise, None.
+            requestHeaders (dict):
+                Request header that is to be placed into the http request headers, if the specified
+                uri service requires it; otherwise, None.
+        """
+        # validation.
+        if requestData is None:
+            requestData = {}
+        if requestHeaders is None:
+            requestHeaders = {}
+        if urlParameters is None:
+            urlParameters = {}
+
+        self._MethodName:str = methodName            
+        self._RequestData:dict = requestData
+        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
+
+      
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def HasRequestData(self) -> bool:
+        """ 
+        Returns True if request data is present, and should be supplied as part of the 
+        http request body; otherwise, False.
+        """
+        return self._RequestData is not None and len(self._RequestData) != 0
+
+
+    @property
+    def HasRequestHeaders(self) -> bool:
+        """ 
+        Returns True if request headers are present, and should be supplied as part of the 
+        http request headers; otherwise, False.
+        """
+        return self._RequestHeaders is not None and len(self._RequestHeaders) != 0
+
+
+    @property
+    def HasRequestJson(self) -> bool:
+        """ 
+        Returns True if request json is present, and should be supplied as part of the 
+        http request body; otherwise, False.
+        """
+        return self._RequestJson is not None and len(self._RequestJson) != 0
+
+
+    @property
+    def HasUrlParameters(self) -> bool:
+        """ 
+        Returns True if url parameters are present, and should be supplied as part of the 
+        http request url; otherwise, False.
+        """
+        return self._UrlParameters is not None and len(self._UrlParameters) != 0
+
+
+    @property
+    def HasResponseData(self) -> bool:
+        """ 
+        Returns True if data was returned with the response; otherwise, False. 
+        """
+        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:
+        """ 
+        Indicates if the `RequestData` property is already encoded (True) or not (False).
+        """
+        return self._IsRequestDataEncoded
+
+    @IsRequestDataEncoded.setter
+    def IsRequestDataEncoded(self, value:bool):
+        """ 
+        Sets the IsRequestDataEncoded property value.
+        """
+        self._IsRequestDataEncoded = value
+
+
+    @property
+    def IsResponseEmpty(self) -> bool:
+        """ 
+        Returns True if the response contains no data (e.g. a pass / fail response)
+        and is not null; otherwise, False.
+        """
+        return self._ResponseData is not None and len(self._ResponseData) == 0
+
+
+    @property
+    def IsSimpleResponse(self) -> bool:
+        """ 
+        Returns True if the response contains no data (e.g. a pass / fail response); 
+        otherwise, False if the response requires further processing.
+        """
+        return self._ResponseData is not None and len(self._ResponseData) != 0
+
+
+    @property
+    def MethodName(self) -> str:
+        """ 
+        The client method that executed the request.
+        
+        Example: `GetArtist`.
+        """
+        return self._MethodName
+
+    @MethodName.setter
+    def MethodName(self, value:str):
+        """ 
+        Sets the MethodName property value.
+        """
+        if value is not None:
+            if isinstance(value, str):
+                self._MethodName = value
+
+
+    @property
+    def RequestData(self) -> dict: 
+        """ 
+        Request data that is to be placed into the http request body, if the specified
+        uri service requires it.
+        """
+        return self._RequestData
+    
+    @RequestData.setter
+    def RequestData(self, value:dict):
+        """ 
+        Sets the RequestData property value.
+        """
+        if value is not None:
+            self._RequestData = value
+        
+
+    @property
+    def RequestHeaders(self) -> Mapping[str, str]: 
+        """ 
+        Request header data that is to be sent with the http request body, if the specified
+        uri service requires it.
+        """
+        return self._RequestHeaders
+
+
+    @property
+    def RequestJson(self) -> dict: 
+        """ 
+        Request data that is to be placed into the http request body, if the specified
+        uri service requires it.
+        """
+        return self._RequestJson
+    
+    @RequestJson.setter
+    def RequestJson(self, value:dict):
+        """ 
+        Sets the RequestJson property value.
+        """
+        if value is not None:
+            if isinstance(value, dict):
+                self._RequestJson = value
+        
+
+    @property
+    def ResponseData(self) -> dict:
+        """ 
+        Response data returned from the server, if the specified uri returned
+        a response that contains data.
+        """
+        return self._ResponseData
+
+    @ResponseData.setter
+    def ResponseData(self, value:dict):
+        """ 
+        Sets the ResponseData property value.
+        """
+        if value is not None:
+            # some Spotify responses can contain non-dictionary data!
+            #if isinstance(value, dict):
+            self._ResponseData = value
+        
+
+    @property
+    def Uri(self) -> str: 
+        """ 
+        Target uri which should be queried.
+        """
+        return self._Uri
+
+
+    @property
+    def UrlParameters(self) -> dict: 
+        """ 
+        Parameter values to be placed into the http request url, if the specified
+        uri service requires it.
+        """
+        return self._UrlParameters
+
+    @UrlParameters.setter
+    def UrlParameters(self, value:dict):
+        """ 
+        Sets the UrlParameters property value.
+        """
+        if value is not None:
+            if isinstance(value, dict):
+                self._UrlParameters = value
+        
+
+    def ToString(self) -> str:
+        """
+        Returns a displayable string representation of the class.
+        """
+        msg:str = 'SpotifyApiMessage:'
+        msg = '%s uri="%s"' % (msg, str(self._Uri))
+        if self.HasRequestData: msg = '%s RequestData="%s"' % (msg, self._RequestData)
+        if self.HasRequestJson: msg = '%s RequestJson="%s"' % (msg, self._RequestJson)
+        if self.IsSimpleResponse: msg = '%s response="%s"' % (msg, str(self.IsSimpleResponse).lower())
+        return msg