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

spotifywebapipython/models/spotifyconnectdevices.py

@@ -0,0 +1,628 @@
+# external package imports.
+from datetime import datetime
+from typing import Iterator
+
+# our package imports.
+from ..sautils import export
+from .device import Device
+from .spotifyconnectdevice import SpotifyConnectDevice
+from .playerplaystate import PlayerPlayState
+from .zeroconfdiscoveryresult import ZeroconfDiscoveryResult
+from spotifywebapipython.zeroconfapi import ZeroconfGetInfo, ZeroconfGetInfoAlias
+
+# get smartinspect logger reference; create a new session for this module name.
+from smartinspectpython.siauto import SIAuto, SILevel, SISession, SIMethodParmListContext, SIColors
+import logging
+
+_logsi:SISession = SIAuto.Si.GetSession(__name__)
+if (_logsi == None):
+    _logsi = SIAuto.Si.AddSession(__name__, True)
+_logsi.SystemLogger = logging.getLogger(__name__)
+
+
+@export
+class SpotifyConnectDevices():
+    """
+    Spotify Connect Devices collection.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initializes a new instance of the class.
+        """
+        self._DateLastRefreshed:int = 0
+        self._Items:list[SpotifyConnectDevice] = []
+
+
+    def __getitem__(self, key) -> SpotifyConnectDevice:
+        return self._Items[key]
+
+
+    def __iter__(self) -> Iterator:
+        return iter(self._Items)
+
+
+    def __len__(self) -> int:
+        return len(self._Items)
+
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def AgeLastRefreshed(self) -> float:
+        """ 
+        Number of seconds between the current date time and the `DateLastRefreshed` property value.
+        """
+        return (datetime.utcnow().timestamp() - self._DateLastRefreshed)
+    
+
+    @property
+    def DateLastRefreshed(self) -> float:
+        """ 
+        Date and time the device list was last refreshed, in unix epoch format (e.g. 1669123919.331225).
+        """
+        return self._DateLastRefreshed
+    
+    @DateLastRefreshed.setter
+    def DateLastRefreshed(self, value:float):
+        """ 
+        Sets the DateLastRefreshed property value.
+        """
+        if isinstance(value, float):
+            self._DateLastRefreshed = value
+    
+
+    @property
+    def Items(self) -> list[SpotifyConnectDevice]:
+        """ 
+        Array of `SpotifyConnectDevice` objects.
+        """
+        return self._Items
+    
+
+    @property
+    def ItemsCount(self) -> int:
+        """ 
+        Number of objects in the `Items` property array.
+        """
+        if self._Items is not None:
+            return len(self._Items)
+        return 0
+    
+
+    def AddDynamicDevice(
+        self, 
+        device:Device, 
+        activeUser:str
+        ) -> None:
+        """ 
+        Adds a new dynamic device entry to the `Items` collection.  
+        
+        Args:
+            device (Device):
+                Device information to add.
+            activeUser (str):
+                Currently active user id.
+
+        Dynamic devices are Spotify Connect devices that are not found in Zeroconf discovery
+        process, but still exist in the player device list.  These are usually Spotify Player
+        client devices (e.g. mobile / web / desktop players) that utilize temporary device id's.
+        """
+        # validations.
+        if (device is None) or (not isinstance(device, Device)):
+            return
+        
+        # build zeroconf discovery result with what we can.
+        discoverResult:ZeroconfDiscoveryResult = ZeroconfDiscoveryResult()
+        discoverResult.DeviceName = device.Name
+        discoverResult.HostIpAddresses.append('127.0.0.1')
+        discoverResult.Server = '127.0.0.1'
+        discoverResult.HostIpPort = 0
+        discoverResult.Name = device.Name
+        discoverResult.SpotifyConnectCPath = '/zc'
+        discoverResult.SpotifyConnectVersion = '1.0'
+
+        # build zeroconf getinfo result with what we can.
+        info:ZeroconfGetInfo = ZeroconfGetInfo()
+        info.ActiveUser = activeUser
+        info.DeviceId = device.Id
+        info.DeviceType = device.Type
+        info.RemoteName = device.Name
+        info.SpotifyError = 0
+        info.Status = 101
+        info.StatusString = 'OK'
+        
+        # populate brand info for popular devices.
+        if (device.Name == "Web Player (Chrome)"):
+            info.BrandDisplayName = 'Google'
+            info.ModelDisplayName = 'Chrome'
+            info.ProductId = 'Web Player'
+        elif (device.Name == "Web Player (Microsoft Edge)"):
+            info.BrandDisplayName = 'Microsoft'
+            info.ModelDisplayName = 'Edge'
+            info.ProductId = 'Web Player'
+        else:
+            info.BrandDisplayName = 'unknown'
+            info.ModelDisplayName = 'unknown'
+            info.ProductId = 'unknown'
+        
+        # add the device.
+        scDevice:SpotifyConnectDevice = SpotifyConnectDevice()
+        scDevice.Id = info.DeviceId
+        scDevice.Name = info.RemoteName
+        scDevice.DeviceInfo = info
+        scDevice.DiscoveryResult = discoverResult
+        self._Items.append(scDevice)
+
+        # trace.
+        _logsi.LogVerbose("Added SpotifyConnectDevices collection entry: \"%s\" (dynamic device=%s)" % (scDevice.Title, discoverResult.IsDynamicDevice), colorValue=SIColors.ForestGreen)
+
+
+    def GetActiveDevice(
+        self, 
+        ) -> SpotifyConnectDevice:
+        """ 
+        Returns a Spotify Connect device if one is currently marked as the active device;
+        otherwise, null if there is no active device.
+
+        Note that this does not perform a real-time Spotify Web API query for the active device.
+        It simply checks the devices collection for an entry that was marked as the active device
+        by the `UpdatePlayerDevices` method.
+        """
+        # find and return the active device if one exists; otherwise, null.
+        result:SpotifyConnectDevice = None
+        scDevice:SpotifyConnectDevice
+        for scDevice in self._Items:
+            if (scDevice.DeviceInfo is not None):
+                if (scDevice.DeviceInfo.IsActiveDevice):
+                    result = scDevice
+                    break
+        return result
+
+
+    def RemoveDevice(
+        self,
+        deviceId:str,
+        dynamicDeviceOnly:bool=False
+        ) -> None:
+        """
+        Removes existing device entry(s) from the `Items` collection by device id value.
+        
+        Args:
+            deviceId (str):
+                Device id to remove.
+            dynamicDeviceOnly (str):
+                True to only remove the device if it's a dynamic device entry;
+                otherwise, False to remove the device id regardless.  
+                Default is False.
+
+        It's possible to have multiple devices with the same id (e.g. both a dynamic and a
+        zeroconf registered device).
+
+        Dynamic devices are Spotify Connect devices that are not found in Zeroconf discovery
+        process, but still exist in the player device list.  These are usually Spotify Player
+        client devices (e.g. mobile / web / desktop players) that utilize temporary device id's.
+        """
+        # validations.
+        if (not isinstance(dynamicDeviceOnly,bool)):
+            dynamicDeviceOnly = False
+
+        # remove device from devices collection;
+        # the reversed() function creates an iterator that traverses the list in reverse order. 
+        # this ensures that removing an element doesn't affect the indices of the subsequent 
+        # elements we're going to iterate over.
+        deviceIdCompare:str = "" + deviceId.lower()
+        scDevice:SpotifyConnectDevice
+        for idx in reversed(range(len(self._Items))):
+
+            scDevice = self._Items[idx]
+
+            # did we find a match by device id?
+            if (deviceIdCompare == scDevice.Id.lower()):
+
+                isFound:bool = True
+
+                # get dynamic device status.
+                isDynamic:bool = False
+                if (scDevice.DiscoveryResult is not None):
+                   isDynamic = scDevice.DiscoveryResult.IsDynamicDevice
+
+                # are we checking for dynamic device? if so, and it's NOT dynamic, then don't delete it!
+                if (dynamicDeviceOnly) and (not isDynamic):
+                    isFound = False
+
+                # are we deleting this device?
+                if (isFound):
+                    _logsi.LogVerbose("Removing SpotifyConnectDevices collection entry: \"%s\" - %s" % (scDevice.Title, scDevice.DiscoveryResult.Description), colorValue=SIColors.Orange)
+                    self._Items.pop(idx)
+
+
+    def UpdatePlayerDevices(
+        self, 
+        playerDevices:list[Device],
+        activeUser:str,
+        playerState:PlayerPlayState=None
+        ) -> SpotifyConnectDevice:
+        """ 
+        Adds a list of dynamic player device entries to the `Items` collection, removes any
+        existing dynamic devices from the collection that are not in the `playerDevices` list,
+        and updates the currently active device based on playerState.
+        
+        Args:
+            playerDevices (list[Device]):
+                List of current player devices obtained via a call to `GetPlayerDevices` method.
+            activeUser (str):
+                Currently active user id.
+            playerState (PlayerPlayState):
+                Current player state obtained via a call to `GetPlayerPlaybackState` method
+                which will be used to set the active device in the `Items` collection;
+                otherwise, null to bypass active device set.
+
+        Returns:
+            null if the `playerState` argument was not specified; 
+            otherwise, the currently active Spotify Player device instance as determined by
+            the Spotify Player PlayState.
+
+        Dynamic devices are Spotify Connect devices that are not found in Zeroconf discovery
+        process, but still exist in the player device list.  These are usually Spotify Player
+        client devices (e.g. mobile / web / desktop players) that utilize temporary device id's.
+        """
+        result:SpotifyConnectDevice = None
+
+        # validations
+        if (not isinstance(playerDevices, list)):
+            return result
+
+        # add dynamic devices.
+        scDevice:SpotifyConnectDevice
+        device:Device
+        for device in playerDevices:
+
+            # is the player device present in the collection? if not, then add it.
+            if (not self.ContainsDeviceId(device.Id)):
+                self.AddDynamicDevice(device, activeUser)
+                        
+            # is the device in the available device list for this user context?
+            # if not, then set an indicator so we can re-activate it later if need be.
+            for scDevice in self._Items:
+                if (scDevice.DeviceInfo.DeviceId == device.Id):
+                    scDevice.DeviceInfo.IsInDeviceList = True
+                    break
+
+        # remove stale dynamic devices from results collection;
+        # the reversed() function creates an iterator that traverses the list in reverse order. 
+        # this ensures that removing an element doesn't affect the indices of the subsequent 
+        # elements we're going to iterate over.
+        for idx in reversed(range(len(self._Items))):
+
+            # only process dynamic devices.
+            scDevice = self._Items[idx]
+            if (scDevice.DiscoveryResult.IsDynamicDevice):
+
+                # process all player devices.
+                wasFound:bool = False
+                playerDevice:Device
+                for playerDevice in playerDevices:
+                    if (scDevice.Id == playerDevice.Id):
+                        wasFound = True
+                        break
+
+                # if collection entry was not found in the player device list then remove it.
+                if (not wasFound):
+                    _logsi.LogVerbose("Removed dynamic device \"%s\" (%s) from Spotify Connect Devices collection" % (scDevice.Name, scDevice.Id))
+                    self._Items.pop(idx)
+
+        # update active device entry.
+        # returns null if the `playerState` argument was not specified; 
+        # otherwise, the currently active Spotify Player device instance as determined by
+        # the Spotify Player PlayState (could be null if no active device).
+        result = self.UpdateActiveDevice(playerState)
+        return result
+
+
+    def UpdateActiveDevice(
+        self, 
+        playerState:PlayerPlayState=None
+        ) -> SpotifyConnectDevice:
+        """ 
+        Updates the currently active device based on playerState.
+        
+        Args:
+            playerState (PlayerPlayState):
+                Current player state obtained via a call to `GetPlayerPlaybackState` method
+                which will be used to set the active device in the `Items` collection;
+                otherwise, null to bypass active device set.
+
+        Returns:
+            The currently active Spotify Player device instance as determined by
+            the Spotify Player PlayState; could be null if no active device was found.
+        """
+        result:SpotifyConnectDevice = None
+
+        if (isinstance(playerState, PlayerPlayState)):
+
+            # we do this in case the active device is a "restricted" device; if it is, then it may 
+            # not show up as the active device (common issue with Sonos devices).  
+            # in this case, it WILL show up in the player state device property as the active device.
+            # if it IS active, then we will set the active flag.        
+            # note that the PlayerPlayState device is a name and not a device id.
+            if playerState.Device is not None:
+
+                device = playerState.Device
+                for scDevice in self._Items:
+                    scDevice.DeviceInfo.IsActiveDevice = False
+                    if (device.Name == scDevice.Name):
+                        _logsi.LogVerbose("Spotify Connect active device detected: \"%s\" (%s)" % (device.Name, device.Id))
+                        scDevice.DeviceInfo.IsActiveDevice = True
+                        result = scDevice
+
+        # returns null if the `playerState` argument was not specified; 
+        # otherwise, the currently active Spotify Player device instance as determined by
+        # the Spotify Player PlayState (could be null if no active device).
+        return result
+
+
+    def ContainsDeviceId(self, value:str) -> bool:
+        """ 
+        Returns True if the `Items` collection contains the specified device id value;
+        otherwise, False.
+        
+        Alias entries (if any) are also compared.
+        """
+        scDevice:SpotifyConnectDevice = self.GetDeviceById(value)
+        if scDevice is not None:
+            return True
+        return False
+
+
+    def ContainsDeviceName(self, value:str) -> bool:
+        """ 
+        Returns True if the `Items` collection contains the specified device name value;
+        otherwise, False.
+        
+        Alias entries (if any) are also compared.
+        """
+        scDevice:SpotifyConnectDevice = self.GetDeviceByName(value)
+        if scDevice is not None:
+            return True
+        return False
+        
+
+    def ContainsZeroconfEndpointGetInformation(self, value:str) -> bool:
+        """ 
+        Returns True if the `Items` collection contains the specified Zeroconf getInfo Endpoint url value;
+        otherwise, False.
+        """
+        result:bool = False
+        if value is None:
+            return result
+        
+        # convert case for comparison.
+        value = value.lower()
+        
+        # process all discovered devices.
+        scDevice:SpotifyConnectDevice
+        for scDevice in self._Items:
+            if (scDevice.DiscoveryResult.ZeroconfApiEndpointGetInformation.lower() == value):
+                result = True
+                break
+        return result
+    
+
+    def GetDeviceByDiscoveryKey(self, value:str) -> SpotifyConnectDevice:
+        """ 
+        Returns a `SpotifyConnectDevice` instance if the `Items` collection contains the specified 
+        device zeroconf discovery results key value; otherwise, None.
+        """
+        result:SpotifyConnectDevice = None
+        if value is None:
+            return result
+        
+        # convert case for comparison.
+        value = value.lower()
+
+        # process all devices, comparing discovery keys.
+        for i in range(len(self._Items)):
+            if (self._Items[i].DiscoveryResult is not None):
+                if (self._Items[i].DiscoveryResult.Key is not None):
+                    if (self._Items[i].DiscoveryResult.Key.lower() == value):
+                        result = self._Items[i]
+                        break       
+        return result
+
+
+    def GetDeviceById(self, value:str) -> SpotifyConnectDevice:
+        """ 
+        Returns a `SpotifyConnectDevice` instance if the `Items` collection contains the specified 
+        device id value; otherwise, None.
+        
+        Alias entries (if any) are also compared.
+        """
+        result:SpotifyConnectDevice = None
+        if value is None:
+            return result
+        
+        # convert case for comparison.
+        value = value.lower()
+        
+        # process all discovered devices.
+        scDevice:SpotifyConnectDevice
+        for scDevice in self._Items:
+            if (scDevice.DeviceInfo.HasAliases):
+                scAlias:ZeroconfGetInfoAlias
+                for scAlias in scDevice.DeviceInfo.Aliases:
+                    if (scAlias.Id.lower() == value):
+                        result = scDevice
+                        break
+                if result:
+                    break
+            else:
+                if (scDevice.DeviceInfo.DeviceId.lower() == value):
+                    result = scDevice
+                    break
+        return result
+    
+
+    def GetDeviceByName(self, value:str) -> SpotifyConnectDevice:
+        """ 
+        Returns a `SpotifyConnectDevice` instance if the `Items` collection contains the specified 
+        device name value; otherwise, None.
+        
+        Alias entries (if any) are also compared.
+        """
+        result:SpotifyConnectDevice = None
+        if value is None:
+            return result
+        
+        # convert case for comparison.
+        value = value.lower()
+        
+        # process all discovered devices.
+        scDevice:SpotifyConnectDevice
+        for scDevice in self._Items:
+            if (scDevice.DeviceInfo.HasAliases):
+                scAlias:ZeroconfGetInfoAlias
+                for scAlias in scDevice.DeviceInfo.Aliases:
+                    if (scAlias.Name.lower() == value):
+                        result = scDevice
+                        break
+                if result is not None:
+                    break
+            else:
+                if (scDevice.DeviceInfo.RemoteName.lower() == value):
+                    result = scDevice
+                    break
+        return result
+    
+
+    def GetDeviceList(self) -> list[Device]:
+        """
+        Returns a list of `Device` objects that can be used to build a selection list
+        of available devices.  
+        
+        Note that the `Device` object has the following properties populated:
+        Id, Name, IsActive, Type.
+        """
+        result:list[Device] = []
+        
+        # process all discovered devices.
+        scDevice:SpotifyConnectDevice
+        for scDevice in self._Items:
+
+            # map device information details.
+            info:ZeroconfGetInfo = scDevice.DeviceInfo
+
+            # create new mock device.
+            device = Device()
+            device.Type = info.DeviceType
+                
+            # are aliases being used (RemoteName is null if so)?
+            if info.RemoteName is None:
+                    
+                # if aliases are defined, then use the alias details.
+                infoAlias:ZeroconfGetInfoAlias
+                for infoAlias in info.Aliases:
+                    device.Id = infoAlias.Id
+                    device.Name = infoAlias.Name
+
+            else:
+
+                # if no aliases then use the remote name and id.
+                device.Id = info.DeviceId
+                device.Name = info.RemoteName
+                
+            # append device to results.
+            result.append(device)
+
+        # sort items on Name property, ascending order.
+        if len(result) > 0:
+            result.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
+
+        return result
+    
+
+    def GetDeviceIndexByDiscoveryKey(self, value:str) -> int:
+        """ 
+        Returns the index of the `Items` collection entry that contains 
+        the specified device zeroconf discovery results key value if found; 
+        otherwise, -1.
+        """
+        result:int = -1
+        if value is None:
+            return result
+        
+        # convert case for comparison.
+        value = value.lower()
+
+        # process all devices, comparing discovery keys.
+        for i in range(len(self._Items)):
+            if (self._Items[i].DiscoveryResult is not None):
+                if (self._Items[i].DiscoveryResult.Key is not None):
+                    if (self._Items[i].DiscoveryResult.Key.lower() == value):
+                        result = i
+                        break       
+        return result
+
+
+    def GetDeviceIndexByDiscoveryName(self, value:str) -> int:
+        """ 
+        Returns the index of the `Items` collection entry that contains 
+        the specified device zeroconf discovery results name value if found; 
+        otherwise, -1.
+        """
+        result:int = -1
+        if value is None:
+            return result
+        
+        # convert case for comparison.
+        value = value.lower()
+
+        # process all devices, comparing discovery keys.
+        for i in range(len(self._Items)):
+            if (self._Items[i].DiscoveryResult is not None):
+                if (self._Items[i].DiscoveryResult.Name is not None):
+                    if (self._Items[i].DiscoveryResult.Name.lower() == value):
+                        result = i
+                        break       
+        return result
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'AgeLastRefreshed': self.AgeLastRefreshed,
+            'DateLastRefreshed': self._DateLastRefreshed,
+            'ItemsCount': self.ItemsCount,
+            'Items': [ item.ToDictionary() for item in self._Items ],
+        }
+
+        return result
+        
+           
+    def ToString(self, includeItems:bool=False) -> str:
+        """
+        Returns a displayable string representation of the class.
+        
+        Args:
+            includeItems (bool):
+                True to include the Items collection of objects; otherwise, False
+                to only return base properties.
+        """
+        msg:str = 'Items Count=%s' % (str(self.ItemsCount))
+        msg:str = '%s, DateLastRefreshed=%s' % (msg, str(self._DateLastRefreshed))
+        
+        if (includeItems):
+            item:SpotifyConnectDevice
+            for item in self._Items:
+                msg = "%s\n- %s" % (msg, item.ToString(True))
+            
+        return msg 

