Merge branch 'master' into feature/album_types

Author: JonnyWong16

.github/workflows/ci.yaml

@@ -251,6 +251,6 @@ jobs:
         coverage xml
 
     - name: Upload ${{ matrix.plex }} coverage to Codecov
-      uses: codecov/codecov-action@v2.0.3
+      uses: codecov/codecov-action@v2.1.0
       with:
         flags: ${{ matrix.plex }}

plexapi/audio.py

@@ -426,3 +426,7 @@ def trackNumber(self):
     def _defaultSyncTitle(self):
         """ Returns str, default title for a new syncItem. """
         return '%s - %s - %s' % (self.grandparentTitle, self.parentTitle, self.title)
+
+    def _getWebURL(self, base=None):
+        """ Get the Plex Web URL with the correct parameters. """
+        return self._server._buildWebURL(base=base, endpoint='details', key=self.parentKey)

plexapi/base.py

@@ -579,12 +579,28 @@ def delete(self):
 
     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)
 
+    def _getWebURL(self, base=None):
+        """ Get the Plex Web URL with the correct parameters.
+            Private method to allow overriding parameters from subclasses.
+        """
+        return self._server._buildWebURL(base=base, endpoint='details', key=self.key)
+
+    def getWebURL(self, base=None):
+        """ Returns the Plex Web URL for a media item.
+
+            Parameters:
+                base (str): The base URL before the fragment (``#!``).
+                    Default is https://app.plex.tv/desktop.
+        """
+        return self._getWebURL(base=base)
+
 
 class Playable(object):
     """ This is a general place to store functions specific to media that is Playable.

plexapi/library.py

@@ -456,10 +456,45 @@ def get(self, title):
 
             Parameters:
                 title (str): Title of the item to return.
+
+            Raises:
+                :exc:`~plexapi.exceptions.NotFound`: The title is not found in the library.
         """
-        key = '/library/sections/%s/all?title=%s' % (self.key, quote(title, safe=''))
+        key = '/library/sections/%s/all?includeGuids=1&title=%s' % (self.key, quote(title, safe=''))
         return self.fetchItem(key, title__iexact=title)
 
+    def getGuid(self, guid):
+        """ Returns the media item with the specified external IMDB, TMDB, or TVDB ID.
+            Note: This search uses a PlexAPI operator so performance may be slow. All items from the
+            entire Plex library need to be retrieved for each guid search. It is recommended to create
+            your own lookup dictionary if you are searching for a lot of external guids.
+
+            Parameters:
+                guid (str): The external guid of the item to return.
+                    Examples: IMDB ``imdb://tt0944947``, TMDB ``tmdb://1399``, TVDB ``tvdb://121361``.
+
+            Raises:
+                :exc:`~plexapi.exceptions.NotFound`: The guid is not found in the library.
+
+            Example:
+
+                .. code-block:: python
+
+                    # This will retrieve all items in the entire library 3 times
+                    result1 = library.getGuid('imdb://tt0944947')
+                    result2 = library.getGuid('tmdb://1399')
+                    result3 = library.getGuid('tvdb://121361')
+
+                    # This will only retrieve all items in the library once to create a lookup dictionary
+                    guidLookup = {guid.id: item for item in library.all() for guid in item.guids}
+                    result1 = guidLookup['imdb://tt0944947']
+                    result2 = guidLookup['tmdb://1399']
+                    result3 = guidLookup['tvdb://121361']
+
+        """
+        key = '/library/sections/%s/all?includeGuids=1' % self.key
+        return self.fetchItem(key, Guid__id__iexact=guid)
+
     def all(self, libtype=None, **kwargs):
         """ Returns a list of all items from this library section.
             See description of :func:`~plexapi.library.LibrarySection.search()` for details about filtering / sorting.
@@ -979,6 +1014,8 @@ def _buildSearchKey(self, title=None, sort=None, libtype=None, limit=None, filte
         """
         args = {}
         filter_args = []
