spotifywebapiPython 1.0.242__py3-none-any.whl

spotifywebapipython/models/searchresultbase.py

@@ -0,0 +1,299 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .externalurls import ExternalUrls
+from .imageobject import ImageObject
+from .linkedfrom import LinkedFrom
+
+@export
+class SearchResultBase:
+    """
+    Base class used to return basic search results common to all Spotify types.
+
+    This class is not part of the Spotify Web API specification.
+    """
+
+    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.
+        """
+        self._ExternalUrls:ExternalUrls = None
+        self._Href:str = None
+        self._Id:str = None
+        self._Images:list[ImageObject] = []
+        self._LinkedFrom:LinkedFrom = None
+        self._Name:str = None
+        self._Type:str = None
+        self._Uri:str = None
+
+        if (root is None):
+
+            # if not building the class from json response, then initialize various properties as 
+            # the object is probably being built manually.
+            self._ExternalUrls = ExternalUrls()
+        
+        else:
+
+            self._Href = root.get('href', None)
+            self._Id = root.get('id', None)
+            self._Name = root.get('name', None)
+            self._Type = root.get('type', None)
+            self._Uri = root.get('uri', None)
+
+            # process all collections and objects.
+            item:dict = root.get('external_urls',None)
+            if item is not None:
+                self._ExternalUrls = ExternalUrls(root=item)
+
+            item:dict = root.get('linked_from',None)
+            if item is not None:
+                self._LinkedFrom = LinkedFrom(root=item)
+
+            items:list = root.get('images',None)
+            if items is not None:
+                for item in items:
+                    self._Images.append(ImageObject(root=item))
+        
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    # implement sorting support.
+    def __eq__(self, other):
+        try:
+            return self.Name == other.Name
+        except Exception:
+            if (isinstance(self, SearchResultBase )) and (isinstance(other, SearchResultBase )):
+                return self.Name == other.Name
+            return False
+
+    def __lt__(self, other):
+        try:
+            return self.Name < other.Name
+        except Exception:
+            if (isinstance(self, SearchResultBase )) and (isinstance(other, SearchResultBase )):
+                return self.Name < other.Name
+            return False
+
+
+    @property
+    def ExternalUrls(self) -> ExternalUrls:
+        """ 
+        Known external URLs for this object.
+        """
+        return self._ExternalUrls
+    
+
+    @property
+    def Href(self) -> str:
+        """ 
+        A link to the Web API endpoint providing full details of the object.
+        """
+        return self._Href
+
+
+    @property
+    def Id(self) -> str:
+        """ 
+        The Spotify ID for the object.
+        
+        Example: `5v5ETK9WFXAnGQ3MRubKuE`
+        """
+        return self._Id
+
+    @Id.setter
+    def Id(self, value:str):
+        """ 
+        Sets the Id property value.
+        """
+        if isinstance(value, str):
+            self._Id = value
+    
+
+    @property
+    def IdOrigin(self) -> str:
+        """ 
+        The origin Spotify ID for the track.
+        The `LinkedFrom.Id` value is returned if present; 
+        otherwise, the `Id` value is returned.
+
+        This is a helper property, and is not part of the Spotify Web API specification.
+        """
+        if (self.IsLinkedFrom):
+            return self._LinkedFrom.Id
+        return self._Id
+
+
+    @property
+    def Images(self) -> list[ImageObject]:
+        """ 
+        Images for the object.  
+        
+        The array may be empty or contain up to three images.  
+        The images are returned by size in descending order.  
+        Note: If returned, the source URL for the image (url) is temporary and will expire in less than a day.
+        """
+        return self._Images
+
+
+    @property
+    def ImageUrl(self) -> str:
+        """
+        Returns the highest resolution order image from the `Images` list, if images 
+        are defined; otherwise, null.
+        """
+        return ImageObject.GetImageHighestResolution(self._Images)
+            
+        
+    @property
+    def IsLinkedFrom(self) -> bool:
+        """ 
+        Whether or not the track is linked from another track.
+
+        If True, the `LinkedFrom` property contains track origin data;
+        If False, the `LinkedFrom` property is an empty dictionary.
+
+        This is a helper property, and is not part of the Spotify Web API specification.
+        """
+        if (self._LinkedFrom is not None) and (self._LinkedFrom.Id is not None):
+            return True
+        return False
+
+
+    @property
+    def LinkedFrom(self) -> LinkedFrom:
+        """ 
+        Part of the response when Track Relinking is applied, and the requested track has been replaced 
+        with a different track.  The track in the LinkedFrom object contains information about the originally 
+        requested track.
+        """
+        return self._LinkedFrom
+
+
+    @property
+    def Name(self) -> str:
+        """ 
+        The name of the object.
+        """
+        return self._Name
+    
+    @Name.setter
+    def Name(self, value:str):
+        """ 
+        Sets the Name property value.
+        """
+        if isinstance(value, str):
+            self._Name = value
+    
+
+    @property
+    def Type(self) -> str:
+        """ 
+        The object type (e.g. album, artist, audiobook, episode, playlist, show, track, etc).
+        """
+        return self._Type
+
+    @Type.setter
+    def Type(self, value:str):
+        """ 
+        Sets the Type property value.
+        """
+        if isinstance(value, str):
+            self._Type = value
+    
+
+    @property
+    def Uri(self) -> str:
+        """ 
+        The Spotify URI for the object.
+        
+        Example: `spotify:playlist:5v5ETK9WFXAnGQ3MRubKuE`
+        """
+        return self._Uri
+    
+    @Uri.setter
+    def Uri(self, value:str):
+        """ 
+        Sets the Uri property value.
+        """
+        if isinstance(value, str):
+            self._Uri = value
+    
+
+    @property
+    def UriOrigin(self) -> str:
+        """ 
+        The origin Spotify URI for the track.
+        The `LinkedFrom.Uri` value is returned if present; 
+        otherwise, the `Uri` value is returned.
+
+        This is a helper property, and is not part of the Spotify Web API specification.
+        """
+        if (self.IsLinkedFrom):
+            return self._LinkedFrom.Uri
+        return self._Uri
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        externalUrls:dict = {}
+        if self._ExternalUrls is not None:
+            externalUrls = self._ExternalUrls.ToDictionary()
+
+        linked_from:dict = {}
+        if self._LinkedFrom is not None:
+            linked_from = self._LinkedFrom.ToDictionary()
+
+        result:dict = \
+        {
+            'external_urls': externalUrls,
+            'href': self._Href,
+            'id': self._Id,
+            'image_url': self.ImageUrl,
+            'images': [ item.ToDictionary() for item in self._Images ],
+            'is_linked_from': self.IsLinkedFrom,
+            'name': self._Name,
+            'type': self._Type,
+            'uri': self._Uri,
+            'linked_from': linked_from,
+            'id_origin': self.IdOrigin,
+            'uri_origin': self.UriOrigin,
+        }
+        return result
+        
+
+    def ToString(self, includeTitle:bool=True) -> str:
+        """
+        Returns a displayable string representation of the class.
+        
+        Args:
+            includeTitle (str):
+                True to include the class name title prefix.
+        """
+        msg:str = ''
+        if includeTitle: 
+            msg = 'SearchResultBase:'
+        
+        if self._Name is not None: msg = '%s\n Name="%s"' % (msg, str(self._Name))
+        if self._Href is not None: msg = '%s\n Href="%s"' % (msg, str(self._Href))
+        if self._Id is not None: msg = '%s\n Id="%s"' % (msg, str(self._Id))
+        if self.IdOrigin is not None: msg = '%s\n IdOrigin="%s"' % (msg, str(self.IdOrigin))
+        if self._Images is not None: msg = '%s\n Images Count=%s' % (msg, str(len(self._Images)))
+        if self._Type is not None: msg = '%s\n Type="%s"' % (msg, str(self._Type))
+        if self._Uri is not None: msg = '%s\n Uri="%s"' % (msg, str(self._Uri))
+        if self.UriOrigin is not None: msg = '%s\n UriOrigin="%s"' % (msg, str(self.UriOrigin))
+        if self._LinkedFrom is not None: msg = '%s\n LinkedFrom: %s' % (msg, self._LinkedFrom.ToString(False))
+        return msg 

spotifywebapipython/models/show.py

@@ -0,0 +1,87 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .showsimplified import ShowSimplified
+from .episodepagesimplified import EpisodePageSimplified
+
+@export
+class Show(ShowSimplified):
+    """
+    Spotify Web API Show 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._Episodes:EpisodePageSimplified = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            # process all collections and objects.
+            item:dict = root.get('episodes',None)
+            if item is not None:
+                self._Episodes = EpisodePageSimplified(root=item)
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Episodes(self) -> EpisodePageSimplified:
+        """ 
+        The episodes of the show.
+        
+        This is a `EpisodePageSimplified` object.
+        """
+        return self._Episodes
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        # get base class result.
+        resultBase:dict = super().ToDictionary()
+
+        episodes:dict = {}
+        if self._Episodes is not None:
+            episodes = self._Episodes.ToDictionary()
+
+        result:dict = \
+        {
+            'episodes': episodes
+        }
+        
+        # combine base class results with these results.
+        resultBase.update(result)
+        
+        # return an unsorted dictionary.
+        return resultBase
+        
+
+    def ToString(self) -> str:
+        """
+        Returns a displayable string representation of the class.
+        """
+        msg:str = 'Show: %s' % super().ToString(False)
+        if self._Episodes is not None: msg = '%s\n Episode Count=%s' % (msg, str(self._Episodes.Total))
+        return msg 

