Merge branch 'master' into feature/delete_resources

Author: JonnyWong16

.gitignore

@@ -27,6 +27,8 @@ pyvenv.cfg
 MANIFEST
 venv/
 .venv/
+private.key
+public.key
 
 # path for the test lib.
 plex/

README.rst

@@ -37,6 +37,7 @@ Installation & Documentation
 .. code-block:: python
 
     pip install plexapi[alert]  # Install with dependencies required for plexapi.alert
+    pip install plexapi[jwt]    # Install with dependencies required for Plex JWT authentication
 
 Documentation_ can be found at Read the Docs.
 

plexapi/audio.py

@@ -12,7 +12,8 @@
 from plexapi.exceptions import BadRequest
 from plexapi.mixins import (
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, PlayedUnplayedMixin, RatingMixin,
-    ArtUrlMixin, ArtMixin, LogoMixin, LogoUrlMixin, PosterUrlMixin, PosterMixin, ThemeMixin, ThemeUrlMixin,
+    ArtUrlMixin, ArtMixin, LogoMixin, LogoUrlMixin, PosterUrlMixin, PosterMixin, SquareArtMixin, SquareArtUrlMixin,
+    ThemeMixin, ThemeUrlMixin,
     ArtistEditMixins, AlbumEditMixins, TrackEditMixins
 )
 from plexapi.playlist import Playlist
