Merge pull request #403 from zSeriesGuy/PlayHistory

Support history for specific ratingKeys

Author: Hellowlol

plexapi/base.py

@@ -421,6 +421,15 @@ def delete(self):
                 'havnt allowed items to be deleted' % self.key)
             raise
 
+    def history(self, maxresults=9999999, mindate=None):
+        """ Get Play History for a media item.
+            Parameters:
+                maxresults (int): Only return the specified number of results (optional).
+                mindate (datetime): Min datetime to return results from.
+        """
+        return self._server.history(maxresults=maxresults, mindate=mindate, ratingKey=self.ratingKey)
+
+
     # The photo tag cant be built atm. TODO
     # def arts(self):
     #     part = '%s/arts' % self.key

plexapi/library.py

@@ -294,6 +294,17 @@ def add(self, name='', type='', agent='', scanner='', location='', language='en'
             part += urlencode(kwargs)
         return self._server.query(part, method=self._server._session.post)
 
+    def history(self, maxresults=9999999, mindate=None):
+        """ Get Play History for all library Sections for the owner.
+            Parameters:
+                maxresults (int): Only return the specified number of results (optional).
+                mindate (datetime): Min datetime to return results from.
+        """
+        hist = []
+        for section in self.sections():
+            hist.extend(section.history(maxresults=maxresults, mindate=mindate))
+        return hist
+
 
 class LibrarySection(PlexObject):
     """ Base class for a single library section.
@@ -633,6 +644,14 @@ def sync(self, policy, mediaSettings, client=None, clientId=None, title=None, so
 
         return myplex.sync(client=client, clientId=clientId, sync_item=sync_item)
 
+    def history(self, maxresults=9999999, mindate=None):
+        """ Get Play History for this library Section for the owner.
+            Parameters:
+                maxresults (int): Only return the specified number of results (optional).
+                mindate (datetime): Min datetime to return results from.
+        """
+        return self._server.history(maxresults=maxresults, mindate=mindate, librarySectionID=self.key, accountID=1)
+
 
 class MovieSection(LibrarySection):
     """ Represents a :class:`~plexapi.library.LibrarySection` section containing movies.

plexapi/myplex.py

@@ -600,6 +600,19 @@ def claimToken(self):
             raise BadRequest('(%s) %s %s; %s' % (response.status_code, codename, response.url, errtext))
         return response.json()['token']
 
+    def history(self, maxresults=9999999, mindate=None):
+        """ Get Play History for all library sections on all servers for the owner.
+            Parameters:
+                maxresults (int): Only return the specified number of results (optional).
+                mindate (datetime): Min datetime to return results from.
+        """
+        servers = [x for x in self.resources() if x.provides == 'server' and x.owned]
+        hist = []
+        for server in servers:
+            conn = server.connect()
+            hist.extend(conn.history(maxresults=maxresults, mindate=mindate, accountID=1))
+        return hist
+
 
 class MyPlexUser(PlexObject):
     """ This object represents non-signed in users such as friends and linked
@@ -654,6 +667,8 @@ def _loadData(self, data):
         self.title = data.attrib.get('title', '')
         self.username = data.attrib.get('username', '')
         self.servers = self.findItems(data, MyPlexServerShare)
+        for server in self.servers:
+            server.accountID = self.id
 
     def get_token(self, machineIdentifier):
         try:
@@ -663,6 +678,29 @@ def get_token(self, machineIdentifier):
         except Exception:
             log.exception('Failed to get access token for %s' % self.title)
 
+    def server(self, name):
+        """ Returns the :class:`~plexapi.myplex.MyPlexServerShare` that matches the name specified.
+
+            Parameters:
+                name (str): Name of the server to return.
+        """
+        for server in self.servers:
+            if name.lower() == server.name.lower():
+                return server
+
+        raise NotFound('Unable to find server %s' % name)
+
+    def history(self, maxresults=9999999, mindate=None):
+        """ Get all Play History for a user in all shared servers.
+            Parameters:
+                maxresults (int): Only return the specified number of results (optional).
+                mindate (datetime): Min datetime to return results from.
+        """
+        hist = []
+        for server in self.servers:
+            hist.extend(server.history(maxresults=maxresults, mindate=mindate))
+        return hist
+
 
 class Section(PlexObject):
     """ This refers to a shared section. The raw xml for the data presented here
@@ -689,6 +727,16 @@ def _loadData(self, data):
         self.type = data.attrib.get('type')
         self.shared = utils.cast(bool, data.attrib.get('shared'))
 
+    def history(self, maxresults=9999999, mindate=None):
+        """ Get all Play History for a user for this section in this shared server.
+            Parameters:
+                maxresults (int): Only return the specified number of results (optional).
+                mindate (datetime): Min datetime to return results from.
+        """
+        server = self._server._server.resource(self._server.name).connect()
+        return server.history(maxresults=maxresults, mindate=mindate,
+                              accountID=self._server.accountID, librarySectionID=self.sectionKey)
+
 
 class MyPlexServerShare(PlexObject):
     """ Represents a single user's server reference. Used for library sharing.
@@ -711,6 +759,7 @@ def _loadData(self, data):
         """ Load attribute values from Plex XML response. """
         self._data = data
         self.id = utils.cast(int, data.attrib.get('id'))
+        self.accountID = utils.cast(int, data.attrib.get('accountID'))
         self.serverId = utils.cast(int, data.attrib.get('serverId'))
         self.machineIdentifier = data.attrib.get('machineIdentifier')
         self.name = data.attrib.get('name')
@@ -720,7 +769,21 @@ def _loadData(self, data):
         self.owned = utils.cast(bool, data.attrib.get('owned'))
         self.pending = utils.cast(bool, data.attrib.get('pending'))
 
+    def section(self, name):
+        """ Returns the :class:`~plexapi.myplex.Section` that matches the name specified.
+
+            Parameters:
+                name (str): Name of the section to return.
+        """
+        for section in self.sections():
+            if name.lower() == section.title.lower():
+                return section
+
+        raise NotFound('Unable to find section %s' % name)
+
     def sections(self):
+        """ Returns a list of all :class:`~plexapi.myplex.Section` objects shared with this user.
+        """
         url = MyPlexAccount.FRIENDSERVERS.format(machineId=self.machineIdentifier, serverId=self.id)
         data = self._server.query(url)
         sections = []
@@ -731,6 +794,15 @@ def sections(self):
 
         return sections
 
+    def history(self, maxresults=9999999, mindate=None):
+        """ Get all Play History for a user in this shared server.
+            Parameters:
+                maxresults (int): Only return the specified number of results (optional).
+                mindate (datetime): Min datetime to return results from.
+        """
+        server = self._server.resource(self.name).connect()
+        return server.history(maxresults=maxresults, mindate=mindate, accountID=self.accountID)
+
 
 class MyPlexResource(PlexObject):
     """ This object represents resources connected to your Plex server that can provide

plexapi/server.py

@@ -322,7 +322,7 @@ def installUpdate(self):
             # figure out what method this is..
             return self.query(part, method=self._session.put)
 
-    def history(self, maxresults=9999999, mindate=None):
+    def history(self, maxresults=9999999, mindate=None, ratingKey=None, accountID=None, librarySectionID=None):
         """ Returns a list of media items from watched history. If there are many results, they will
             be fetched from the server in batches of X_PLEX_CONTAINER_SIZE amounts. If you're only
             looking for the first <num> results, it would be wise to set the maxresults option to that
@@ -332,9 +332,18 @@ def history(self, maxresults=9999999, mindate=None):
                 maxresults (int): Only return the specified number of results (optional).
                 mindate (datetime): Min datetime to return results from. This really helps speed
                     up the result listing. For example: datetime.now() - timedelta(days=7)
+                ratingKey (int/str) Request history for a specific ratingKey item.
+                accountID (int/str) Request history for a specific account ID.
+                librarySectionID (int/str) Request history for a specific library section ID.
         """
         results, subresults = [], '_init'
         args = {'sort': 'viewedAt:desc'}
+        if ratingKey:
+            args['metadataItemID'] = ratingKey
+        if accountID:
+            args['accountID'] = accountID
+        if librarySectionID:
+            args['librarySectionID'] = librarySectionID
         if mindate:
             args['viewedAt>'] = int(mindate.timestamp())
         args['X-Plex-Container-Start'] = 0

tests/test_audio.py

@@ -32,6 +32,11 @@ def test_audio_Artist_get(artist, music):
     artist.title == 'Infinite State'
 
 
+def test_audio_Artist_history(artist):
+    history = artist.history()
+    assert len(history)
+
+
 def test_audio_Artist_track(artist):
     track = artist.track('Holy Moment')
     assert track.title == 'Holy Moment'
@@ -80,6 +85,16 @@ def test_audio_Album_attrs(album):
     assert album.artUrl is None
 
 
+def test_audio_Album_history(album):
+    history = album.history()
+    assert len(history)
+
+
+def test_audio_Track_history(track):
+    history = track.history()
+    assert len(history)
+
+
 def test_audio_Album_tracks(album):
     tracks = album.tracks()
     track = tracks[0]

tests/test_history.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+import pytest
+from datetime import datetime
+from plexapi.exceptions import BadRequest, NotFound
+from . import conftest as utils
+
+
+def test_history_Movie(movie):
+    movie.markWatched()
+    history = movie.history()
+    assert len(history)
+    movie.markUnwatched()
+
+
+def test_history_Show(show):
+    show.markWatched()
+    history = show.history()
+    assert len(history)
+    show.markUnwatched()
+
+
+def test_history_Season(show):
+    season = show.season('Season 1')
+    season.markWatched()
+    history = season.history()
+    assert len(history)
+    season.markUnwatched()
+
+
+def test_history_Episode(episode):
+    episode.markWatched()
+    history = episode.history()
+    assert len(history)
+    episode.markUnwatched()
+
+
+def test_history_Artist(artist):
+    history = artist.history()
+
+
+def test_history_Album(album):
+    history = album.history()
+
+
+def test_history_Track(track):
+    history = track.history()
+
+
+def test_history_MyAccount(account, movie, show):
+    movie.markWatched()
+    show.markWatched()
+    history = account.history()
+    assert len(history)
+    movie.markUnwatched()
+    show.markUnwatched()
+
+
+def test_history_MyLibrary(plex, movie, show):
+    movie.markWatched()
+    show.markWatched()
+    history = plex.library.history()
+    assert len(history)
+    movie.markUnwatched()
+    show.markUnwatched()
+
+
+def test_history_MySection(plex, movie):
+    movie.markWatched()
+    history = plex.library.section('Movies').history()
+    assert len(history)
+    movie.markUnwatched()
+
+
+def test_history_MyServer(plex, movie):
+    movie.markWatched()
+    history = plex.history()
+    assert len(history)
+    movie.markUnwatched()
+
+
+def test_history_User(account, shared_username):
+    user = account.user(shared_username)
+    history = user.history()
+
+
+def test_history_UserServer(account, shared_username, plex):
+    userSharedServer = account.user(shared_username).server(plex.friendlyName)
+    history = userSharedServer.history()
+
+
+def test_history_UserSection(account, shared_username, plex):
+    userSharedServerSection = account.user(shared_username).server(plex.friendlyName).section('Movies')
+    history = userSharedServerSection.history()
+

tests/test_video.py

@@ -296,6 +296,13 @@ def test_video_Movie_attrs(movies):
     assert stream2.type == 2
 
 
+def test_video_Movie_history(movie):
+    movie.markWatched()
+    history = movie.history()
+    assert len(history)
+    movie.markUnwatched()
+
+
 def test_video_Show(show):
     assert show.title == 'Game of Thrones'
 
@@ -362,6 +369,13 @@ def test_video_Show_attrs(show):
     assert show.url(None) is None
 
 
+def test_video_Show_history(show):
+    show.markWatched()
+    history = show.history()
+    assert len(history)
+    show.markUnwatched()
+
+
 def test_video_Show_watched(tvshows):
     show = tvshows.get('The 100')
     show.episodes()[0].markWatched()
@@ -468,6 +482,13 @@ def test_video_Episode(show):
         show.episode(season=1337, episode=1337)
 
 
+def test_video_Episode_history(episode):
+    episode.markWatched()
+    history = episode.history()
+    assert len(history)
+    episode.markUnwatched()
+
+
 # Analyze seems to fail intermittently
 @pytest.mark.xfail
 def test_video_Episode_analyze(tvshows):
@@ -544,6 +565,14 @@ def test_video_Season(show):
     assert show.season('Season 1') == seasons[0]
 
 
+def test_video_Season_history(show):
+    season = show.season('Season 1')
+    season.markWatched()
+    history = season.history()
+    assert len(history)
+    season.markUnwatched()
+
+
 def test_video_Season_attrs(show):
     season = show.season('Season 1')
     assert utils.is_datetime(season.addedAt)