spotifywebapipython/models/showpagesaved.py

@@ -0,0 +1,85 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .show import Show
+from .showsaved import ShowSaved
+from .pageobject import PageObject
+
+@export
+class ShowPageSaved(PageObject):
+    """
+    Spotify Web API ShowPageSaved object.
+    
+    This allows for multiple pages of `ShowSaved` 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[ShowSaved] = []
+        
+        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(ShowSaved(root=item))
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Items(self) -> list[ShowSaved]:
+        """ 
+        Array of `ShowSaved` objects.
+        """
+        return self._Items
+    
+
+    def GetShows(self) -> list[Show]:
+        """ 
+        Gets a list of all shows contained in the underlying `Items` list.
+        
+        This is a convenience method so one does not have to loop through the `Items`
+        array of ShowSaved objects to get the list of shows.
+        """
+        result:list[Show] = []
+        item:ShowSaved
+        for item in self._Items:
+            result.append(item.Show)
+        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 'ShowPageSaved: %s' % super().ToString(includeItems)

spotifywebapipython/models/showpagesimplified.py

@@ -0,0 +1,88 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .showsimplified import ShowSimplified
+from .pageobject import PageObject
+
+@export
+class ShowPageSimplified(PageObject):
+    """
+    Spotify Web API SimplifiedShowPage object.
+    
+    This allows for multiple pages of `ShowSimplified` 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[ShowSimplified] = []
+        
+        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(ShowSimplified(root=item))
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Items(self) -> list[ShowSimplified]:
+        """ 
+        Array of `ShowSimplified` objects.
+        """
+        return self._Items
+    
+
+    def ContainsId(self, itemId:str=False) -> bool:
+        """
+        Checks the `Items` collection to see if an item already exists with the
+        specified Id value.
+        
+        Returns True if the itemId exists in the collection; otherwise, False.
+        """
+        result:bool = False
+        
+        item:ShowSimplified
+        for item in self._Items:
+            if item.Id == itemId:
+                result = True
+                break
+            
+        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 'ShowPageSimplified: %s' % super().ToString(includeItems)

