spotifywebapiPython 1.0.242__py3-none-any.whl

spotifywebapipython/models/spotifyconnectdevices.py

@@ -0,0 +1,441 @@
+# 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 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.
+
+        All Spotify Connect Zeroconf GetInfo response `DeviceId` entries are checked
+        first; if not resolved, then base device `Id` entries are checked.  We do it
+        this way in case a Spotify Connect Zeroconf GetInfo response has not been 
+        recevied for a device yet.
+        """
+        result:SpotifyConnectDevice = None
+        if value is None:
+            return result
+        if value == "":
+            return result
+        
+        # convert case for comparison.
+        value = value.lower()
+        
+        # process all discovered devices.
+        scDevice:SpotifyConnectDevice
+        for scDevice in self._Items:
+
+            # check for id in the Spotify Connect Zeroconf GetInfo response.
+            if (scDevice.DeviceInfo.DeviceId is not None):
+                if (scDevice.DeviceInfo.DeviceId.lower() == value):
+                    result = scDevice
+                    _logsi.LogVerbose("GetDeviceById found SpotifyConnectDevices collection entry: %s (DeviceInfo.DeviceId)" % scDevice.Title)
+                    break
+
+
+        # if not resolved, then check for id in the base device definition.
+        if (result is None):
+
+            # process all discovered devices.
+            scDevice:SpotifyConnectDevice
+            for scDevice in self._Items:
+
+                # check for id in the base device definition.
+                if (scDevice.Id is not None):
+                    if (scDevice.Id.lower() == value):
+                        result = scDevice
+                        _logsi.LogVerbose("GetDeviceById found SpotifyConnectDevices collection entry: %s (Device.Id)" % scDevice.Title)
+                        break
+
+        # trace.
+        if (result is None):
+            _logsi.LogVerbose("GetDeviceById could not find SpotifyConnectDevices collection entry: \"%s\"" % value)
+
+        return result
+    
+
+    def GetDeviceByName(self, value:str) -> SpotifyConnectDevice:
+        """ 
+        Returns a `SpotifyConnectDevice` instance if the `Items` collection contains the specified 
+        device name value; otherwise, None.
+        
+        All Spotify Connect Zeroconf GetInfo response `RemoteName` / Zeroconf DiscoveryResult 
+        `DeviceName` entries are checked first; if not resolved, then Spotify Connect Zeroconf 
+        GetInfo `Alias` entries are checked.  We do it this way in case an alias name is defined 
+        for a Spotify Connect Zeroconf entry that already exists with the same name (e.g. the 
+        RemoteName entry will take precedence).
+        """
+        result:SpotifyConnectDevice = None
+        if value is None:
+            return result
+        if value == "":
+            return result
+        
+        # convert case for comparison.
+        value = value.lower()
+        
+        # process all discovered devices.
+        scDevice:SpotifyConnectDevice
+        for scDevice in self._Items:
+
+            # match on `getInfo` RemoteName value (if defined).
+            if (scDevice.DeviceInfo.RemoteName is not None):
+                if (scDevice.DeviceInfo.RemoteName.lower() == value):
+                    result = scDevice
+                    _logsi.LogVerbose("GetDeviceByName found SpotifyConnectDevices collection entry: %s (DeviceInfo.RemoteName)" % scDevice.Title)
+                    break
+
+            # match on Zeroconf DeviceName value (if defined).
+            if (scDevice.DiscoveryResult.DeviceName is not None):
+                if (scDevice.DiscoveryResult.DeviceName.lower() == value):
+                    result = scDevice
+                    _logsi.LogVerbose("GetDeviceByName found SpotifyConnectDevices collection entry: %s (DiscoveryResult.DeviceName)" % scDevice.Title)
+                    break
+
+        # if not resolved, then search by alias name.
+        if (result is None):
+
+            # process all discovered devices.
+            scDevice:SpotifyConnectDevice
+            for scDevice in self._Items:
+
+                # search aliases (if defined).
+                if (scDevice.DeviceInfo.HasAliases):
+                    scAlias:ZeroconfGetInfoAlias
+                    for scAlias in scDevice.DeviceInfo.Aliases:
+                        if (scAlias.Name is not None):
+                            if (scAlias.Name.lower() == value):
+                                result = scDevice
+                                _logsi.LogVerbose("GetDeviceByName found SpotifyConnectDevices collection entry: %s (DeviceInfo.Aliases)" % scDevice.Title)
+                                break
+                    if result is not None:
+                        break
+
+        # trace.
+        if (result is None):
+            _logsi.LogVerbose("GetDeviceByName could not find SpotifyConnectDevices collection entry: \"%s\"" % value)
+
+        return result
+    
+
+    def GetDeviceByNameAndId(self, deviceName:str, deviceId:str) -> int:
+        """ 
+        Returns a `SpotifyConnectDevice` instance if the `Items` collection contains the specified 
+        device name and id value; otherwise, None.
+        
+        Alias entries (if any) are NOT compared.
+        """
+        result:SpotifyConnectDevice = None
+        if deviceName is None:
+            return result
+        if deviceId is None:
+            return deviceId
+        
+        # convert case for comparison.
+        deviceName = deviceName.lower()
+        deviceId = deviceId.lower()
+
+        # process all devices, comparing device name and id.
+        scDevice:SpotifyConnectDevice
+        for scDevice in self._Items:
+            if (scDevice.Name is not None) and (scDevice.Id is not None):
+                if (scDevice.Name.lower() == deviceName) and (scDevice.Id.lower() == deviceId):
+                    result = scDevice
+                    _logsi.LogVerbose("GetDeviceByNameAndId found SpotifyConnectDevices collection entry: %s" % scDevice.Title)
+                    break       
+
+        # trace.
+        if (result is None):
+            _logsi.LogVerbose("GetDeviceByNameAndId could not find SpotifyConnectDevices collection entry: \"%s\" (%s)" % (deviceName, deviceId))
+
+        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 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 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

@@ -0,0 +1,142 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .album import Album
+from .externalids import ExternalIds
+from .tracksimplified import TrackSimplified
+
+@export
+class Track(TrackSimplified):
+    """
+    Spotify Web API Track object.
+    """
+
+    def __init__(self, root:dict=None) -> None:
+        """
+        Initializes a new instance of the class.
+        
+        Args:
+            root (dict):
+                Spotify Web API JSON response in dictionary format, used to load object
+                attributes; otherwise, None to not load attributes.
+        """
+        # initialize base class.
+        super().__init__(root=root)
+        
+        self._Album:Album = None
+        self._ExternalIds:ExternalIds = None
+        self._Popularity:int = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._Popularity = root.get('popularity', None)
+
+            # process all collections and objects.
+            item:dict = root.get('album',None)
+            if item is not None:
+                self._Album = Album(root=item)
+
+            item:dict = root.get('external_ids',None)
+            if item is not None:
+                self._ExternalIds = ExternalIds(root=item)
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Album(self) -> Album:
+        """ 
+        The album on which the track appears. 
+        
+        The album object includes a link in href to full information about the album.
+        """
+        return self._Album
+
+
+    @property
+    def ExternalIds(self) -> ExternalIds:
+        """ 
+        Known external ID's for the track.
+        """
+        return self._ExternalIds
+    
+
+    @property
+    def ImageUrl(self) -> str:
+        """
+        Gets the first image url in the album `Images` list, if images are defined;
+        otherwise, null.
+        """
+        if self._Album is not None:
+            return self._Album.ImageUrl
+        return None
+            
+        
+    @property
+    def Popularity(self) -> int:
+        """ 
+        The popularity of the track.  The value will be between 0 and 100, with 100 being the most popular.
+        
+        The popularity of a track is a value between 0 and 100, with 100 being the most popular. 
+        The popularity is calculated by algorithm and is based, in the most part, on the total number 
+        of plays the track has had and how recent those plays are. Generally speaking, songs that are 
+        being played a lot now will have a higher popularity than songs that were played a lot in the past. 
+        
+        Duplicate tracks (e.g. the same track from a single and an album) are rated independently. 
+        Artist and album popularity is derived mathematically from track popularity. 
+        
+        Note: the popularity value may lag actual popularity by a few days: the value is not updated in real time.
+        """
+        return self._Popularity
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        # get base class result.
+        resultBase:dict = super().ToDictionary()
+
+        album:dict = {}
+        if self._Album is not None:
+            album = self._Album.ToDictionary()
+
+        externalIds:dict = {}
+        if self._ExternalIds is not None:
+            externalIds = self._ExternalIds.ToDictionary()
+
+        result:dict = \
+        {
+            'album': album,
+            'external_ids': externalIds,
+            'popularity': self._Popularity,
+            'image_url': self.ImageUrl,
+        }
+        
+        # combine base class results with these results.
+        resultBase.update(result)
+        
+        # return a sorted dictionary.
+        return dict(sorted(resultBase.items()))
+        
+
+    def ToString(self) -> str:
+        """
+        Returns a displayable string representation of the class.
+        """
+        msg:str = 'Track: %s' % super().ToString(False)
+        if self._Album is not None: msg = '%s\n Album="%s"' % (msg, str(self._Album.Name))
+        #if self._ExternalIds is not None: msg = '%s\n %s' % (msg, str(self._ExternalIds))
+        if self._Popularity is not None: msg = '%s\n Popularity="%s"' % (msg, str(self._Popularity))
+        return msg 

spotifywebapipython/models/trackpage.py

@@ -0,0 +1,110 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .track import Track
+from .pageobject import PageObject
+
+@export
+class TrackPage(PageObject):
+    """
+    Spotify Web API TrackPage object.
+    
+    This allows for multiple pages of `Track` objects to be navigated.
+    """
+
+    def __init__(self, root:dict=None) -> None:
+        """
+        Initializes a new instance of the class.
+        
+        Args:
+            root (dict):
+                Spotify Web API JSON response in dictionary format, used to load object
+                attributes; otherwise, None to not load attributes.
+        """
+        # initialize base class.
+        super().__init__(root=root)
+        
+        # initialize storage.
+        self._Items:list[Track] = []
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            # process all collections and objects.
+            items:list = root.get('items',None)
+            if items is not None:
+                for item in items:
+                    if item is not None:
+                        self._Items.append(Track(root=item))
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Items(self) -> list[Track]:
+        """ 
+        Array of `Track` objects.
+        """
+        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.
+        
+        Args:
+            includeItems (bool):
+                True to include the Items collection of objects; otherwise, False
+                to only return base properties.
+        """
+        return 'TrackPage: %s' % super().ToString(includeItems)