spotifywebapiPython 1.0.242__py3-none-any.whl

spotifywebapipython/models/tracksimplified.py

@@ -0,0 +1,398 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .artistsimplified import ArtistSimplified
+from .externalurls import ExternalUrls
+from .linkedfrom import LinkedFrom
+from .restrictions import Restrictions
+
+@export
+class TrackSimplified:
+    """
+    Spotify Web API SimplifiedTrack 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._Artists:list[ArtistSimplified] = []
+        self._AvailableMarkets:list[str] = []
+        self._DiscNumber:int = None
+        self._DurationMS:int = None
+        self._Explicit:bool = None
+        self._ExternalUrls:ExternalUrls = None
+        self._Href:str = None
+        self._Id:int = None
+        self._IsLocal:bool = None
+        self._IsPlayable:bool = None
+        self._LinkedFrom:LinkedFrom = None
+        self._Name:str = None
+        self._PreviewUrl:str = None
+        self._Restrictions:Restrictions = None
+        self._TrackNumber:int = None
+        self._Type:str = None
+        self._Uri:str = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._AvailableMarkets = root.get('available_markets', None) or []
+            self._DiscNumber = root.get('disc_number', None)
+            self._DurationMS = root.get('duration_ms', None)
+            self._Explicit = root.get('explicit', None)
+            self._Href = root.get('href', None)
+            self._Id = root.get('id', None)
+            self._IsPlayable = root.get('is_playable', None)
+            self._IsLocal = root.get('is_local', None)
+            self._Name = root.get('name', None)
+            self._PreviewUrl = root.get('preview_url', None)
+            self._TrackNumber = root.get('track_number', None)
+            self._Type = root.get('type', None)
+            self._Uri = root.get('uri', None)
+
+            # process all collections and objects.
+            items:list = root.get('artists',None)
+            if items is not None:
+                for item in items:
+                    self._Artists.append(ArtistSimplified(root=item))
+        
+            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)
+
+            item:dict = root.get('restrictions',None)
+            if item is not None:
+                self._Restrictions = Restrictions(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, TrackSimplified )) and (isinstance(other, TrackSimplified )):
+                return self.Name == other.Name
+            return False
+
+    def __lt__(self, other):
+        try:
+            return self.Name < other.Name
+        except Exception:
+            if (isinstance(self, TrackSimplified )) and (isinstance(other, TrackSimplified )):
+                return self.Name < other.Name
+            return False
+
+
+    @property
+    def Artists(self) -> list[ArtistSimplified]:
+        """ 
+        A list of artists who performed the track. 
+        """
+        return self._Artists
+
+
+    @property
+    def AvailableMarkets(self) -> list[str]:
+        """ 
+        A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code.
+        """
+        return self._AvailableMarkets
+
+
+    @property
+    def DiscNumber(self) -> int:
+        """ 
+        The disc number (usually 1 unless the album consists of more than one disc).
+        """
+        return self._DiscNumber
+
+
+    @property
+    def DurationMS(self) -> int:
+        """ 
+        The track length in milliseconds.
+        """
+        return self._DurationMS
+
+
+    @property
+    def Explicit(self) -> bool:
+        """ 
+        Whether or not the track has explicit content (true = yes it does; false = no it does not OR unknown).
+        """
+        return self._Explicit
+
+
+    @property
+    def ExternalUrls(self) -> ExternalUrls:
+        """ 
+        Known external URLs for the track.
+        """
+        return self._ExternalUrls
+    
+
+    @property
+    def Href(self) -> str:
+        """ 
+        A link to the Web API endpoint providing full details of the track.
+        """
+        return self._Href
+
+
+    @property
+    def Id(self) -> str:
+        """ 
+        The Spotify ID for the track.
+        """
+        return self._Id
+
+
+    @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 ImageUrl(self) -> str:
+        """
+        Always returns null, as tracks currently do not support images.
+
+        Added for compatibility with other objects.
+        """
+        return None
+            
+        
+    @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 IsLocal(self) -> bool:
+        """ 
+        Whether or not the track is from a local file.
+        """
+        return self._IsLocal
+
+
+    @property
+    def IsPlayable(self) -> bool:
+        """ 
+        Part of the response when Track Relinking is applied.  
+        If true, the track is playable in the given market. Otherwise false.
+        """
+        return self._IsPlayable
+
+
+    @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 track.
+        """
+        return self._Name
+
+
+    @property
+    def Name(self) -> str:
+        """ 
+        The name of the track.
+        """
+        return self._Name
+
+
+    @property
+    def PreviewUrl(self) -> str:
+        """ 
+        <span class="deprecated">
+            DEPRECATED - property no longer supported by Spotify as of 2024/11/27.
+            More information about the deprecated functionality can be found on the 
+            <a href="https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api" target="_blank">Spotify Developer Forum Blog</a>
+            page.
+        </span>
+        
+        A link to a 30 second preview (MP3 format) of the track. Can be null.
+        
+        Important policy note:
+        - Spotify Audio preview clips can not be a standalone service.       
+        """
+        return self._PreviewUrl
+
+
+    @property
+    def Restrictions(self) -> Restrictions:
+        """ 
+        Included in the response when a content restriction is applied.
+        """
+        return self._Restrictions
+
+
+    @property
+    def TrackNumber(self) -> int:
+        """ 
+        The number of the track. 
+        
+        If an album has several discs, the track number is the number on the specified disc.
+        """
+        return self._TrackNumber
+
+
+    @property
+    def Type(self) -> str:
+        """ 
+        The object type: `track`.
+        """
+        return self._Type
+
+
+    @property
+    def Uri(self) -> str:
+        """ 
+        The Spotify URI for the track.
+        """
+        return self._Uri
+
+
+    @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()
+
+        restrictions:dict = {}
+        if self._Restrictions is not None:
+            restrictions = self._Restrictions.ToDictionary()
+
+        linked_from:dict = {}
+        if self._LinkedFrom is not None:
+            linked_from = self._LinkedFrom.ToDictionary()
+
+        result:dict = \
+        {
+            'artists': [ item.ToDictionary() for item in self._Artists ],
+            'available_markets': [ item for item in self._AvailableMarkets ],
+            'disc_number': self._DiscNumber,
+            'duration_ms': self._DurationMS,
+            'explicit': self._Explicit,
+            'external_urls': externalUrls,
+            'href': self._Href,
+            'id': self._Id,
+            'is_linked_from': self.IsLinkedFrom,
+            'is_local': self._IsLocal,
+            'is_playable': self._IsPlayable,
+            'name': self._Name,
+            'preview_url': self._PreviewUrl,
+            'restrictions': restrictions,
+            'track_number': self._TrackNumber,
+            '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 = 'TrackSimplified:'
+        
+        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._Artists is not None: 
+            cnt:int = len(self._Artists)
+            if cnt > 0: 
+                msg = '%s\n Artist="%s" (%s)' % (msg, str(self._Artists[0].Name), str(self._Artists[0].Id))
+            msg = '%s\n Artists Count=%s' % (msg, str(cnt))
+        if self._AvailableMarkets is not None: msg = '%s\n AvailableMarkets Count=%s' % (msg, str(len(self._AvailableMarkets)))
+        if self._DiscNumber is not None: msg = '%s\n DiscNumber="%s"' % (msg, str(self._DiscNumber))
+        if self._DurationMS is not None: msg = '%s\n DurationMS="%s"' % (msg, str(self._DurationMS))
+        if self._Explicit is not None: msg = '%s\n Explicit="%s"' % (msg, str(self._Explicit))
+        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._IsLocal is not None: msg = '%s\n IsLocal="%s"' % (msg, str(self._IsLocal))
+        if self._IsPlayable is not None: msg = '%s\n IsPlayable="%s"' % (msg, str(self._IsPlayable))
+        if self._PreviewUrl is not None: msg = '%s\n PreviewUrl="%s"' % (msg, str(self._PreviewUrl))
+        if self._TrackNumber is not None: msg = '%s\n TrackNumber="%s"' % (msg, str(self._TrackNumber))
+        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))
+        #if self._Restrictions is not None: msg = '%s\n %s' % (msg, str(self._Restrictions))
+        #if self._ExternalUrls is not None: msg = '%s\n %s' % (msg, str(self._ExternalUrls))
+        return msg 