@@ -181,7 +182,7 @@ def sonicallySimilar(
 class Artist(
     Audio,
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin,
-    ArtMixin, LogoMixin, PosterMixin, ThemeMixin,
+    ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeMixin,
     ArtistEditMixins
 ):
     """ Represents a single Artist.
@@ -351,7 +352,7 @@ def metadataDirectory(self):
 class Album(
     Audio,
     SplitMergeMixin, UnmatchMatchMixin, RatingMixin,
-    ArtMixin, LogoMixin, PosterMixin, ThemeUrlMixin,
+    ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeUrlMixin,
     AlbumEditMixins
 ):
     """ Represents a single Album.
@@ -504,7 +505,7 @@ def metadataDirectory(self):
 class Track(
     Audio, Playable,
     ExtrasMixin, RatingMixin,
-    ArtUrlMixin, LogoUrlMixin, PosterUrlMixin, ThemeUrlMixin,
+    ArtUrlMixin, LogoUrlMixin, PosterUrlMixin, SquareArtUrlMixin, ThemeUrlMixin,
     TrackEditMixins
 ):
     """ Represents a single Track.

plexapi/collection.py

@@ -8,7 +8,7 @@
 from plexapi.library import LibrarySection, ManagedHub
 from plexapi.mixins import (
     AdvancedSettingsMixin, SmartFilterMixin, HubsMixin, RatingMixin,
-    ArtMixin, LogoMixin, PosterMixin, ThemeMixin,
+    ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeMixin,
     CollectionEditMixins
 )
 from plexapi.utils import deprecated
@@ -18,7 +18,7 @@
 class Collection(
     PlexPartialObject,
     AdvancedSettingsMixin, SmartFilterMixin, HubsMixin, RatingMixin,
-    ArtMixin, LogoMixin, PosterMixin, ThemeMixin,
+    ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeMixin,
     CollectionEditMixins
 ):
     """ Represents a single Collection.

plexapi/media.py

@@ -741,7 +741,7 @@ class MediaTag(PlexObject):
 
         Attributes:
             filter (str): The library filter for the tag.
-            id (id): Tag ID (This seems meaningless except to use it as a unique id).
+            id (int): Tag ID (This seems meaningless except to use it as a unique id).
             key (str): API URL (/library/section/<librarySectionID>/all?<filter>).
             role (str): The name of the character role for :class:`~plexapi.media.Role` only.
             tag (str): Name of the tag. This will be Animation, SciFi etc for Genres. The name of
@@ -1116,6 +1116,11 @@ class Poster(BaseResource):
     TAG = 'Photo'
 
 
+class SquareArt(BaseResource):
+    """ Represents a single Square Art object. """
+    TAG = 'Photo'
+
+
 class Theme(BaseResource):
     """ Represents a single Theme object. """
     TAG = 'Track'
@@ -1366,3 +1371,123 @@ class Level(PlexObject):
     def _loadData(self, data):
         """ Load attribute values from Plex XML response. """
         self.loudness = utils.cast(float, data.attrib.get('v'))
+
+
+@utils.registerPlexObject
+class CommonSenseMedia(PlexObject):
+    """ Represents a single CommonSenseMedia media tag.
+        Note: This object is only loaded with partial data from a Plex Media Server.
+        Call `reload()` to load the full data from Plex Discover (Plex Pass required).
+
+        Attributes:
+            TAG (str): 'CommonSenseMedia'
+            ageRatings (List<:class:`~plexapi.media.AgeRating`>): List of AgeRating objects.
+            anyGood (str): A brief description of the media's quality.
+            id (int): The ID of the CommonSenseMedia tag.
+            key (str): The unique key for the CommonSenseMedia tag.
+            oneLiner (str): A brief description of the CommonSenseMedia tag.
+            parentalAdvisoryTopics (List<:class:`~plexapi.media.ParentalAdvisoryTopic`>):
+                List of ParentalAdvisoryTopic objects.
+            parentsNeedToKnow (str): A brief description of what parents need to know about the media.
+            talkingPoints (List<:class:`~plexapi.media.TalkingPoint`>): List of TalkingPoint objects.
+
+        Example:
+
+            .. code-block:: python
+
+                from plexapi.server import PlexServer
+                plex = PlexServer('http://localhost:32400', token='xxxxxxxxxxxxxxxxxxxx')
+
+                # Retrieve the Common Sense Media info for a movie
+                movie = plex.library.section('Movies').get('Cars')
+                commonSenseMedia = movie.commonSenseMedia
+                ageRating = commonSenseMedia.ageRatings[0].age
+
+                # Load the Common Sense Media info from Plex Discover (Plex Pass required)
+                commonSenseMedia.reload()
+                parentalAdvisoryTopics = commonSenseMedia.parentalAdvisoryTopics
+                talkingPoints = commonSenseMedia.talkingPoints
+
+    """
+    TAG = 'CommonSenseMedia'
+
+    def _loadData(self, data):
+        self.ageRatings = self.findItems(data, AgeRating)
+        self.anyGood = data.attrib.get('anyGood')
+        self.id = utils.cast(int, data.attrib.get('id'))
+        self.key = data.attrib.get('key')
+        self.oneLiner = data.attrib.get('oneLiner')
+        self.parentalAdvisoryTopics = self.findItems(data, ParentalAdvisoryTopic)
+        self.parentsNeedToKnow = data.attrib.get('parentsNeedToKnow')
+        self.talkingPoints = self.findItems(data, TalkingPoint)
+
+    def _reload(self, **kwargs):
+        """ Reload the data for the Common Sense Media object. """
+        guid = self._parent().guid
+        if not guid.startswith('plex://'):
+            return self
+
+        ratingKey = guid.rsplit('/', 1)[-1]
+        account = self._server.myPlexAccount()
+        key = f'{account.METADATA}/library/metadata/{ratingKey}/commonsensemedia'
+        data = account.query(key)
+        self._findAndLoadElem(data)
+        return self
+
+
+@utils.registerPlexObject
+class AgeRating(PlexObject):
+    """ Represents a single AgeRating for a Common Sense Media tag.
+
+        Attributes:
+            TAG (str): 'AgeRating'
+            age (float): The age rating (e.g. 13, 17).
+            ageGroup (str): The age group for the rating (e.g. Little Kids, Teens, etc.).
+            rating (float): The star rating (out of 5).
+            ratingCount (int): The number of ratings contributing to the star rating.
+            type (str): The type of rating (official, adult, child).
+    """
+    TAG = 'AgeRating'
+
+    def _loadData(self, data):
+        self.age = utils.cast(float, data.attrib.get('age'))
+        self.ageGroup = data.attrib.get('ageGroup')
+        self.rating = utils.cast(float, data.attrib.get('rating'))
+        self.ratingCount = utils.cast(int, data.attrib.get('ratingCount'))
+        self.type = data.attrib.get('type')
+
+
+@utils.registerPlexObject
+class TalkingPoint(PlexObject):
+    """ Represents a single TalkingPoint for a Common Sense Media tag.
+
+        Attributes:
+            TAG (str): 'TalkingPoint'
+            tag (str): The description of the talking point.
+    """
+    TAG = 'TalkingPoint'
+
+    def _loadData(self, data):
+        self.tag = data.attrib.get('tag')
+
+
+@utils.registerPlexObject
+class ParentalAdvisoryTopic(PlexObject):
+    """ Represents a single ParentalAdvisoryTopic for a Common Sense Media tag.
+
+        Attributes:
+            TAG (str): 'ParentalAdvisoryTopic'
+            id (str): The ID of the topic (e.g. violence, language, etc.).
+            label (str): The label for the topic (e.g. Violence & Scariness, Language, etc.).
+            positive (bool): Whether the topic is considered positive.
+            rating (float): The rating of the topic (out of 5).
+            tag (str): The description of the parental advisory topic.
+    """
+    TAG = 'ParentalAdvisoryTopic'
+
+    def _loadData(self, data):
+        self.id = data.attrib.get('id')
+        self.label = data.attrib.get('label')
+        self.positive = utils.cast(bool, data.attrib.get('positive'))
+        self.rating = utils.cast(float, data.attrib.get('rating'))
+        self.tag = data.attrib.get('tag')

plexapi/mixins.py

@@ -382,7 +382,7 @@ def uploadArt(self, url=None, filepath=None):
 
             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.
+                filepath (str): The full file path to the image to upload or file-like object.
         """
         if url:
             key = f'/library/metadata/{self.ratingKey}/arts?url={quote_plus(url)}'
@@ -447,7 +447,7 @@ def uploadLogo(self, url=None, filepath=None):
 
             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.
+                filepath (str): The full file path to the image to upload or file-like object.
         """
         if url:
             key = f'/library/metadata/{self.ratingKey}/clearLogos?url={quote_plus(url)}'
@@ -513,7 +513,7 @@ def uploadPoster(self, url=None, filepath=None):
 
             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.
+                filepath (str): The full file path to the image to upload or file-like object.
         """
         if url:
             key = f'/library/metadata/{self.ratingKey}/posters?url={quote_plus(url)}'
@@ -540,6 +540,71 @@ def deletePoster(self):
         return self
 
 
+class SquareArtUrlMixin:
+    """ Mixin for Plex objects that can have a square art url. """
+
+    @property
+    def squareArt(self):
+        """ Return the API path to the square art image. """
+        return next((i.url for i in self.images if i.type == 'backgroundSquare'), None)
+
+    @property
+    def squareArtUrl(self):
+        """ Return the square art url for the Plex object. """
+        return self._server.url(self.squareArt, includeToken=True) if self.squareArt else None
+
+
+class SquareArtLockMixin:
+    """ Mixin for Plex objects that can have a locked square art. """
+
+    def lockSquareArt(self):
+        """ Lock the square art for a Plex object. """
+        return self._edit(**{'squareArt.locked': 1})
+
+    def unlockSquareArt(self):
+        """ Unlock the square art for a Plex object. """
+        return self._edit(**{'squareArt.locked': 0})
+
+
+class SquareArtMixin(SquareArtUrlMixin, SquareArtLockMixin):
+    """ Mixin for Plex objects that can have square art. """
+
+    def squareArts(self):
+        """ Returns list of available :class:`~plexapi.media.SquareArt` objects. """
+        return self.fetchItems(f'/library/metadata/{self.ratingKey}/squareArts', cls=media.SquareArt)
+
+    def uploadSquareArt(self, url=None, filepath=None):
+        """ Upload a square art from a url or filepath.
+
+            Parameters:
+                url (str): The full URL to the image to upload.
+                filepath (str): The full file path to the image to upload or file-like object.
+        """
+        if url:
+            key = f'/library/metadata/{self.ratingKey}/squareArts?url={quote_plus(url)}'
+            self._server.query(key, method=self._server._session.post)
+        elif filepath:
+            key = f'/library/metadata/{self.ratingKey}/squareArts'
+            data = openOrRead(filepath)
+            self._server.query(key, method=self._server._session.post, data=data)
+        return self
+
+    def setSquareArt(self, squareArt):
+        """ Set the square art for a Plex object.
+
+            Parameters:
+                squareArt (:class:`~plexapi.media.SquareArt`): The square art object to select.
+        """
+        squareArt.select()
+        return self
+
+    def deleteSquareArt(self):
+        """ Delete the square art from a Plex object. """
+        key = f'/library/metadata/{self.ratingKey}/squareArt'
+        self._server.query(key, method=self._server._session.delete)
+        return self
+
+
 class ThemeUrlMixin:
     """ Mixin for Plex objects that can have a theme url. """