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

spotifywebapipython/models/artistinfo.py

@@ -0,0 +1,282 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .artistinfotourevent import ArtistInfoTourEvent
+
+@export
+class ArtistInfo:
+    """
+    Artist Information About object.
+    """
+
+    def __init__(self, id:str, name:str, typeValue:str, uri:str, imageUrlDefault:str) -> None:
+        """
+        Initializes a new instance of the class.
+        
+        Args:
+            id (str):
+                The Spotify ID for the artist.
+            name (str):
+                The name of the artist.
+            typeValue (str):
+                The object type.
+            uri (str):
+                The Spotify URI for the artist.
+            imageUrlDefault (str):
+                Image url of the artist, if defined
+        """
+        self._AboutUrlFacebook:str = None
+        self._AboutUrlInstagram:str = None
+        self._AboutUrlTwitter:str = None
+        self._AboutUrlWikipedia:str = None
+        self._Bio:str = None
+        self._BioHtml:str = None
+        self._Id:int = id
+        self._ImageUrl:str = None
+        self._ImageUrlDefault:str = imageUrlDefault
+        self._MonthlyListeners:int = None
+        self._Name:str = name
+        self._TourEvents:list[ArtistInfoTourEvent] = []
+        self._Type:str = typeValue
+        self._Uri:str = uri
+        
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def AboutUrlFacebook(self) -> str:
+        """ 
+        URL link to artist Facebook page, if supplied; otherwise, null.
+        """
+        return self._AboutUrlFacebook
+    
+    @AboutUrlFacebook.setter
+    def AboutUrlFacebook(self, value:str):
+        """ 
+        Sets the AboutUrlFacebook property value.
+        """
+        if isinstance(value, str):
+            self._AboutUrlFacebook = value
+
+
+    @property
+    def AboutUrlInstagram(self) -> str:
+        """ 
+        URL link to artist Instagram page, if supplied; otherwise, null.
+        """
+        return self._AboutUrlInstagram
+    
+    @AboutUrlInstagram.setter
+    def AboutUrlInstagram(self, value:str):
+        """ 
+        Sets the AboutUrlInstagram property value.
+        """
+        if isinstance(value, str):
+            self._AboutUrlInstagram = value
+
+
+    @property
+    def AboutUrlTwitter(self) -> str:
+        """ 
+        URL link to artist Twitter page, if supplied; otherwise, null.
+        """
+        return self._AboutUrlTwitter
+    
+    @AboutUrlTwitter.setter
+    def AboutUrlTwitter(self, value:str):
+        """ 
+        Sets the AboutUrlTwitter property value.
+        """
+        if isinstance(value, str):
+            self._AboutUrlTwitter = value
+
+
+    @property
+    def AboutUrlWikipedia(self) -> str:
+        """ 
+        URL link to artist Wikipedia page, if supplied; otherwise, null.
+        """
+        return self._AboutUrlWikipedia
+    
+    @AboutUrlWikipedia.setter
+    def AboutUrlWikipedia(self, value:str):
+        """ 
+        Sets the AboutUrlWikipedia property value.
+        """
+        if isinstance(value, str):
+            self._AboutUrlWikipedia = value
+
+
+    @property
+    def Bio(self) -> str:
+        """ 
+        Biography text, in plain-text format.
+        """
+        return self._Bio
+    
+    @Bio.setter
+    def Bio(self, value:str):
+        """ 
+        Sets the Bio property value.
+        """
+        if isinstance(value, str):
+            self._Bio = value
+
+
+    @property
+    def BioHtml(self) -> str:
+        """ 
+        Biography text, in html format.
+        """
+        return self._BioHtml
+    
+    @BioHtml.setter
+    def BioHtml(self, value:str):
+        """ 
+        Sets the BioHtml property value.
+        """
+        if isinstance(value, str):
+            self._BioHtml = value
+
+
+    @property
+    def Id(self) -> str:
+        """ 
+        The Spotify ID for the artist.
+        """
+        return self._Id
+
+
+    @property
+    def ImageUrl(self) -> str:
+        """ 
+        Image url of the artist, if defined; otheriwse, the `ImageUrlDefault` url value.
+        """
+        if (self._ImageUrl is not None) and (len(self._ImageUrl.strip()) > 0):
+            return self._ImageUrl
+        return self._ImageUrlDefault
+    
+    @ImageUrl.setter
+    def ImageUrl(self, value:str):
+        """ 
+        Sets the ImageUrl property value.
+        """
+        if isinstance(value, str):
+            self._ImageUrl = value
+
+
+    @property
+    def ImageUrlDefault(self) -> str:
+        """ 
+        Default Image url of the artist, if defined; otherwise, null.
+        """
+        return self._ImageUrlDefault
+    
+
+    @property
+    def MonthlyListeners(self) -> int:
+        """ 
+        Monthly Listeners text.
+        """
+        return self._MonthlyListeners
+    
+    @MonthlyListeners.setter
+    def MonthlyListeners(self, value:int):
+        """ 
+        Sets the MonthlyListeners property value.
+        """
+        if isinstance(value, int):
+            self._MonthlyListeners = value
+
+
+    @property
+    def Name(self) -> str:
+        """ 
+        The name of the artist.
+        """
+        return self._Name
+
+
+    @property
+    def TourEvents(self) -> list[ArtistInfoTourEvent]:
+        """ 
+        An array of `ArtistInfoTourEvent` objects, if the artist has any upcoming tour
+        dates on file; otherwise, an empty list.
+        """
+        return self._TourEvents
+    
+
+    @property
+    def Type(self) -> str:
+        """ 
+        The object type: `artist`.
+        """
+        return self._Type
+
+
+    @property
+    def Uri(self) -> str:
+        """ 
+        The Spotify URI for the artist.
+        """
+        return self._Uri
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'about_url_facebook': self._AboutUrlFacebook,
+            'about_url_instagram': self._AboutUrlInstagram,
+            'about_url_twitter': self._AboutUrlTwitter,
+            'about_url_wikipedia': self._AboutUrlWikipedia,
+            'bio': self._Bio,
+            'bio_html': self._BioHtml,
+            'id': self._Id,
+            'image_url': self._ImageUrl,
+            'image_url_default': self._ImageUrlDefault,
+            'name': self._Name,
+            'monthly_listeners': self._MonthlyListeners,
+            'tour_events': [ item.ToDictionary() for item in self._TourEvents ],
+            'type': self._Type,
+            'uri': self._Uri,
+        }
+        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 = 'ArtistInfo:'
+        
+        if self._Name is not None: msg = '%s\n Name="%s"' % (msg, str(self._Name))
+        if self._Uri is not None: msg = '%s\n Uri="%s"' % (msg, str(self._Uri))
+        if self._AboutUrlFacebook is not None: msg = '%s\n AboutUrlFacebook="%s"' % (msg, str(self._AboutUrlFacebook))
+        if self._AboutUrlInstagram is not None: msg = '%s\n AboutUrlInstagram="%s"' % (msg, str(self._AboutUrlInstagram))
+        if self._AboutUrlTwitter is not None: msg = '%s\n AboutUrlTwitter="%s"' % (msg, str(self._AboutUrlTwitter))
+        if self._AboutUrlWikipedia is not None: msg = '%s\n AboutUrlWikipedia="%s"' % (msg, str(self._AboutUrlWikipedia))
+        if self._Bio is not None: msg = '%s\n Bio="%s"' % (msg, str(self._Bio))
+        if self._BioHtml is not None: msg = '%s\n BioHtml="%s"' % (msg, str(self._BioHtml))
+        if self._Id is not None: msg = '%s\n Id="%s"' % (msg, str(self._Id))
+        if self._ImageUrl is not None: msg = '%s\n ImageUrl="%s"' % (msg, str(self._ImageUrl))
+        if self._ImageUrlDefault is not None: msg = '%s\n ImageUrlDefault="%s"' % (msg, str(self._ImageUrlDefault))
+        if self._MonthlyListeners is not None: msg = '%s\n MonthlyListeners="%s"' % (msg, str(self._MonthlyListeners))
+        msg = '%s\n TourEvents Count="%d"' % (msg, len(self._TourEvents))
+        if self._Type is not None: msg = '%s\n Type="%s"' % (msg, str(self._Type))
+        return msg 

