spotifywebapiPython 1.0.242__py3-none-any.whl

spotifywebapipython/models/externalurls.py

@@ -0,0 +1,104 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+
+@export
+class ExternalUrls:
+    """
+    Spotify Web API ExternalUrls object.
+    
+    Contains known external URLs for various object types: artist, track, etc.
+    """
+
+    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._Ean:str = None
+        self._Isrc:str = None
+        self._Spotify:str = None
+        self._Upc:str = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._Ean = root.get('ean', None)
+            self._Isrc = root.get('isrc', None)
+            self._Spotify = root.get('spotify', None)
+            self._Upc = root.get('upc', None)
+            
+            # TODO - test to see if anything other than 'spotify' is returned in this object
+            if self._Ean is not None or self._Isrc is not None or self._Upc is not None:
+                x:int = 0
+            
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Ean(self) -> str:
+        """ 
+        International Article Number.
+        """
+        return self._Ean
+    
+
+    @property
+    def Isrc(self) -> str:
+        """ 
+        International Standard Recording Code.
+        """
+        return self._Isrc
+    
+
+    @property
+    def Spotify(self) -> str:
+        """ 
+        The Spotify URL for the object.
+        """
+        return self._Spotify
+    
+
+    @property
+    def Upc(self) -> str:
+        """ 
+        Universal Product Code.
+        """
+        return self._Upc
+    
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'spotify': self._Spotify,
+        }
+        return result
+        
+
+    def ToString(self) -> str:
+        """
+        Returns a displayable string representation of the class.
+        """
+        msg:str = 'ExternalUrls:'
+        if self._Spotify is not None: msg = '%s\n Spotify="%s"' % (msg, str(self._Spotify))
+        if self._Ean is not None: msg = '%s\n Ean="%s"' % (msg, str(self._Ean))
+        if self._Isrc is not None: msg = '%s\n Isrc="%s"' % (msg, str(self._Isrc))
+        if self._Upc is not None: msg = '%s\n Upc="%s"' % (msg, str(self._Upc))
+        return msg 

spotifywebapipython/models/followers.py

@@ -0,0 +1,81 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+
+@export
+class Followers:
+    """
+    Spotify Web API Followers object.
+    
+    Contains information about the followers of an artist.
+    """
+
+    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._Href:str = None
+        self._Total:int = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._Href = root.get('href', None)
+            self._Total = root.get('total', None)
+
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Href(self) -> str:
+        """ 
+        This will always be set to null, as the Web API does not support it at the moment.
+        """
+        return self._Href
+    
+
+    @property
+    def Total(self) -> int:
+        """ 
+        The total number of followers.
+        
+        Example: `31288`
+        """
+        return self._Total
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'href': self._Href,
+            'total': self._Total,
+        }
+        return result
+        
+
+    def ToString(self) -> str:
+        """
+        Returns a displayable string representation of the class.
+        """
+        msg:str = 'Followers:'
+        if self._Total is not None: msg = '%s\n Total=%s' % (msg, str(self._Total))
+        if self._Href is not None: msg = '%s\n Href="%s"' % (msg, str(self._Href))
+        return msg 

spotifywebapipython/models/imageobject.py