+
+        args['includeGuids'] = int(bool(kwargs.pop('includeGuids', True)))
         for field, values in list(kwargs.items()):
             if field.split('__')[-1] not in OPERATORS:
                 filter_args.append(self._validateFilterField(field, values, libtype))
@@ -1456,6 +1493,23 @@ def filterFields(self, mediaType=None):
     def listChoices(self, category, libtype=None, **kwargs):
         return self.listFilterChoices(field=category, libtype=libtype)
 
+    def getWebURL(self, base=None, tab=None, key=None):
+        """ Returns the Plex Web URL for the library.
+
+            Parameters:
+                base (str): The base URL before the fragment (``#!``).
+                    Default is https://app.plex.tv/desktop.
+                tab (str): The library tab (recommended, library, collections, playlists, timeline).
+                key (str): A hub key.
+        """
+        params = {'source': self.key}
+        if tab is not None:
+            params['pivot'] = tab
+        if key is not None:
+            params['key'] = key
+            params['pageType'] = 'list'
+        return self._server._buildWebURL(base=base, **params)
+
 
 class MovieSection(LibrarySection):
     """ Represents a :class:`~plexapi.library.LibrarySection` section containing movies.
@@ -1857,6 +1911,7 @@ def _loadData(self, data):
         self.style = data.attrib.get('style')
         self.title = data.attrib.get('title')
         self.type = data.attrib.get('type')
+        self._section = None  # cache for self.section
 
     def __len__(self):
         return self.size
@@ -1868,6 +1923,13 @@ def reload(self):
             self.more = False
             self.size = len(self.items)
 
+    def section(self):
+        """ Returns the :class:`~plexapi.library.LibrarySection` this hub belongs to.
+        """
+        if self._section is None:
+            self._section = self._server.library.sectionByID(self.librarySectionID)
+        return self._section
+
 
 class HubMediaTag(PlexObject):
     """ Base class of hub media tag search results.

plexapi/mixins.py

@@ -601,7 +601,9 @@ def _parseFilters(self, content):
                 key += '='
                 value = value[1:]
 
-            if key == 'type':
+            if key == 'includeGuids':
+                filters['includeGuids'] = int(value)
+            elif key == 'type':
                 filters['libtype'] = utils.reverseSearchType(value)
             elif key == 'sort':
                 filters['sort'] = value.split(',')

plexapi/photo.py

@@ -137,6 +137,10 @@ def download(self, savepath=None, keep_original_name=False, showstatus=False):
                 filepaths.append(filepath)
         return filepaths
 
+    def _getWebURL(self, base=None):
+        """ Get the Plex Web URL with the correct parameters. """
+        return self._server._buildWebURL(base=base, endpoint='details', key=self.key, legacy=1)
+
 
 @utils.registerPlexObject
 class Photo(PlexPartialObject, Playable, ArtUrlMixin, PosterUrlMixin, RatingMixin, TagMixin):
@@ -301,3 +305,7 @@ def download(self, savepath=None, keep_original_name=False, showstatus=False):
             if filepath:
                 filepaths.append(filepath)
         return filepaths
+
+    def _getWebURL(self, base=None):
+        """ Get the Plex Web URL with the correct parameters. """
+        return self._server._buildWebURL(base=base, endpoint='details', key=self.parentKey, legacy=1)

plexapi/playlist.py