spotifywebapipython/models/artistinfotourevent.py

@@ -0,0 +1,127 @@
+# external package imports.
+from datetime import datetime
+
+# our package imports.
+from ..sautils import export
+
+@export
+class ArtistInfoTourEvent:
+    """
+    Artist Information Tour object.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initializes a new instance of the class.
+        """
+        self._EventDateTime:str = None
+        self._Href:str = None
+        self._Title:str = None
+        self._VenueName:str = None
+        
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def EventDateTime(self) -> datetime:
+        """ 
+        Date and time the tour event starts in the local timezone of the 
+        venue location, if supplied; otherwise, null.
+        """
+        return self._EventDateTime
+    
+    @EventDateTime.setter
+    def EventDateTime(self, value:datetime):
+        """ 
+        Sets the EventDateTime property value.
+        """
+        if value is None or isinstance(value, datetime):
+            self._EventDateTime = value
+
+
+    @property
+    def Href(self) -> str:
+        """ 
+        Link to the concert information, if supplied; otherwise, null.
+        """
+        return self._Href
+    
+    @Href.setter
+    def Href(self, value:str):
+        """ 
+        Sets the Href property value.
+        """
+        if isinstance(value, str):
+            self._Href = value
+
+
+    @property
+    def Title(self) -> str:
+        """ 
+        Title given to the event by the promoter, if supplied; otherwise, null.
+        """
+        return self._Title
+    
+    @Title.setter
+    def Title(self, value:str):
+        """ 
+        Sets the Title property value.
+        """
+        if isinstance(value, str):
+            self._Title = value
+
+
+    @property
+    def VenueName(self) -> str:
+        """ 
+        The venue name of where the event will take place, if supplied; otherwise, null.
+        """
+        return self._VenueName
+    
+    @VenueName.setter
+    def VenueName(self, value:str):
+        """ 
+        Sets the VenueName property value.
+        """
+        if isinstance(value, str):
+            self._VenueName = value
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'title': self._Title,
+            'venue_name': self._VenueName,
+            'href': self._Href,
+        }
+        if self._EventDateTime is not None:
+            result['event_datetime'] = self._EventDateTime.isoformat()
+        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 = 'ArtistInfoTourEvent:'
+        
+        if self._EventDateTime is not None: msg = '%s\n EventDateTime="%s"' % (msg, self._EventDateTime.isoformat())
+        if self._Title is not None: msg = '%s\n Title="%s"' % (msg, str(self._Title))
+        if self._VenueName is not None: msg = '%s\n VenueName="%s"' % (msg, str(self._VenueName))
+        if self._Href is not None: msg = '%s\n Href="%s"' % (msg, str(self._Href))
+        return msg 

