Add support for watchlists and streaming services (#922)

* Remove Plex news

* Replace requests with query method for online hubs

* Add myPlexAccount watchlist methods

* Add mixin for objects that can be added to watchlist

* Add tests for watchlist

* Always split ratingKey from guid for watchlist

* Add method to retrieve streaming service availability

* Add test for streaming service availability

* Add filtering and sorting for watchlists

* Fix watchlist tests

* Add method to check if an item is on a user's watchlist

* Update watchlist tests

* Make account optional for WatchlistMixin

* Add Discover search

* Use manuallyLoadXML method for Discover search results

* Remove webshows and podcasts

* Fix WatchlistMixin account AttributeError

* Add BadRequest exception when adding to/removing from watchlist

* Update watchlist tests for BadRequest

* Update watchlist doc strings

Author: JonnyWong16

plexapi/media.py

@@ -1112,3 +1112,41 @@ def _loadData(self, data):
     @deprecated('use "languageCodes" instead')
     def languageCode(self):
         return self.languageCodes
+
+
+@utils.registerPlexObject
+class Availability(PlexObject):
+    """ Represents a single online streaming service Availability.
+
+        Attributes:
+            TAG (str): 'Availability'
+            country (str): The streaming service country.
+            offerType (str): Subscription, buy, or rent from the streaming service.
+            platform (str): The platform slug for the streaming service.
+            platformColorThumb (str): Thumbnail icon for the streaming service.
+            platformInfo (str): The streaming service platform info.
+            platformUrl (str): The URL to the media on the streaming service.
+            price (float): The price to buy or rent from the streaming service.
+            priceDescription (str): The display price to buy or rent from the streaming service.
+            quality (str): The video quality on the streaming service.
+            title (str): The title of the streaming service.
+            url (str): The Plex availability URL.
+    """
+    TAG = 'Availability'
+
+    def __repr__(self):
+        return f'<{self.__class__.__name__}:{self.platform}:{self.offerType}>'
+
+    def _loadData(self, data):
+        self._data = data
+        self.country = data.attrib.get('country')
+        self.offerType = data.attrib.get('offerType')
+        self.platform = data.attrib.get('platform')
+        self.platformColorThumb = data.attrib.get('platformColorThumb')
+        self.platformInfo = data.attrib.get('platformInfo')
+        self.platformUrl = data.attrib.get('platformUrl')
+        self.price = utils.cast(float, data.attrib.get('price'))
+        self.priceDescription = data.attrib.get('priceDescription')
+        self.quality = data.attrib.get('quality')
+        self.title = data.attrib.get('title')
+        self.url = data.attrib.get('url')

plexapi/mixins.py

@@ -984,3 +984,65 @@ def removeWriter(self, writers, locked=True):
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('writer', writers, locked=locked, remove=True)
+
+
+class WatchlistMixin(object):
+    """ Mixin for Plex objects that can be added to a user's watchlist. """
+
+    def onWatchlist(self, account=None):
+        """ Returns True if the item is on the user's watchlist.
+            Also see :func:`~plexapi.myplex.MyPlexAccount.onWatchlist`.
+
+            Parameters:
+                account (:class:`~plexapi.myplex.MyPlexAccount`, optional): Account to check item on the watchlist.
+                   Note: This is required if you are not connected to a Plex server instance using the admin account.
+        """
+        try:
+            account = account or self._server.myPlexAccount()
+        except AttributeError:
+            account = self._server
+        return account.onWatchlist(self)
+
+    def addToWatchlist(self, account=None):
+        """ Add this item to the specified user's watchlist.
+            Also see :func:`~plexapi.myplex.MyPlexAccount.addToWatchlist`.
+
+            Parameters:
+                account (:class:`~plexapi.myplex.MyPlexAccount`, optional): Account to add item to the watchlist.
+                   Note: This is required if you are not connected to a Plex server instance using the admin account.
+        """
+        try:
+            account = account or self._server.myPlexAccount()
+        except AttributeError:
+            account = self._server
+        account.addToWatchlist(self)
+
+    def removeFromWatchlist(self, account=None):
+        """ Remove this item from the specified user's watchlist.
+            Also see :func:`~plexapi.myplex.MyPlexAccount.removeFromWatchlist`.
+
+            Parameters:
+                account (:class:`~plexapi.myplex.MyPlexAccount`, optional): Account to remove item from the watchlist.
+                   Note: This is required if you are not connected to a Plex server instance using the admin account.
+        """
+        try:
+            account = account or self._server.myPlexAccount()
+        except AttributeError:
+            account = self._server
+        account.removeFromWatchlist(self)
+
+    def streamingServices(self, account=None):
+        """ Return a list of :class:`~plexapi.media.Availability`
+            objects for the available streaming services for this item.
+
+            Parameters:
+                account (:class:`~plexapi.myplex.MyPlexAccount`, optional): Account used to retrieve availability.
+                   Note: This is required if you are not connected to a Plex server instance using the admin account.
+        """
+        try:
+            account = account or self._server.myPlexAccount()
+        except AttributeError:
+            account = self._server
+        ratingKey = self.guid.rsplit('/', 1)[-1]
+        data = account.query(f"{account.METADATA}/library/metadata/{ratingKey}/availabilities")
+        return self.findItems(data)

plexapi/myplex.py

@@ -1,5 +1,6 @@
 # -*- coding: utf-8 -*-
 import copy
+import html
 import threading
 import time
 from xml.etree import ElementTree
@@ -72,14 +73,12 @@ class MyPlexAccount(PlexObject):
     REMOVEHOMEUSER = 'https://plex.tv/api/home/users/{userId}'                                  # delete
     SIGNIN = 'https://plex.tv/users/sign_in.xml'                                                # get with auth
     WEBHOOKS = 'https://plex.tv/api/v2/user/webhooks'                                           # get, post with data
-    OPTOUTS = 'https://plex.tv/api/v2/user/%(userUUID)s/settings/opt_outs'                      # get
+    OPTOUTS = 'https://plex.tv/api/v2/user/{userUUID}/settings/opt_outs'                        # get
     LINK = 'https://plex.tv/api/v2/pins/link'                                                   # put
     # Hub sections
-    VOD = 'https://vod.provider.plex.tv/'                                                       # get
-    WEBSHOWS = 'https://webshows.provider.plex.tv/'                                             # get
-    NEWS = 'https://news.provider.plex.tv/'                                                     # get
-    PODCASTS = 'https://podcasts.provider.plex.tv/'                                             # get
-    MUSIC = 'https://music.provider.plex.tv/'                                                   # get
+    VOD = 'https://vod.provider.plex.tv'                                                        # get
+    MUSIC = 'https://music.provider.plex.tv'                                                    # get
+    METADATA = 'https://metadata.provider.plex.tv'
     # Key may someday switch to the following url. For now the current value works.
     # https://plex.tv/api/v2/user?X-Plex-Token={token}&X-Plex-Client-Identifier={clientId}
     key = 'https://plex.tv/users/account'
@@ -182,6 +181,8 @@ def query(self, url, method=None, headers=None, timeout=None, **kwargs):
                 raise NotFound(message)
             else:
                 raise BadRequest(message)
+        if headers.get('Accept') == 'application/json':
+            return response.json()
         data = response.text.encode('utf8')
         return ElementTree.fromstring(data) if data.strip() else None
 
@@ -698,6 +699,7 @@ def claimToken(self):
 
     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.
@@ -709,47 +711,155 @@ def history(self, maxresults=9999999, mindate=None):
             hist.extend(conn.history(maxresults=maxresults, mindate=mindate, accountID=1))
         return hist
 
+    def onlineMediaSources(self):
+        """ Returns a list of user account Online Media Sources settings :class:`~plexapi.myplex.AccountOptOut`
+        """
+        url = self.OPTOUTS.format(userUUID=self.uuid)
+        elem = self.query(url)
+        return self.findItems(elem, cls=AccountOptOut, etag='optOut')
+
     def videoOnDemand(self):
         """ Returns a list of VOD Hub items :class:`~plexapi.library.Hub`
         """
-        req = requests.get(self.VOD + 'hubs/', headers={'X-Plex-Token': self._token})
-        elem = ElementTree.fromstring(req.text)
-        return self.findItems(elem)
+        data = self.query(f'{self.VOD}/hubs')
+        return self.findItems(data)
 
-    def webShows(self):
-        """ Returns a list of Webshow Hub items :class:`~plexapi.library.Hub`
+    def tidal(self):
+        """ Returns a list of tidal Hub items :class:`~plexapi.library.Hub`
         """
-        req = requests.get(self.WEBSHOWS + 'hubs/', headers={'X-Plex-Token': self._token})
-        elem = ElementTree.fromstring(req.text)
-        return self.findItems(elem)
+        data = self.query(f'{self.MUSIC}/hubs')
+        return self.findItems(data)
+
+    def watchlist(self, filter=None, sort=None, libtype=None, **kwargs):
+        """ Returns a list of :class:`~plexapi.video.Movie` and :class:`~plexapi.video.Show` items in the user's watchlist.
+            Note: The objects returned are from Plex's online metadata. To get the matching item on a Plex server,
+            search for the media using the guid.
+
+            Parameters:
+                filter (str, optional): 'available' or 'released' to only return items that are available or released,
+                    otherwise return all items.
+                sort (str, optional): In the format ``field:dir``. Available fields are ``watchlistedAt`` (Added At),
+                    ``titleSort`` (Title), ``originallyAvailableAt`` (Release Date), or ``rating`` (Critic Rating).
+                    ``dir`` can be ``asc`` or ``desc``.
+                libtype (str, optional): 'movie' or 'show' to only return movies or shows, otherwise return all items.
+                **kwargs (dict): Additional custom filters to apply to the search results.
+
+
+            Example:
+
+                .. code-block:: python
+
+                    # Watchlist for released movies sorted by critic rating in descending order
+                    watchlist = account.watchlist(filter='released', sort='rating:desc', libtype='movie')
+                    item = watchlist[0]  # First item in the watchlist
+
+                    # Search for the item on a Plex server
+                    result = plex.library.search(guid=item.guid, libtype=item.type)
 
-    def news(self):
-        """ Returns a list of News Hub items :class:`~plexapi.library.Hub`
         """
-        req = requests.get(self.NEWS + 'hubs/sections/all', headers={'X-Plex-Token': self._token})
-        elem = ElementTree.fromstring(req.text)
-        return self.findItems(elem)
+        params = {
+            'includeCollections': 1,
+            'includeExternalMedia': 1
+        }
 
-    def podcasts(self):
-        """ Returns a list of Podcasts Hub items :class:`~plexapi.library.Hub`
+        if not filter:
+            filter = 'all'
+        if sort:
+            params['sort'] = sort
+        if libtype:
+            params['type'] = utils.searchType(libtype)
+
+        params.update(kwargs)
+        data = self.query(f'{self.METADATA}/library/sections/watchlist/{filter}', params=params)
+        return self.findItems(data)
+
+    def onWatchlist(self, item):
+        """ Returns True if the item is on the user's watchlist.
+
+            Parameters:
+                item (:class:`~plexapi.video.Movie` or :class:`~plexapi.video.Show`): Item to check
+                    if it is on the user's watchlist.
         """
-        req = requests.get(self.PODCASTS + 'hubs/', headers={'X-Plex-Token': self._token})
-        elem = ElementTree.fromstring(req.text)
-        return self.findItems(elem)
+        ratingKey = item.guid.rsplit('/', 1)[-1]
+        data = self.query(f"{self.METADATA}/library/metadata/{ratingKey}/userState")
+        return bool(data.find('UserState').attrib.get('watchlistedAt'))
 
-    def tidal(self):
-        """ Returns a list of tidal Hub items :class:`~plexapi.library.Hub`
+    def addToWatchlist(self, items):
+        """ Add media items to the user's watchlist
+
+            Parameters:
+                items (List): List of :class:`~plexapi.video.Movie` or :class:`~plexapi.video.Show`
+                    objects to be added to the watchlist.
+
+            Raises:
+                :exc:`~plexapi.exceptions.BadRequest`: When trying to add invalid or existing
+                    media to the watchlist.
         """
-        req = requests.get(self.MUSIC + 'hubs/', headers={'X-Plex-Token': self._token})
-        elem = ElementTree.fromstring(req.text)
-        return self.findItems(elem)
+        if not isinstance(items, list):
+            items = [items]
+        
+        for item in items:
+            if self.onWatchlist(item):
+                raise BadRequest('"%s" is already on the watchlist' % item.title)
+            ratingKey = item.guid.rsplit('/', 1)[-1]
+            self.query(f'{self.METADATA}/actions/addToWatchlist?ratingKey={ratingKey}', method=self._session.put)
 
-    def onlineMediaSources(self):
-        """ Returns a list of user account Online Media Sources settings :class:`~plexapi.myplex.AccountOptOut`
+    def removeFromWatchlist(self, items):
+        """ Remove media items from the user's watchlist
+
+            Parameters:
+                items (List): List of :class:`~plexapi.video.Movie` or :class:`~plexapi.video.Show`
+                    objects to be added to the watchlist.
+
+            Raises:
+                :exc:`~plexapi.exceptions.BadRequest`: When trying to remove invalid or non-existing
+                    media to the watchlist.
         """
-        url = self.OPTOUTS % {'userUUID': self.uuid}
-        elem = self.query(url)
-        return self.findItems(elem, cls=AccountOptOut, etag='optOut')
+        if not isinstance(items, list):
+            items = [items]
+        
+        for item in items:
+            if not self.onWatchlist(item):
+                raise BadRequest('"%s" is not on the watchlist' % item.title)
+            ratingKey = item.guid.rsplit('/', 1)[-1]
+            self.query(f'{self.METADATA}/actions/removeFromWatchlist?ratingKey={ratingKey}', method=self._session.put)
+
+    def searchDiscover(self, query, limit=30):
+        """ Search for movies and TV shows in Discover.
+            Returns a list of :class:`~plexapi.video.Movie` and :class:`~plexapi.video.Show` objects.
+
+            Parameters:
+                query (str): Search query.
+                limit (int, optional): Limit to the specified number of results. Default 30.
+        """
+        headers = {
+            'Accept': 'application/json'
+        }
+        params = {
+            'query': query,
+            'limit ': limit,
+            'searchTypes': 'movies,tv',
+            'includeMetadata': 1
+        }
+
+        data = self.query(f'{self.METADATA}/library/search', headers=headers, params=params)
+        searchResults = data['MediaContainer'].get('SearchResult', [])
+
+        results = []
+        for result in searchResults:
+            metadata = result['Metadata']
+            type = metadata['type']
+            if type == 'movie':
+                tag = 'Video'
+            elif type == 'show':
+                tag = 'Directory'
+            else:
+                continue
+            attrs = ''.join(f'{k}="{html.escape(str(v))}" ' for k, v in metadata.items())
+            xml = f'<{tag} {attrs}/>'
+            results.append(self._manuallyLoadXML(xml))
+
+        return results
 
     def link(self, pin):
         """ Link a device to the account using a pin code.

plexapi/video.py

@@ -10,7 +10,8 @@
     ArtUrlMixin, ArtMixin, BannerMixin, PosterUrlMixin, PosterMixin, ThemeUrlMixin, ThemeMixin,
     ContentRatingMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin,
     SummaryMixin, TaglineMixin, TitleMixin,
-    CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin
+    CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin,
+    WatchlistMixin
 )
 
 
@@ -280,7 +281,8 @@ class Movie(
     ArtMixin, PosterMixin, ThemeMixin,
     ContentRatingMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin,
     SummaryMixin, TaglineMixin, TitleMixin,
-    CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin
+    CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin,
+    WatchlistMixin
 ):
     """ Represents a single Movie.
 
@@ -394,7 +396,8 @@ class Show(
     ArtMixin, BannerMixin, PosterMixin, ThemeMixin,
     ContentRatingMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin,
     SummaryMixin, TaglineMixin, TitleMixin,
-    CollectionMixin, GenreMixin, LabelMixin
+    CollectionMixin, GenreMixin, LabelMixin,
+    WatchlistMixin
 ):
     """ Represents a single Show (including all seasons and episodes).