@@ -464,3 +464,7 @@ def sync(self, videoQuality=None, photoResolution=None, audioBitrate=None, clien
             raise Unsupported('Unsupported playlist content')
 
         return myplex.sync(sync_item, client=client, clientId=clientId)
+
+    def _getWebURL(self, base=None):
+        """ Get the Plex Web URL with the correct parameters. """
+        return self._server._buildWebURL(base=base, endpoint='playlist', key=self.key)

plexapi/server.py

@@ -890,6 +890,42 @@ def resources(self):
         key = '/statistics/resources?timespan=6'
         return self.fetchItems(key, StatisticsResources)
 
+    def _buildWebURL(self, base=None, endpoint=None, **kwargs):
+        """ Build the Plex Web URL for the object.
+
+            Parameters:
+                base (str): The base URL before the fragment (``#!``).
+                    Default is https://app.plex.tv/desktop.
+                endpoint (str): The Plex Web URL endpoint.
+                    None for server, 'playlist' for playlists, 'details' for all other media types.
+                **kwargs (dict): Dictionary of URL parameters.
+        """
+        if base is None:
+            base = 'https://app.plex.tv/desktop/'
+
+        if endpoint:
+            return '%s#!/server/%s/%s%s' % (
+                base, self.machineIdentifier, endpoint, utils.joinArgs(kwargs)
+            )
+        else:
+            return '%s#!/media/%s/com.plexapp.plugins.library%s' % (
+                base, self.machineIdentifier, utils.joinArgs(kwargs)
+            )
+
+    def getWebURL(self, base=None, playlistTab=None):
+        """ Returns the Plex Web URL for the server.
+
+            Parameters:
+                base (str): The base URL before the fragment (``#!``).
+                    Default is https://app.plex.tv/desktop.
+                playlistTab (str): The playlist tab (audio, video, photo). Only used for the playlist URL.
+        """
+        if playlistTab is not None:
+            params = {'source': 'playlists', 'pivot': 'playlists.%s' % playlistTab}
+        else:
+            params = {'key': '/hubs', 'pageType': 'hub'}
+        return self._buildWebURL(base=base, **params)
+
 
 class Account(PlexObject):
     """ Contains the locally cached MyPlex account information. The properties provided don't

requirements_dev.txt

@@ -7,12 +7,12 @@ flake8==3.9.2
 pillow==8.3.2
 pytest==6.2.5
 pytest-cache==1.0
-pytest-cov==2.12.1
+pytest-cov==3.0.0
 pytest-mock<3.6.2
 recommonmark==0.7.1
 requests==2.26.0
 requests-mock==1.9.3
-sphinx==4.1.2
-sphinx-rtd-theme==0.5.2
-tqdm==4.62.2
+sphinx==4.2.0
+sphinx-rtd-theme==1.0.0
+tqdm==4.62.3
 websocket-client==1.2.1

tests/test_audio.py

@@ -1,4 +1,6 @@
 # -*- coding: utf-8 -*-
+from urllib.parse import quote_plus
+
 import pytest
 from plexapi.exceptions import BadRequest
 
@@ -115,6 +117,14 @@ def test_audio_Artist_media_tags(artist):
     test_media.tag_style(artist)
 
 
+def test_video_Artist_PlexWebURL(plex, artist):
+    url = artist.getWebURL()
+    assert url.startswith('https://app.plex.tv/desktop')
+    assert plex.machineIdentifier in url
+    assert 'details' in url
+    assert quote_plus(artist.key) in url
+
+
 def test_audio_Album_attrs(album):
     assert utils.is_datetime(album.addedAt)
     if album.art:
@@ -214,6 +224,14 @@ def test_audio_Album_media_tags(album):
     test_media.tag_style(album)
 
 
+def test_video_Album_PlexWebURL(plex, album):
+    url = album.getWebURL()
+    assert url.startswith('https://app.plex.tv/desktop')
+    assert plex.machineIdentifier in url
+    assert 'details' in url
+    assert quote_plus(album.key) in url
+
+
 def test_audio_Track_attrs(album):
     track = album.get("As Colourful As Ever").reload()
     assert utils.is_datetime(track.addedAt)
@@ -357,6 +375,14 @@ def test_audio_Track_media_tags(track):
     test_media.tag_mood(track)
 
 
+def test_video_Track_PlexWebURL(plex, track):
+    url = track.getWebURL()
+    assert url.startswith('https://app.plex.tv/desktop')
+    assert plex.machineIdentifier in url
+    assert 'details' in url
+    assert quote_plus(track.parentKey) in url
+
+
 def test_audio_Audio_section(artist, album, track):
     assert artist.section()
     assert album.section()