spotifywebapipython/models/artistpage.py

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

spotifywebapipython/models/artistsimplified.py

@@ -90,6 +90,8 @@ class ArtistSimplified:
     def Id(self) -> str:
         """ 
         The Spotify ID for the artist.
+        
+        Example: `2CIMQHirSU0MQqyYHq0eOx`
         """
         return self._Id
 
@@ -114,6 +116,8 @@ class ArtistSimplified:
     def Uri(self) -> str:
         """ 
         The Spotify URI for the artist.
+        
+        Example: `spotify:artist:2CIMQHirSU0MQqyYHq0eOx`
         """
         return self._Uri
 

spotifywebapipython/models/audiobookpagesimplified.py

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

spotifywebapipython/models/audiobooksimplified.py

@@ -218,12 +218,10 @@ class AudiobookSimplified:
     @property
     def ImageUrl(self) -> str:
         """
-        Gets the first image url in the `Images` list, if images are defined;
-        otherwise, null.
+        Returns the highest resolution order image from the `Images` list, if images 
+        are defined; otherwise, null.
         """
-        if len(self._Images) > 0:
-            return self._Images[0].Url
-        return None
+        return ImageObject.GetImageHighestResolution(self._Images)
             
         
     @property
@@ -316,6 +314,7 @@ class AudiobookSimplified:
             'href': self._Href,
             'html_description': self._HtmlDescription,
             'id': self._Id,
