spotifywebapiPython 1.0.73__py3-none-any.whl → 1.0.74__py3-none-any.whl

spotifywebapipython/zeroconfapi/credentials.py

@@ -1,9 +1,17 @@
+# our package imports.
+from .authenticationtypes import AuthenticationTypes
+
 class Credentials:
     """
     Credentials used by the Spotify SpConnectionLoginBlob method.
     """
 
-    def __init__(self, username: str, password: str):
+    def __init__(
+            self, 
+            username:str, 
+            password:str,
+            authenticationType:AuthenticationTypes=AuthenticationTypes.USER_PASS,
+            ):
         """
         Initializes a new instance of the class.
         
@@ -12,7 +20,15 @@ class Credentials:
                 Spotify Connect user name to login with.  
             password (str):
                 Spotify Connect user password to login with.  
+            authenticationType (AuthenticationTypes):
+                Authentication type.
         """
+        # validations.
+        if (authenticationType is None) or (not isinstance(authenticationType, AuthenticationTypes)):
+            authenticationType = AuthenticationTypes.USER_PASS
+        
+        # initialize storage.
         self.username: bytes = bytes(username, 'ascii')
         self.password: bytes = bytes(password, 'ascii')
-        self.auth_type: int = 0x00
+        self.auth_type: AuthenticationTypes = authenticationType
+        

spotifywebapipython/zeroconfapi/zeroconfconnect.py

@@ -6,7 +6,7 @@ import time
 
 # our package imports.
 from .blobbuilder import BlobBuilder
-from .credentials import Credentials
+from .credentials import Credentials, AuthenticationTypes
 from .helpers import int_to_b64str
 from .spotifyzeroconfapierror import SpotifyZeroconfApiError
 from .zeroconfresponse import ZeroconfResponse
@@ -42,6 +42,12 @@ class ZeroconfConnect:
     GitHub repository.
     """
     
+    SPOTIFY_CONNECT_CLIENT_VERSION_DEFAULT:str = '2.7.1'
+    """
+    Spotify Connect default version string ('2.7.1').
+    """
+    
+
     def __init__(self, 
                  hostIpAddress:str,
                  hostIpPort:int,
@@ -72,6 +78,8 @@ class ZeroconfConnect:
         # validations.
         if (useSSL is None) or (not isinstance(useSSL,bool)):
             useSSL = False
+        if (version is None) or (not isinstance(version,str)):
+            version = ZeroconfConnect.SPOTIFY_CONNECT_CLIENT_VERSION_DEFAULT
             
         # initialize storage.
         self._CPath:str = cpath
@@ -208,10 +216,15 @@ class ZeroconfConnect:
                 responseUTF8 = response.content.decode('utf-8')
                 _logsi.LogText(SILevel.Error, "ZeroconfConnect http response [%s-%s]: '%s' (utf-8)" % (response.status_code, response.reason, endpoint), 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 SpotifyZeroconfApiError(response.status_code, responseUTF8, methodName, response.reason, _logsi)
-            
+            # at this point we don't know what Spotify Web Api returned!
+            # it's been found that some devices (Sonos, etc) do not return a proper JSON response.
+            # raise a new exception with the non-JSON response data if the http status is not 200 (OK).
+            if (response.status_code != 200):
+                raise SpotifyZeroconfApiError(response.status_code, responseUTF8, methodName, response.reason, _logsi)
+
+            # trace.
+            _logsi.LogVerbose("Spotify Connect Device (ip=%s) returned an invalid JSON response, but the http status code was 200 so we will ignore it" % (self._HostIpAddress))
+
         # at this point we know that the response contains JSON data, as
         # we would have raised an exception before this if we could not
         # convert the response to JSON!
@@ -335,14 +348,6 @@ class ZeroconfConnect:
             # get the current device id from the device via Spotify ZeroConf API `getInfo` endpoint.
             info:ZeroconfGetInfo = self.GetInformation()
 
-            # are we including origin device information (e.g. deviceName, deviceId)?
-            # TODO - maybe tailor this to info.BrandDisplayName and info.ModelDisplayName instead?
-            includeOriginDeviceInfo:bool = False
-            if (info.PublicKey == 'SU5WQUxJRA==') and (info.Availability == 'NOT-LOADED'):
-                includeOriginDeviceInfo = True
-            elif info.TokenType == 'authorization_code':                
-                includeOriginDeviceInfo = True
-
             # execute the Spotify Zeroconf API addUser request.
             responseData:dict = self._ConnectAddUser(
                 info,
@@ -350,7 +355,6 @@ class ZeroconfConnect:
                 password,
                 loginId,
                 apiMethodName,
-                includeOriginDeviceInfo=includeOriginDeviceInfo
                 )
 
             # process results.
@@ -402,7 +406,6 @@ class ZeroconfConnect:
                     password,
                     loginId,
                     apiMethodName,
-                    includeOriginDeviceInfo=includeOriginDeviceInfo
                     )
 
                 # process results.
@@ -447,7 +450,6 @@ class ZeroconfConnect:
             password:str,
             loginId:str,
             apiMethodName:str,
-            includeOriginDeviceInfo:bool=False,
             ) -> dict:
         """
         Execute the `addUser` request.