spotifywebapipython/models/userprofile.py

@@ -0,0 +1,184 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .explicitcontent import ExplicitContent
+from .externalurls import ExternalUrls
+from .followers import Followers
+from .imageobject import ImageObject
+from .userprofilesimplified import UserProfileSimplified
+
+@export
+class UserProfile(UserProfileSimplified):
+    """
+    Spotify Web API User Profile object.
+    
+    Information about the user from their account profile.
+    """
+
+    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._Country:str = None
+        self._EMail:str = None
+        self._ExplicitContent:ExplicitContent = None
+        self._Product:str = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._Country = root.get('country', None)
+            self._EMail = root.get('email', None)
+            self._Product = root.get('product', None)
+
+            # process all collections and objects.
+            item:dict = root.get('explicit_content',None)
+            if item is not None:
+                self._ExplicitContent = ExplicitContent(root=item)
+
+        UNKNOWN:str = 'unknown'
+        
+        # post validations.
+        # this is done, as some authorization levels will not return some of these details;
+        # in this case, we will default the values to 'unknown'.
+        if self._EMail is None:
+            self._EMail = UNKNOWN
+        if self._Product is None:
+            self._Product = UNKNOWN
+
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Country(self) -> str:
+        """ 
+        The country of the user, as set in the user's account profile. 
+        
+        An ISO 3166-1 alpha-2 country code. 
+        
+        This field is only available when the current user has granted access to 
+        the `user-read-private` scope.
+        
+        Example: `US`
+        """
+        return self._Country
+
+
+    @property
+    def EMail(self) -> str:
+        """ 
+        The user's email address, as entered by the user when creating their account. 
+        Important! This email address is unverified; there is no proof that it actually 
+        belongs to the user. 
+        
+        This field is only available when the current user has granted access to 
+        the `user-read-email` scope.
+        
+        Example: `johnsmith@example.com`
+        """
+        return self._EMail
+
+
+    @property
+    def ExplicitContent(self) -> ExternalUrls:
+        """ 
+        The user's explicit content settings. 
+        
+        This field is only available when the current user has granted access to 
+        the `user-read-private` scope.
+        """
+        return self._ExplicitContent
+    
+
+    @property
+    def IsProductFree(self) -> str:
+        """ 
+        Returns true if the user's Spotify subscription level is `free` or `open`;
+        otherwise, False.
+        
+        This field is only valid when the current user has granted access to 
+        the `user-read-private` scope; otherwise, it is set to `unknown`.
+        """
+        return (self._Product == 'free') or (self._Product == 'opem')
+
+
+    @property
+    def IsProductPremium(self) -> bool:
+        """ 
+        Returns true if the user's Spotify subscription level is `premium`;
+        otherwise, False.
+        
+        This field is only valid when the current user has granted access to 
+        the `user-read-private` scope; otherwise, it is set to `unknown`.
+        """
+        return (self._Product == 'premium')
+
+
+    @property
+    def Product(self) -> bool:
+        """ 
+        The user's Spotify subscription level: `premium`, `free`, etc. 
+        
+        The subscription level `open` can be considered the same as `free`. 
+        
+        This field is only valid when the current user has granted access to 
+        the `user-read-private` scope; otherwise, it is set to `unknown`.
+        """
+        return self._Product
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        # get base class result.
+        resultBase:dict = super().ToDictionary()
+
+        explicitContent:dict = {}
+        if self._ExplicitContent is not None:
+            explicitContent = self._ExplicitContent.ToDictionary()
+
+        result:dict = \
+        {
+            'country': self._Country,
+            'email': self._EMail,
+            'explicitContent': explicitContent,
+            'product': self._Product,
+        }
+        
+        # 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 = 'UserProfile: %s' % super().ToString(False)
+        if self._Country is not None: msg = '%s\n Country="%s"' % (msg, str(self._Country))
+        if self._EMail is not None: msg = '%s\n EMail="%s"' % (msg, str(self._EMail))
+        #if self._ExplicitContent is not None: msg = '%s\n %s' % (msg, str(self._ExplicitContent))
+        if self._Product is not None: msg = '%s\n Product="%s"' % (msg, str(self._Product))
+        return msg