Add logo resources

plexapi/media.py

@@ -1094,6 +1094,11 @@ class Art(BaseResource):
     TAG = 'Photo'
 
 
+class Logo(BaseResource):
+    """ Represents a single Logo object. """
+    TAG = 'Photo'
+
+
 class Poster(BaseResource):
     """ Represents a single Poster object. """
     TAG = 'Photo'

plexapi/mixins.py

@@ -403,6 +403,63 @@ def setArt(self, art):
         return self
 
 
+class LogoUrlMixin:
+    """ Mixin for Plex objects that can have a logo url. """
+
+    @property
+    def logoUrl(self):
+        """ Return the logo url for the Plex object. """
+        image = next((i for i in self.images if i.type == 'clearLogo'), None)
+        return self._server.url(image.url, includeToken=True) if image else None
+
+
+class LogoLockMixin:
+    """ Mixin for Plex objects that can have a locked logo. """
+
+    def lockLogo(self):
+        """ Lock the logo for a Plex object. """
+        raise NotImplementedError('Logo cannot be locked through the API.')
+
+    def unlockLogo(self):
+        """ Unlock the logo for a Plex object. """
+        raise NotImplementedError('Logo cannot be unlocked through the API.')
+
+
+class LogoMixin(LogoUrlMixin, LogoLockMixin):
+    """ Mixin for Plex objects that can have logos. """
+
+    def logos(self):
+        """ Returns list of available :class:`~plexapi.media.Logo` objects. """
+        return self.fetchItems(f'/library/metadata/{self.ratingKey}/clearLogos', cls=media.Logo)
+
+    def uploadLogo(self, url=None, filepath=None):
+        """ Upload a logo from a url or filepath.
+
+            Parameters:
+                url (str): The full URL to the image to upload.
+                filepath (str): The full file path the the image to upload or file-like object.
+        """
+        if url:
+            key = f'/library/metadata/{self.ratingKey}/clearLogos?url={quote_plus(url)}'
+            self._server.query(key, method=self._server._session.post)
+        elif filepath:
+            key = f'/library/metadata/{self.ratingKey}/clearLogos'
+            data = openOrRead(filepath)
+            self._server.query(key, method=self._server._session.post, data=data)
+        return self
+
+    def setLogo(self, logo):
+        """ Set the logo for a Plex object.
+
+            Raises:
+                :exc:`~plexapi.exceptions.NotImplementedError`: Logo cannot be set through the API.
+        """
+        raise NotImplementedError(
+            'Logo cannot be set through the API. '
+            'Re-upload the logo using "uploadLogo" to set it.'
+        )
+
+
 class PosterUrlMixin:
     """ Mixin for Plex objects that can have a poster url. """
 
@@ -513,6 +570,11 @@ def uploadTheme(self, url=None, filepath=None, timeout=None):
         return self
 
     def setTheme(self, theme):
+        """ Set the theme for a Plex object.
+
+            Raises:
+                :exc:`~plexapi.exceptions.NotImplementedError`: Themes cannot be set through the API.
+        """
         raise NotImplementedError(
             'Themes cannot be set through the API. '
             'Re-upload the theme using "uploadTheme" to set it.'

plexapi/utils.py

@@ -90,6 +90,8 @@
     'theme': 317,
     'studio': 318,
     'network': 319,
+    'showOrdering': 322,
+    'clearLogo': 323,
     'place': 400,
 }
 REVERSETAGTYPES = {v: k for k, v in TAGTYPES.items()}

plexapi/video.py

@@ -9,7 +9,7 @@
 from plexapi.exceptions import BadRequest
 from plexapi.mixins import (
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, PlayedUnplayedMixin, RatingMixin,
-    ArtUrlMixin, ArtMixin, PosterUrlMixin, PosterMixin, ThemeUrlMixin, ThemeMixin,
+    ArtUrlMixin, ArtMixin, LogoMixin, PosterUrlMixin, PosterMixin, ThemeUrlMixin, ThemeMixin,
     MovieEditMixins, ShowEditMixins, SeasonEditMixins, EpisodeEditMixins,
     WatchlistMixin
 )
@@ -334,7 +334,7 @@ def sync(self, videoQuality, client=None, clientId=None, limit=None, unwatched=F
 class Movie(
     Video, Playable,
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin,
-    ArtMixin, PosterMixin, ThemeMixin,
+    ArtMixin, LogoMixin, PosterMixin, ThemeMixin,
     MovieEditMixins,
     WatchlistMixin
 ):
@@ -491,7 +491,7 @@ def metadataDirectory(self):
 class Show(
     Video,
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin,
-    ArtMixin, PosterMixin, ThemeMixin,
+    ArtMixin, LogoMixin, PosterMixin, ThemeMixin,
     ShowEditMixins,
     WatchlistMixin
 ):