spotifywebapiPython 1.0.242__py3-none-any.whl

spotifywebapipython/models/copyright.py

@@ -0,0 +1,79 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+
+@export
+class Copyright:
+    """
+    Spotify Web API Content Copyright object.
+    
+    Contains information about content copyrights.
+    """
+
+    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._Text:str = None
+        self._Type:str = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._Text = root.get('text', None)
+            self._Type = root.get('type', None)
+
+
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Text(self) -> str:
+        """ 
+        The copyright text for this content.
+        """
+        return self._Text
+    
+
+    @property
+    def Type(self) -> str:
+        """ 
+        The type of copyright: C = the copyright, P = the sound recording (performance) copyright.
+        """
+        return self._Type
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'text': self._Text,
+            'type': self._Type
+        }
+        return result
+        
+
+    def ToString(self) -> str:
+        """
+        Returns a displayable string representation of the class.
+        """
+        msg:str = 'Copyright:'
+        if self._Type is not None: msg = '%s\n Type="%s"' % (msg, str(self._Type))
+        if self._Text is not None: msg = '%s\n Text="%s"' % (msg, str(self._Text))
+        return msg 

spotifywebapipython/models/device.py

@@ -0,0 +1,301 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+
+@export
+class Device:
+    """
+    Spotify Web API Device 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 storage.
+        self._Id:str = None
+        self._IsActive:bool = None
+        self._IsPrivateSession:bool = None
+        self._IsRestricted:bool = None
+        self._Name:str = None
+        self._SupportsVolume:bool = None
+        self._Type:str = None
+        self._VolumePercent:int = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._Id = root.get('id', None)
+            self._IsActive = root.get('is_active', None)
+            self._IsPrivateSession = root.get('is_private_session', None)
+            self._IsRestricted = root.get('is_restricted', None)
+            self._Name = root.get('name', None)
+            self._SupportsVolume = root.get('supports_volume', None)
+            self._Type = root.get('type', None)
+            self._VolumePercent = root.get('volume_percent', None)
+
+        # post load validations.
+        if self._IsActive is None:
+            self._IsActive = False
+        if self._IsPrivateSession is None:
+            self._IsPrivateSession = False
+        if self._IsRestricted is None:
+            self._IsRestricted = False
+        if self._SupportsVolume is None:
+            self._SupportsVolume = False
+        if self._VolumePercent is None:
+            self._VolumePercent = 0
+
+
+    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 as ex:
+            if (isinstance(self, Device )) and (isinstance(other, Device )):
+                return self.Name == other.Name
+            return False
+
+    def __lt__(self, other):
+        try:
+            return self.Name < other.Name
+        except Exception as ex:
+            if (isinstance(self, Device )) and (isinstance(other, Device )):
+                return self.Name < other.Name
+            return False
+
+
+    @property
+    def Id(self) -> str:
+        """ 
+        The device ID.  
+        
+        This ID is unique and persistent to some extent. However, this is not guaranteed 
+        and any cached device_id should periodically be cleared out and refetched as necessary.
+        """
+        return self._Id
+
+    @Id.setter
+    def Id(self, value:str):
+        """ 
+        Sets the Id property value.
+        """
+        if isinstance(value, str):
+            self._Id = value
+
+
+    @property
+    def IsActive(self) -> bool:
+        """ 
+        If this device is the currently active device.
+        """
+        return self._IsActive
+
+    @IsActive.setter
+    def IsActive(self, value:bool):
+        """ 
+        Sets the IsActive property value.
+        """
+        if isinstance(value, bool):
+            self._IsActive = value
+
+
+    @property
+    def IsMuted(self) -> bool:
+        """ 
+        True if the player device volume is zero (muted); 
+        otherwise, false.
+        """
+        return (self._VolumePercent == 0)
+
+
+    @property
+    def IsPrivateSession(self) -> bool:
+        """ 
+        If this device is currently in a private session.
+        """
+        return self._IsPrivateSession
+
+
+    @property
+    def IsRestricted(self) -> bool:
+        """ 
+        Whether controlling this device is restricted.  
+        
+        At present if this is "true" then no Web API commands will be accepted by this device.
+        """
+        return self._IsRestricted
+
+
+    @property
+    def Name(self) -> str:
+        """ 
+        A human-readable name for the device. 
+        
+        Some devices have a name that the user can configure (e.g. "Loudest speaker") and some 
+        devices have a generic name associated with the manufacturer or device model.
+        
+        Example: `Kitchen speaker`
+        """
+        return self._Name
+
+    @Name.setter
+    def Name(self, value:str):
+        """ 
+        Sets the Name property value.
+        """
+        if isinstance(value, str):
+            self._Name = value
+
+
+    @property
+    def SelectItemNameAndId(self) -> str:
+        """
+        Returns a string that can be used in a selection list in the
+        form of "Name (Id)".
+        
+        This is a helper property, and not part of the Spotify Web API interface.
+        """
+        return "%s (%s)" % (self.Name, self.Id)
+        
+
+    @property
+    def SupportsVolume(self) -> bool:
+        """ 
+        If this device can be used to set the volume.
+        """
+        return self._SupportsVolume
+
+
+    @property
+    def Type(self) -> str:
+        """ 
+        Device type, such as `computer`, `smartphone` or `speaker`.
+        
+        Example: `computer`
+        """
+        return self._Type
+
+    @Type.setter
+    def Type(self, value:str):
+        """ 
+        Sets the Type property value.
+        """
+        if isinstance(value, str):
+            self._Type = value
+
+
+    @property
+    def VolumePercent(self) -> int:
+        """ 
+        The current volume in percent.
+        
+        Range: `0 - 100`
+        Example: `59`
+        """
+        return self._VolumePercent
+
+    @VolumePercent.setter
+    def VolumePercent(self, value:int):
+        """ 
+        Sets the VolumePercent property value.
+        """
+        if isinstance(value, int):
+            self._VolumePercent = value
+
+
+    @staticmethod
+    def GetIdFromSelectItem(value:str) -> str:
+        """
+        Returns the Id portion of a `SelectItemNameAndId` property value.
+        
+        Args:
+            value (str):
+                A `SelectItemNameAndId` property value.
+                
+        Returns:
+            The Id portion of a `SelectItemNameAndId` property value, or None
+            if the Id portion could not be determined.
+        """
+        result:str = None
+        if isinstance(value, str):
+            idx:int = value.rfind("(")
+            if idx > -1:
+                result = value[idx+1:len(value)-1]  # drop the "(" and ")"
+        return result
+        
+
+    @staticmethod
+    def GetNameFromSelectItem(value:str) -> str:
+        """
+        Returns the Name portion of a `SelectItemNameAndId` property value.
+        
+        Args:
+            value (str):
+                A `SelectItemNameAndId` property value.
+                
+        Returns:
+            The Name portion of a `SelectItemNameAndId` property value, or None
+            if the Name portion could not be determined.
+        """
+        result:str = None
+        if isinstance(value, str):
+            idx:int = value.rfind("(")
+            if idx > -1:
+                result = value[:idx-1]
+        return result
+        
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        result:dict = \
+        {
+            'id': self._Id,
+            'is_active': self._IsActive,
+            'is_private_session': self._IsPrivateSession,
+            'is_restricted': self._IsRestricted,
+            'name': self._Name,
+            'supports_volume': self._SupportsVolume,
+            'type': self._Type,
+            'volume_percent': self._VolumePercent,
+            # helper property(s), not part of the Spotify Web API interface:
+            'is_muted': self.IsMuted,
+            'select_item_name_and_id': self.SelectItemNameAndId,
+        }
+        return result
+        
+
+    def ToString(self) -> str:
+        """
+        Returns a displayable string representation of the class.
+        """
+        msg:str = 'Device:'
+        if self._Id is not None: msg = '%s\n Id="%s"' % (msg, str(self._Id))
+        if self._IsActive is not None: msg = '%s\n IsActive="%s"' % (msg, str(self._IsActive))
+        if self.IsMuted is not None: msg = '%s\n IsMuted="%s"' % (msg, str(self.IsMuted))
+        if self._IsPrivateSession is not None: msg = '%s\n IsPrivateSession="%s"' % (msg, str(self._IsPrivateSession))
+        if self._IsRestricted is not None: msg = '%s\n IsRestricted="%s"' % (msg, str(self._IsRestricted))
+        if self._Name is not None: msg = '%s\n Name="%s"' % (msg, str(self._Name))
+        if self._SupportsVolume is not None: msg = '%s\n SupportsVolume="%s"' % (msg, str(self._SupportsVolume))
+        if self._Type is not None: msg = '%s\n Type="%s"' % (msg, str(self._Type))
+        if self._VolumePercent is not None: msg = '%s\n VolumePercent="%s"' % (msg, str(self._VolumePercent))
+        return msg 

spotifywebapipython/models/episode.py

@@ -0,0 +1,84 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .episodesimplified import EpisodeSimplified
+from .showsimplified import ShowSimplified
+
+@export
+class Episode(EpisodeSimplified):
+    """
+    Spotify Web API Episode 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._Show:ShowSimplified = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            # 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 Show(self) -> ShowSimplified:
+        """ 
+        The show on which the episode belongs.
+        
+        This is a `ShowSimplified` object.
+        """
+        return self._Show
+
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        # get base class result.
+        resultBase:dict = super().ToDictionary()
+
+        result:dict = \
+        {
+            'show': self._Show.ToDictionary(),
+        }
+        
+        # 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 = 'Episode: %s' % super().ToString(False)
+        if self._Show is not None: msg = '%s\n Show Name="%s"' % (msg, str(self._Show.Name))
+        return msg
+

spotifywebapipython/models/episodepagesaved.py

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

spotifywebapipython/models/episodepagesimplified.py

@@ -0,0 +1,88 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .episodesimplified import EpisodeSimplified
+from .pageobject import PageObject
+
+@export
+class EpisodePageSimplified(PageObject):
+    """
+    Spotify Web API SimplifiedEpisodePage object.
+    
+    This allows for multiple pages of `EpisodeSimplified` 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[EpisodeSimplified] = []
+        
+        if (root is None):
+
+            self._Total = 0
+        
+        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(EpisodeSimplified(root=item))
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Items(self) -> list[EpisodeSimplified]:
+        """ 
+        Array of `EpisodeSimplified` 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:EpisodeSimplified
+        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 'EpisodePageSimplified: %s' % super().ToString(includeItems)