@@ -0,0 +1,193 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+
+@export
+class ImageObject:
+    """
+    Spotify Web API Image 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._Height:int = None
+        self._Url:str = None
+        self._Width:int = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._Height = root.get('height', None)
+            self._Url = root.get('url', None)
+            self._Width = root.get('width', None)
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Height(self) -> int:
+        """ 
+        The image height in pixels.
+        
+        Example: `300`
+        """
+        return self._Height
+
+
+    @property
+    def Url(self) -> str:
+        """ 
+        The source URL of the image.
+        
+        Example: `https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228`
+        """
+        return self._Url
+    
+
+    @property
+    def Width(self) -> int:
+        """ 
+        The image width in pixels.
+        
+        Example: `300`
+        """
+        return self._Width
+
+
+    @staticmethod
+    def GetImageHighestResolution(
+            images:list,
+            desiredWidth:int=None,
+            ) -> str:
+        """
+        Returns the highest resolution order image from a list of `ImageObject` items.
+    
+        Args:
+            images (list[ImageObject]):
+                The cover art for the media in various sizes, usually widest first.
+            desiredWidth (int):
+                A desired resolution width to return (if found); if not found, then the
+                highest resolution is returned.
+
+        Returns:
+            The highest resolution order image from the list of `images`.
+    
+        The Spotify Web API normally returns a list of `ImageObject` items with the
+        highest resolution image as the first list item; however, the GetShowFavorites
+        returns them in the reverse order.
+        """
+        result:str = None
+        resultWidth:int = 0
+
+        if (images is not None) and (len(images) > 0):
+        
+            # set default image to return.
+            result = images[0].Url
+            resultWidth:int = (images[0].Width or 0)  # in case width is null
+            
+            # search for the highest resolution image and return it.
+            image: ImageObject
+            for image in images:
+
+                imageWidth:int = (image.Width or 0)   # in case width is null
+
+                # check for exact desired width match.
+                if (desiredWidth is not None) and (desiredWidth == imageWidth):
+                    result = image.Url
+                    resultWidth = imageWidth
+                    break
+
+                # check for largest resolution width match.
+                if (imageWidth > resultWidth):
+                    result = image.Url
+                    resultWidth = imageWidth
+        
+        return result
+    
+
+    @staticmethod
+    def GetImageHighestResolutionWidth(
+            images:list,
+            desiredWidth:int=None,
+            ) -> str:
+        """
+        Returns the highest resolution order image width from a list of `ImageObject` items.
+    
+        Args:
+            images (list[ImageObject]):
+                The cover art for the media in various sizes, usually widest first.
+            desiredWidth (int):
+                A desired resolution width to return (if found); if not found, then the
+                highest resolution is returned.
+
+        Returns:
+            The highest resolution order image width from the list of `images`.
+    
+        The Spotify Web API normally returns a list of `ImageObject` items with the
+        highest resolution image as the first list item; however, the GetShowFavorites
+        returns them in the reverse order.
+        """
+        resultWidth:int = 0
+
+        if (images is not None) and (len(images) > 0):
+        
+            # set default image width to return.
+            resultWidth:int = (images[0].Width or 0)  # in case width is null
+            
+            # search for the highest resolution image width and return it.
+            image: ImageObject
+            for image in images:
+
+                imageWidth:int = (image.Width or 0)   # in case width is null
+
+                # check for exact desired width match.
+                if (desiredWidth is not None) and (desiredWidth == imageWidth):
+                    resultWidth = imageWidth
+                    break
+
+                # check for largest resolution width match.
+                if (imageWidth > resultWidth):
+                    resultWidth = imageWidth
+        
+        return resultWidth
+    
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'url': self._Url,
+            'height': self._Height,
+            'width': self._Width,
+        }
+        return result
+        
+
+    def ToString(self) -> str:
+        """
+        Returns a displayable string representation of the class.
+        """
+        msg:str = 'ImageObject:'
+        if self._Width is not None: msg = '%s\n Width="%s"' % (msg, str(self._Width))
+        if self._Height is not None: msg = '%s\n Height="%s"' % (msg, str(self._Height))
+        if self._Url is not None: msg = '%s\n Url="%s"' % (msg, str(self._Url))
+        return msg 

spotifywebapipython/models/imagevibrantcolors.py

@@ -0,0 +1,182 @@
+# external package imports.
+from ..vibrant import Palette, Swatch
+
+# our package imports.
+from ..sautils import export
+
+@export
+class ImageVibrantColors:
+    """
+    Image Vibrant Colors object.
+    """
+
+    def __init__(self, root:Palette=None) -> None:
+        """
+        Initializes a new instance of the class.
+        
+        Args:
+            root (Palette):
+                Vibrant Palette object that contains extracted color information used to load object
+                attributes; otherwise, None to not load attributes.
+        """
+        self._EmptySwatch:Swatch = Swatch(rgb=[0,0,0], population=0, hsl=[0.0,0.0,0.0])
+
+        self._DarkMuted:Swatch = None
+        self._DarkVibrant:Swatch = None
+        self._LightMuted:Swatch = None
+        self._LightVibrant:Swatch = None
+        self._Muted:Swatch = None
+        self._Vibrant:Swatch = None
+
+        if (not isinstance(root, Palette)):
+
+            pass
+        
+        else:
+
+            # store vibrant color palette information.
+            self._DarkMuted = root.dark_muted
+            self._DarkVibrant = root.dark_vibrant
+            self._LightMuted = root.light_muted
+            self._LightVibrant = root.light_vibrant
+            self._Muted = root.muted
+            self._Vibrant = root.vibrant
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def DarkMuted(self) -> Swatch:
+        """ 
+        A dark but muted version of the color palette.  
+
+        This value represents a dark, muted color from the image, meaning the color is darker than
+        others in the image and has lower saturation. The resulting color is not vibrant or bright 
+        but still retains some of the overall mood or tone of the image.  
+
+        This value is typically used when you want a darker, less intense color that adds subtle depth 
+        to a design. It's great for backgrounds, sidebars, or any UI element where you want a muted, 
+        non-intrusive tone.  
+        """
+        return self._DarkMuted or self._EmptySwatch
+
+
+    @property
+    def DarkVibrant(self) -> Swatch:
+        """ 
+        A darker and vibrant version of the dominant color.  
+
+        This value represents a darker shade of the vibrant dominant color, retaining its saturation 
+        and richness.  It's typically used when you want to use a darker variant of the most dominant 
+        color in the image, but still with significant visual impact.  
+
+        This value is commonly used for prominent elements that need to stand out in a dark color 
+        palette, like header bars, call-to-action buttons, or elements that need to grab attention 
+        but in a muted, dark fashion.  
+        """
+        return self._DarkVibrant or self._EmptySwatch
+
+
+    @property
+    def LightMuted(self) -> Swatch:
+        """ 
+        A lighter but muted version of the color palette.  
+
+        This value represents a light color with low saturation. It's a softer and more desaturated 
+        version of the most prominent light color in the image.  
+
+        This value is great for when you need a color that won't draw too much attention but still 
+        provides a harmonious tone. It can be used for backgrounds, UI components, or designs that need 
+        to remain visually calm or neutral.  
+        """
+        return self._LightMuted or self._EmptySwatch
+
+
+    @property
+    def LightVibrant(self) -> Swatch:
+        """ 
+        A lighter and vibrant version of the dominant color.  
+
+        This value represents a light, saturated color that retains vibrancy. It's less dark than the 
+        darkVibrant swatch, but it maintains high saturation, making it stand out in designs that require 
+        a colorful but light tone.  
+
+        This value is typically used for elements that need to draw attention in a design without being 
+        overpowering. It's useful for buttons, highlights, or icons that need to stand out in a bright, 
+        colorful design while maintaining a softer appearance compared to darker vibrant tones.  
+        """
+        return self._LightVibrant or self._EmptySwatch
+
+
+    @property
+    def Muted(self) -> Swatch:
+        """ 
+        A color that is less saturated and has a softer tone.  
+
+        This value corresponds to a color that is desaturated or toned down. While it may be one of the 
+        prominent colors in the image, its saturation is significantly reduced, making it softer and more 
+        subtle compared to the vibrant color.  
+
+        This value is useful in situations where you want a color that's not overpowering but still retains 
+        visual presence. It works well for backgrounds, borders, or UI components that should be visible without 
+        grabbing too much attention.  
+        """
+        return self._Muted or self._EmptySwatch
+
+
+    @property
+    def Vibrant(self) -> Swatch:
+        """ 
+        The most dominant, bright, and saturated color in the image.  
+
+        This value corresponds to the most vibrant color from the image, meaning it's the most saturated and 
+        intense color found in the image. It's the color that grabs attention due to its brightness and boldness.  
+
+        This value is ideal for creating designs that need a bold, eye-catching focal point. It can be used for 
+        accent colors, calls to action (CTAs), buttons, and any design element where you want the color to stand 
+        out and be visually stimulating.  
+        """
+        return self._Vibrant or self._EmptySwatch
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'dark_muted': self.DarkMuted.ToDictionary(),
+            'dark_vibrant': self.DarkVibrant.ToDictionary(),
+            'light_muted': self.LightMuted.ToDictionary(),
+            'light_vibrant': self.LightVibrant.ToDictionary(),
+            'muted': self.Muted.ToDictionary(),
+            'vibrant': self.Vibrant.ToDictionary(),
+        }
+        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 = 'ImageVibrantColors:'
+        
+        msg = '%s\n DarkMuted: %s' % (msg, self.DarkMuted.ToString(False))
+        msg = '%s\n DarkVibrant: %s' % (msg, self.DarkVibrant.ToString(False))
+        msg = '%s\n LightMuted: %s' % (msg, self.LightMuted.ToString(False))
+        msg = '%s\n LightVibrant: %s' % (msg, self.LightVibrant.ToString(False))
+        msg = '%s\n Muted: %s' % (msg, self.Muted.ToString(False))
+        msg = '%s\n Vibrant: %s' % (msg, self.Vibrant.ToString(False))
+        return msg