+            'image_url': self.ImageUrl,
             'images': [ item.ToDictionary() for item in self._Images ],
             'languages': [ item for item in self._Languages ],
             'media_type': self._MediaType,

spotifywebapipython/models/category.py

@@ -115,6 +115,17 @@ class Category:
         return self._Name
 
 
+    @property
+    def Type(self) -> str:
+        """
+        A simulated Spotify type value for the category.
+        
+        This is a helper property - no value with this name is returned from the
+        Spotify Web API.
+        """
+        return "category"
+
+
     @property
     def Uri(self) -> str:
         """
@@ -134,8 +145,11 @@ class Category:
         {
             'href': self._Href,
             'icons': [ item.ToDictionary() for item in self._Icons ],
+            'image_url': self.ImageUrl,
             'id': self._Id,
             'name': self._Name,
+            'type': self.Type,
+            'uri': self.Uri,
         }
         return result
         
@@ -149,4 +163,6 @@ class Category:
         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._Icons is not None: msg = '%s\n Icons Count=%s' % (msg, str(len(self._Icons)))
+        if self._Id is not None: msg = '%s\n Type="%s"' % (msg, str(self.Type))
+        if self._Id is not None: msg = '%s\n Uri="%s"' % (msg, str(self.Uri))
         return msg

spotifywebapipython/models/categorypage.py

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

spotifywebapipython/models/chapterpagesimplified.py

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

spotifywebapipython/models/chaptersimplified.py

@@ -138,7 +138,7 @@ class ChapterSimplified:
     @property
     def ChapterNumber(self) -> int:
         """ 
-        The number of the chapter
+        The number of the chapter.
 
         Example: `1`
         """
@@ -176,7 +176,7 @@ class ChapterSimplified:
     @property
     def ExternalUrls(self) -> ExternalUrls:
         """ 
-        Known external URLs for the album.
+        Known external URLs for the chapter.
         """
         return self._ExternalUrls
     
@@ -220,12 +220,10 @@ class ChapterSimplified:
     @property
     def ImageUrl(self) -> str:
         """
-        Gets the first image url in the `Images` list, if images are defined;
-        otherwise, null.
+        Returns the highest resolution order image from the `Images` list, if images 
+        are defined; otherwise, null.
         """
-        if len(self._Images) > 0:
-            return self._Images[0].Url
-        return None
+        return ImageObject.GetImageHighestResolution(self._Images)
             
         
     @property
@@ -339,6 +337,7 @@ class ChapterSimplified:
             'href': self._Href,
             'html_description': self._HtmlDescription,
             'id': self._Id,
+            'image_url': self.ImageUrl,
             'images': [ item.ToDictionary() for item in self._Images ],
             'is_playable': self._IsPlayable,
             'languages': [ item for item in self._Languages ],

spotifywebapipython/models/context.py

@@ -60,7 +60,7 @@ class Context:
     @property
     def Href(self) -> str:
         """ 
-        A link to the Web API endpoint providing full details of the track.
+        A link to the Web API endpoint providing full details of the context.
         """
         return self._Href
 
@@ -69,8 +69,6 @@ class Context:
     def Type(self) -> str:
         """ 
         Object type, such as `artist`, `playlist`, `album` or `show`.
-        
-        Example: `computer`
         """
         return self._Type