spotifywebapipython/models/showsaved.py

@@ -0,0 +1,99 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .showsimplified import ShowSimplified
+
+@export
+class ShowSaved:
+    """
+    Spotify Web API SavedShow 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.
+        """
+        self._Show:ShowSimplified = None
+        self._AddedAt:str = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._AddedAt = root.get('added_at', None)
+
+            # process all collections and objects.
+            item:dict = root.get('show',None)
+            if item is not None:
+                self._Show = ShowSimplified(root=item)
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def AddedAt(self) -> str:
+        """ 
+        The date and time the show was saved. 
+        
+        Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero 
+        offset: YYYY-MM-DDTHH:MM:SSZ. If the time is imprecise (for example, the date/time of an 
+        episode release), an additional field indicates the precision; see for example, release_date 
+        in an episode object.
+        """
+        return self._AddedAt
+
+
+    @property
+    def Show(self) -> ShowSimplified:
+        """ 
+        Information about the show.
+        """
+        return self._Show
+    
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        show:dict = {}
+        if self._Show is not None:
+            show = self._Show.ToDictionary()
+
+        result:dict = \
+        {
+            'added_at': self._AddedAt,
+            'show': show
+        }
+        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 = 'ShowSaved:'
+        if self._AddedAt is not None: msg = '%s\n AddedAt="%s"' % (msg, str(self._AddedAt))
+        
+        if (includeItems):
+            if self._Show is not None: msg = '%s\n %s' % (msg, str(self._Show))
+            
+        return msg