spotifywebapiPython 1.0.242__py3-none-any.whl

spotifywebapipython/models/playhistory.py

@@ -0,0 +1,136 @@
+# external package imports.
+from datetime import datetime
+
+# our package imports.
+from ..sautils import export
+from .context import Context
+from .track import Track
+
+@export
+class PlayHistory:
+    """
+    Spotify Web API PlayHistory 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._Context:Context = None
+        self._PlayedAt:str = None
+        self._PlayedAtMS:int = None
+        self._Track:Track = None
+        
+        if (root is None):
+
+            pass
+        
+        else:
+
+            self._PlayedAt = root.get('played_at', None)
+
+            # process all collections and objects.
+            item:dict = root.get('context',None)
+            if item is not None:
+                self._Context = Context(root=item)
+
+            item:dict = root.get('track',None)
+            if item is not None:
+                self._Track = Track(root=item)
+
+        # convert played at local datetime to unix milliseconds timestamp.
+        if self._PlayedAt is not None:
+            dtLocalIso:str = self._PlayedAt.replace('Z','+00:00')
+            dtLocal:str = datetime.fromisoformat(dtLocalIso)
+            dtLocalUnixTS:float = dtLocal.timestamp()
+            self._PlayedAtMS = int(dtLocalUnixTS * 1000)
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def PlayedAt(self) -> str:
+        """ 
+        The date and time the track was played (in local time).
+        
+        Example: `2024-01-25T15:33:17.136Z`
+        """
+        return self._PlayedAt
+
+
+    @property
+    def PlayedAtMS(self) -> int:
+        """ 
+        The `PlayedAt` value in Unix millisecond timestamp format, or null if the `PlayedAt` value is null.
+        
+        Example: `1706213826000`
+        """
+        return self._PlayedAtMS
+
+
+    @property
+    def Context(self) -> Context:
+        """ 
+        The context the track was played from.
+        """
+        return self._Context
+
+
+    @property
+    def Track(self) -> Track:
+        """ 
+        The track the user listened to.
+        """
+        return self._Track
+    
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        context:dict = {}
+        if self._Context is not None:
+            context = self._Context.ToDictionary()
+            
+        track:dict = {}
+        if self._Track is not None:
+            track = self._Track.ToDictionary()
+            
+        result:dict = \
+        {
+            'context': context,
+            'played_at': self._PlayedAt,
+            'played_at_ms': self._PlayedAtMS,
+            'track': track,
+        }
+        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 = 'PlayHistory:'
+        if self._PlayedAt is not None: msg = '%s\n PlayedAt="%s"' % (msg, str(self._PlayedAt))
+        if self._Context is not None: msg = '%s\n Context="%s"' % (msg, str(self._Context.Uri))
+        
+        if (includeItems):
+            if self._Track is not None: msg = '%s\n %s' % (msg, str(self._Track))
+            
+        return msg 

spotifywebapipython/models/playhistorypage.py

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

spotifywebapipython/models/playlist.py

@@ -0,0 +1,125 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .followers import Followers
+from .playlistpage import PlaylistPage
+from .playlistsimplified import PlaylistSimplified
+from .track import Track
+
+@export
+class Playlist(PlaylistSimplified):
+    """
+    Spotify Web API Playlist 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)
+
+        # initialize storage.
+        self._Followers:Followers = None
+        self._Tracks:PlaylistPage = None
+
+        if (root is None):
+
+            # if not building the class from json response, then initialize various properties as 
+            # the playlist is probably being built manually.
+            self._Followers = Followers()
+            self._Tracks = PlaylistPage()
+        
+        else:
+
+            # process all collections and objects.
+            item:dict = root.get('followers',None)
+            if item is not None:
+                self._Followers = Followers(root=item)
+        
+            item:dict = root.get('tracks',None)
+            if item is not None:
+                self._Tracks = PlaylistPage(root=item)
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Followers(self) -> Followers:
+        """ 
+        Information about the followers of the playlist.
+        """
+        return self._Followers
+
+
+    @property
+    def Tracks(self) -> PlaylistPage:
+        """ 
+        The tracks of the playlist.
+        
+        This is a `PlaylistPage` object, meaning only 50 tracks max are listed per request.
+        """
+        return self._Tracks
+
+
+    def GetTracks(self) -> list[Track]:
+        """ 
+        Gets a list of all tracks contained in the underlying `Tracks.Items` list.
+        
+        This is a convenience method so one does not have to loop through the `Tracks.Items`
+        array of PlaylistPage objects to get the list of tracks.
+        """
+        result:list[Track] = []
+        if self._Tracks is not None:
+            result = self._Tracks.GetTracks()
+        return result
+    
+
+    def ToDictionary(self) -> dict:
+        """
+        Returns a dictionary representation of the class.
+        """
+        # get base class result.
+        resultBase:dict = super().ToDictionary()
+
+        followers:dict = {}
+        if self._Followers is not None:
+            followers = self._Followers.ToDictionary()
+
+        tracks:dict = {}
+        if self._Tracks is not None:
+            tracks = self._Tracks.ToDictionary()
+
+        result:dict = \
+        {
+            'tracks': tracks,
+            'followers': followers
+        }
+        
+        # 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 = 'Playlist: %s' % super().ToString(False)
+        #if self._Followers is not None: msg = '%s\n %s' % (msg, str(self._Followers))
+        if self._Tracks is not None: msg = '%s\n Tracks Count=%s' % (msg, str(self._Tracks.Total))
+        return msg 

spotifywebapipython/models/playlistpage.py

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

spotifywebapipython/models/playlistpagesimplified.py

@@ -0,0 +1,107 @@
+# external package imports.
+
+# our package imports.
+from ..sautils import export
+from .pageobject import PageObject
+from .playlistsimplified import PlaylistSimplified
+
+@export
+class PlaylistPageSimplified(PageObject):
+    """
+    Spotify Web API PlaylistPageSimplified object.
+    
+    This allows for multiple pages of `PlaylistSimplified` 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[PlaylistSimplified] = []
+        
+        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(PlaylistSimplified(root=item))
+
+        
+    def __repr__(self) -> str:
+        return self.ToString()
+
+
+    def __str__(self) -> str:
+        return self.ToString()
+
+
+    @property
+    def Items(self) -> list[PlaylistSimplified]:
+        """ 
+        Array of `PlaylistSimplified` 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:PlaylistSimplified
+        for item in self._Items:
+            if item.Id == itemId:
+                result = True
+                break
+            
+        return result
+        
+
+    def GetSpotifyOwnedItems(self) -> list[PlaylistSimplified]:
+        """ 
+        Gets a list of all items contained in the `Items` list that are owned 
+        by `spotify:user:spotify`.
+        """
+        result:list[PlaylistSimplified] = []
+        item:PlaylistSimplified
+        for item in self._Items:
+            if item.Owner is not None:
+                if item.Owner.Uri == "spotify:user:spotify":
+                    result.append(item)
+
+        # sort items on Name property, ascending order.
+        if len(result) > 0:
+            result.sort(key=lambda x: (x.Name or "").lower(), reverse=False)
+
+        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 'PlaylistPageSimplified: %s' % super().ToString(includeItems)