@@ -459,19 +461,14 @@ class ZeroconfConnect:
             
             # trace.
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
-            apiMethodParms.AppendKeyValue("includeOriginDeviceInfo", includeOriginDeviceInfo)
             apiMethodParms.AppendKeyValue("info.Availability", info.Availability)
             apiMethodParms.AppendKeyValue("info.PublicKey", info.PublicKey)
             apiMethodParms.AppendKeyValue("info.DeviceId", info.DeviceId)
             apiMethodParms.AppendKeyValue("info.RemoteName", info.RemoteName)
             _logsi.LogMethodParmList(SILevel.Verbose, "Issuing Spotify Connect Zeroconf addUser request (ip=%s)" % self._HostIpAddress, apiMethodParms)
         
-            # validations.
-            if (includeOriginDeviceInfo is None):
-                includeOriginDeviceInfo = False
-            
             # formulate the blob.
-            credentials:Credentials = Credentials(username, password)
+            credentials:Credentials = Credentials(username, password, AuthenticationTypes.USER_PASS)
             builder = BlobBuilder(credentials, info.DeviceId, info.PublicKey)
             blob = builder.build()
         
@@ -484,22 +481,36 @@ class ZeroconfConnect:
                 'Connection': 'close'
             }
             _logsi.LogDictionary(SILevel.Debug, "ZeroconfConnect http request: '%s' (headers)" % (endpoint), reqHeaders)
-            
-            # set tokenType based on getInfo token type.
-            # if TokenType is 'athorization_code', then use it as-is;
-            # if TokenType is 'accesstoken', then use `default`.
-            # otherwise, use 'default'.
+
+            # set defaults used by most manufacturers - we will tailor these in the
+            # logic below for specific manufacturers / devices as required:
+            # - clientKey should be the getInfo response PublicKey (base64 encoded).
+            # - exclude origin device information from the addUser request.
+            # - tokenType should be set to 'default'.
+            clientKey:str = builder.dh_keys.PublicKeyBase64String
+            includeOriginDeviceInfo:bool = False
             tokenType:str = 'default'
-            if info.TokenType == 'authorization_code':
-                tokenType = info.TokenType
             
-            # set clientKey based on getInfo token type.
-            # if TokenType is 'athorization_code', then clientKey should be null.
-            # otherwise, clientKey should be the PublicKey (base64 encoded).
-            clientKey:str = builder.dh_keys.PublicKeyBase64String
-            if info.TokenType == 'authorization_code':
+            # include the origin device information if PublicKey="INVALID" (base64 encoded) and availability="NOT-LOADED".
+            if (info.PublicKey == 'SU5WQUxJRA==') and (info.Availability == 'NOT-LOADED'):
+                includeOriginDeviceInfo = True
+
+            # special processing for tokenType "authorization_code":
+            # - include origin device information in the addUser request.
+            # - set the tokenType to 'authorization_code'.
+            # - set the clientKey value to null, as it is contained in the token.
+            if info.TokenType == 'authorization_code':                
                 clientKey = ''