spotifywebapipython/models/track.py

@@ -120,7 +120,8 @@ class Track(TrackSimplified):
         {
             'album': album,
             'external_ids': externalIds,
-            'popularity': self._Popularity
+            'popularity': self._Popularity,
+            'image_url': self.ImageUrl,
         }
         
         # combine base class results with these results.

spotifywebapipython/models/trackpage.py

@@ -38,7 +38,8 @@ class TrackPage(PageObject):
             items:list = root.get('items',None)
             if items is not None:
                 for item in items:
-                    self._Items.append(Track(root=item))
+                    if item is not None:
+                        self._Items.append(Track(root=item))
 
         
     def __repr__(self) -> str:
@@ -57,6 +58,46 @@ class TrackPage(PageObject):
         return self._Items
     
 
+    def GetUris(self, afterUri:str=None) -> str:
+        """ 
+        Gets a comma-delimited list of uri's contained in the underlying `Items` list.
+        
+        args:
+            afterUri (str):
+                If specified, the process will look for this uri before adding subsequent
+                uri's to the returned results.  This allows you to skip uri's that have
+                recently been played.
+        
+        This is a convenience method so one does not have to loop through the `Items`
+        array of PlayHistory objects to get the list of uri's.
+        """
+        result:str = ""
+        addUri:bool = False
+        item:Track
+
+        # add uri's from the beginning if no `afterUri` argument was passed.
+        if (afterUri is None) or (len(afterUri.strip()) == 0):
+            addUri = True
+        
+        for item in self._Items:
+
+            if (not addUri):
+
+                # check for `afterUri` match; if found, we will start adding uri's
+                # to the list with the next item.
+                if (afterUri == item.Uri):
+                    addUri = True
+                    
+            elif (addUri):
+                
+                # add item uri to the list.
+                if (len(result) > 0):
+                    result += ","
+                result += item.Uri
+                
+        return result
+    
+
     def ToString(self, includeItems:bool=False) -> str:
         """
         Returns a displayable string representation of the class.

spotifywebapipython/models/trackpagesaved.py

@@ -39,7 +39,8 @@ class TrackPageSaved(PageObject):
             items:list = root.get('items',None)
             if items is not None:
                 for item in items:
-                    self._Items.append(TrackSaved(root=item))
+                    if item is not None:
+                        self._Items.append(TrackSaved(root=item))
 
         
     def __repr__(self) -> str: