Support history for specific ratingKeys

Add history method to PlexPartialObject
Add ratingKey to server history method.
Add tests for movie, show, season, episode, artist, album, and track history.

plexapi/base.py

@@ -421,6 +421,11 @@ class PlexPartialObject(PlexObject):
                 'havnt allowed items to be deleted' % self.key)
             raise
 
+    def history(self):
+        """ Get Play History for a media item. """
+        return self._server.history(ratingKey=self.ratingKey)
+
+
     # The photo tag cant be built atm. TODO
     # def arts(self):
     #     part = '%s/arts' % self.key

plexapi/server.py

@@ -322,7 +322,7 @@ class PlexServer(PlexObject):
             # 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):
         """ 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
@@ -335,6 +335,8 @@ class PlexServer(PlexObject):
         """
         results, subresults = [], '_init'
         args = {'sort': 'viewedAt:desc'}
+        if ratingKey:
+            args['metadataItemID'] = ratingKey
         if mindate:
             args['viewedAt>'] = int(mindate.timestamp())
         args['X-Plex-Container-Start'] = 0

tests/test_audio.py

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

tests/test_video.py

@@ -272,6 +272,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'
 
@@ -338,6 +345,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()
@@ -444,6 +458,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):
@@ -520,6 +541,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)