Add support for Common Sense Media

Author: JonnyWong16

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
@@ -1366,3 +1366,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[0]
+                    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 hub. """
+        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/video.py

@@ -349,11 +349,12 @@ class Movie(
             TYPE (str): 'movie'
             audienceRating (float): Audience rating (usually from Rotten Tomatoes).
             audienceRatingImage (str): Key to audience rating image (rottentomatoes://image.rating.spilled).
-            chapters (List<:class:`~plexapi.media.Chapter`>): List of Chapter objects.
+            chapters (List<:class:`~plexapi.media.Chapter`>): List of chapter objects.
             chapterSource (str): Chapter source (agent; media; mixed).
             collections (List<:class:`~plexapi.media.Collection`>): List of collection objects.
+            commonSenseMedia (List<:class:`~plexapi.media.CommonSenseMedia`>): List of Common Sense Media objects.
             contentRating (str) Content rating (PG-13; NR; TV-G).
-            countries (List<:class:`~plexapi.media.Country`>): List of countries objects.
+            countries (List<:class:`~plexapi.media.Country`>): List of country objects.
             directors (List<:class:`~plexapi.media.Director`>): List of director objects.
             duration (int): Duration of the movie in milliseconds.
             editionTitle (str): The edition title of the movie (e.g. Director's Cut, Extended Edition, etc.).
@@ -426,6 +427,10 @@ def chapters(self):
     def collections(self):
         return self.findItems(self._data, media.Collection)
 
+    @cached_data_property
+    def commonSenseMedia(self):
+        return self.findItems(self._data, media.CommonSenseMedia)
+
     @cached_data_property
     def countries(self):
         return self.findItems(self._data, media.Country)
@@ -566,6 +571,7 @@ class Show(
                 100 = On next refresh).
             childCount (int): Number of seasons (including Specials) in the show.
             collections (List<:class:`~plexapi.media.Collection`>): List of collection objects.
+            commonSenseMedia (List<:class:`~plexapi.media.CommonSenseMedia`>): List of Common Sense Media objects.
             contentRating (str) Content rating (PG-13; NR; TV-G).
             duration (int): Typical duration of the show episodes in milliseconds.
             enableCreditsMarkerGeneration (int): Setting that indicates if credits markers detection is enabled.
@@ -651,6 +657,10 @@ def _loadData(self, data):
     def collections(self):
         return self.findItems(self._data, media.Collection)
 
+    @cached_data_property
+    def commonSenseMedia(self):
+        return self.findItems(self._data, media.CommonSenseMedia)
+
     @cached_data_property
     def genres(self):
         return self.findItems(self._data, media.Genre)
@@ -984,7 +994,7 @@ class Episode(
             TYPE (str): 'episode'
             audienceRating (float): Audience rating (TMDB or TVDB).
             audienceRatingImage (str): Key to audience rating image (tmdb://image.rating).
-            chapters (List<:class:`~plexapi.media.Chapter`>): List of Chapter objects.
+            chapters (List<:class:`~plexapi.media.Chapter`>): List of chapter objects.
             chapterSource (str): Chapter source (agent; media; mixed).
             collections (List<:class:`~plexapi.media.Collection`>): List of collection objects.
             contentRating (str) Content rating (PG-13; NR; TV-G).