-            
+                includeOriginDeviceInfo = True
+                tokenType = info.TokenType
+                
+                # TODO - not sure of the blob credentials layout for AuthenticationTypes.SPOTIFY_TOKEN requests.
+                # get a Spotify WebServices API auth token that the Sonos device can use.
+                #credentials:Credentials = Credentials(username, authToken, AuthenticationTypes.SPOTIFY_TOKEN)  # authToken is the password
+                #credentials:Credentials = Credentials('', authToken, AuthenticationTypes.SPOTIFY_TOKEN)  # authToken is the password
+                #builder = BlobBuilder(credentials, info.DeviceId, info.PublicKey)
+                #blob = builder.build()
+
             # set request parameters.
             reqData={
                 'action': 'addUser',
@@ -650,6 +661,7 @@ class ZeroconfConnect:
 
                 # was a good http status code returned?
                 if response.status_code == 200:
+                    
                     # yes - default status results if they are not set.
                     result.Status = 101
                     if result.StatusString is None:

spotifywebapipython/zeroconfapi/zeroconfgetinfo.py

@@ -133,7 +133,7 @@ class ZeroconfGetInfo(ZeroconfResponse):
 
         Device aliases will show up as separate devices in the Spotify app.  
         
-        Note
+        A maximum of 8 aliases are supported (SP_MAX_DEVICE_ALIASES).
         
         Please refer to the `RemoteName` property for more information.       
         """
@@ -146,9 +146,12 @@ class ZeroconfGetInfo(ZeroconfResponse):
         The SpZeroConfVars availability field returned by SpZeroConfGetVars.  
         
         The following are values that I have encountered thus far:  
-        - "" = Device is available and ready for use.
+        - ""            - Device is available and ready for use.
         - "UNAVAILABLE" - Device is unavailable, and should probably be rebooted.
-        - "NOT-LOADED" - Spotify SDK / API is not loaded.
+        - "NOT-LOADED"  - Spotify SDK / API is not loaded.
+        
+        The maximum length of the availability string (SP_MAX_AVAILABILITY_LENGTH) 
+        is 15 characters (not counting terminating NULL).       
         """
         return self._Availability
 
@@ -157,6 +160,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def BrandDisplayName(self) -> str:
         """ 
         A UTF-8-encoded brand name of the hardware device, for hardware integrations (e.g. "Bose", "Onkyo", etc).
+        
+        The maximum length of the brand display name (SP_MAX_BRAND_NAME_LENGTH) 
+        is 32 characters (not counting terminating NULL).       
         """
         return self._BrandDisplayName
 
@@ -165,6 +171,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def ClientId(self) -> str:
         """ 
         Client id of the application (e.g. "79ebcb219e8e4e123456789000123456").
+        
+        The maximum length of the client ID value (SP_MAX_CLIENT_ID_LENGTH) 
+        is 32 characters (not counting terminating NULL).
         """
         return self._ClientId
 
@@ -173,6 +182,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def DeviceId(self) -> str:
         """ 
         Unique device ID used for ZeroConf logins (e.g. "30fbc80e35598f3c242f2120413c943dfd9715fe").
+
+        The maximum length of the device ID value used for ZeroConf logins (SP_MAX_DEVICE_ID_LENGTH) 
+        is 64 characters (not counting terminating NULL).
         """
         return self._DeviceId
     
@@ -191,20 +203,23 @@ class ZeroconfGetInfo(ZeroconfResponse):
         Type of the device (e.g. "SPEAKER", "AVR", etc).
         
         Can be any of the following `SpDeviceType` devices:
-        - kSpDeviceTypeComputer	    Laptop or desktop computer device.
-        - kSpDeviceTypeTablet	    Tablet PC device.
-        - kSpDeviceTypeSmartphone	Smartphone device.
-        - kSpDeviceTypeSpeaker	    Speaker device.
-        - kSpDeviceTypeTV	        Television device.
-        - kSpDeviceTypeAVR	        Audio/Video receiver device.
-        - kSpDeviceTypeSTB	        Set-Top Box device.
-        - kSpDeviceTypeAudioDongle	Audio dongle device.
-        - kSpDeviceTypeGameConsole	Game console device.
-        - kSpDeviceTypeCastVideo	Chromecast Video.
-        - kSpDeviceTypeCastAudio	Chromecast Audio.
-        - kSpDeviceTypeAutomobile	Automobile.
-        - kSpDeviceTypeSmartwatch	Smartwatch.
-        - kSpDeviceTypeChromebook	Chromebook.        
+        - Computer	    Laptop or desktop computer device.
+        - Tablet	    Tablet PC device.
+        - Smartphone	Smartphone device.
+        - Speaker	    Speaker device.
+        - TV	        Television device.
+        - AVR	        Audio/Video receiver device.
+        - STB	        Set-Top Box device.
+        - AudioDongle	Audio dongle device.
+        - GameConsole	Game console device.
+        - CastVideo	    Chromecast Video.
+        - CastAudio	    Chromecast Audio.
+        - Automobile	Automobile.
+        - Smartwatch	Smartwatch.
+        - Chromebook	Chromebook.        
+        
+        The maximum length of the device type string (SP_MAX_DEVICE_TYPE_LENGTH) 
+        is 15 characters (not counting terminating NULL).
         """
         return self._DeviceType
     
@@ -221,6 +236,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def GroupStatus(self) -> str:
         """ 
         The SpZeroConfVars group_status field returned by SpZeroConfGetVars (e.g. "NONE").
+
+        The maximum length of the group status string (SP_MAX_GROUP_STATUS_LENGTH) 
+        is 15 characters (not counting terminating NULL).
         """
         return self._GroupStatus
 
@@ -255,6 +273,19 @@ class ZeroconfGetInfo(ZeroconfResponse):
         return False
     
 
+    @property
+    def IsBrandSonos(self) -> bool:
+        """ 
+        Returns True if the device is a 'Sonos' branded device; otherwise, False.
+        
+        Determination is made based upon the `BrandDisplayName` property value.
+        """
+        result:bool = False
+        if (isinstance(self._BrandDisplayName, str)) and (self._BrandDisplayName.lower().strip() == 'sonos'):
+            result = True
+        return result
+    
+
     @property
     def LibraryVersion(self) -> str:
         """ 
@@ -267,6 +298,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def ModelDisplayName(self) -> str:
         """ 
         A UTF-8-encoded model name of the hardware device, for hardware integrations (e.g. "Soundtouch").
+        
+        The maximum length of the model display name (SP_MAX_MODEL_NAME_LENGTH) 
+        is 30 characters (not counting terminating NULL).
         """
         return self._ModelDisplayName
 
@@ -283,6 +317,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def PublicKey(self) -> str:
         """ 
         Public key used in ZeroConf logins (e.g. "G+ZM4irhc...").
+        
+        The maximum length of the public key used in ZeroConf logins (SP_MAX_PUBLIC_KEY_LENGTH) 
+        is 149 characters (not counting terminating NULL).
         """
         return self._PublicKey
 
@@ -328,6 +365,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def Scope(self) -> str:
         """ 
         OAuth scope requested when authenticating with the Spotify backend (e.g. "streaming").
+        
+        The maximum length of the token type string (SP_MAX_SCOPE_LENGTH) 
+        is 64 characters (not counting terminating NULL).
         """
         return self._Scope
 
@@ -344,6 +384,8 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def SupportedDrmMediaFormats(self) -> list:
         """ 
         The SpZeroConfVars supported_drm_media_formats field returned by SpZeroConfGetVars (e.g. []).
+        
+        A maximum of 8 formats are supported (SP_MAX_SUPPORTED_FORMATS).
         """
         return self._SupportedDrmMediaFormats
 
@@ -351,7 +393,13 @@ class ZeroconfGetInfo(ZeroconfResponse):
     @property
     def TokenType(self) -> str:
         """ 
-        Token type provided by the client (e.g. "accesstoken", "authorization_code", etc).
+        Token type provided by the client:
+        - "accesstoken"         Access token.
+        - "authorization_code"  OAuth Authorization Code token.
+        - "default"             Default access token.
+        
+        The maximum length of the token type string (SP_MAX_TOKEN_TYPE_LENGTH) 
+        is 30 characters (not counting terminating NULL).
         """
         return self._TokenType
 
@@ -360,6 +408,9 @@ class ZeroconfGetInfo(ZeroconfResponse):
     def Version(self) -> str:
         """ 
         ZeroConf API version number (e.g. "2.10.0").
+        
+        The maximum length of the library version string (SP_MAX_VERSION_LENGTH) 
+        is 30 characters (not counting terminating NULL).
         """
         return self._Version