Add edition support for movies (#1010)

* Add editionTitle to Movie attributes

* Add EditionTitleMixin to Movie

* Add tests for movie editionTitle

* Add `editions()` method to Movie

* Add test for movie editions method

Author: JonnyWong16

plexapi/mixins.py

@@ -569,6 +569,19 @@ def editContentRating(self, contentRating, locked=True):
         return self.editField('contentRating', contentRating, locked=locked)
 
 
+class EditionTitleMixin(EditFieldMixin):
+    """ Mixin for Plex objects that can have an edition title. """
+
+    def editEditionTitle(self, editionTitle, locked=True):
+        """ Edit the edition title. Plex Pass is required to edit this field.
+
+            Parameters:
+                editionTitle (str): The new value.
+                locked (bool): True (default) to lock the field, False to unlock the field.
+        """
+        return self.editField('editionTitle', editionTitle, locked=locked)
+
+
 class OriginallyAvailableMixin(EditFieldMixin):
     """ Mixin for Plex objects that can have an originally available date. """
 

plexapi/video.py

@@ -8,7 +8,7 @@
 from plexapi.mixins import (
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, PlayedUnplayedMixin, RatingMixin,
     ArtUrlMixin, ArtMixin, BannerMixin, PosterUrlMixin, PosterMixin, ThemeUrlMixin, ThemeMixin,
-    ContentRatingMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin,
+    ContentRatingMixin, EditionTitleMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin,
     SummaryMixin, TaglineMixin, TitleMixin,
     CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin,
     WatchlistMixin
@@ -291,7 +291,7 @@ class Movie(
     Video, Playable,
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin,
     ArtMixin, PosterMixin, ThemeMixin,
-    ContentRatingMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin,
+    ContentRatingMixin, EditionTitleMixin, OriginallyAvailableMixin, OriginalTitleMixin, SortTitleMixin, StudioMixin,
     SummaryMixin, TaglineMixin, TitleMixin,
     CollectionMixin, CountryMixin, DirectorMixin, GenreMixin, LabelMixin, ProducerMixin, WriterMixin,
     WatchlistMixin
@@ -310,6 +310,7 @@ class Movie(
             countries (List<:class:`~plexapi.media.Country`>): List of countries 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.).
             genres (List<:class:`~plexapi.media.Genre`>): List of genre objects.
             guids (List<:class:`~plexapi.media.Guid`>): List of guid objects.
             labels (List<:class:`~plexapi.media.Label`>): List of label objects.
@@ -350,6 +351,7 @@ def _loadData(self, data):
         self.countries = self.findItems(data, media.Country)
         self.directors = self.findItems(data, media.Director)
         self.duration = utils.cast(int, data.attrib.get('duration'))
+        self.editionTitle = data.attrib.get('editionTitle')
         self.genres = self.findItems(data, media.Genre)
         self.guids = self.findItems(data, media.Guid)
         self.labels = self.findItems(data, media.Label)
@@ -400,6 +402,16 @@ def reviews(self):
         data = self._server.query(self._details_key)
         return self.findItems(data, media.Review, rtag='Video')
 
+    def editions(self):
+        """ Returns a list of :class:`~plexapi.video.Movie` objects
+            for other editions of the same movie.
+        """
+        filters = {
+            'guid': self.guid,
+            'id!': self.ratingKey
+        }
+        return self.section().search(filters=filters)
+
 
 @utils.registerPlexObject
 class Show(

tests/test_mixins.py

@@ -46,6 +46,10 @@ def edit_content_rating(obj):
     _test_mixins_field(obj, "contentRating", "ContentRating")
 
 
+def edit_edition_title(obj):
+    _test_mixins_field(obj, "editionTitle", "EditionTitle")
+
+
 def edit_originally_available(obj):
     _test_mixins_field(obj, "originallyAvailableAt", "OriginallyAvailable")
 

tests/test_video.py

@@ -56,6 +56,7 @@ def test_video_Movie_attrs(movies):
     assert movie.chapterSource is None
     assert not movie.collections
     assert movie.contentRating in utils.CONTENTRATINGS
+    assert movie.editionTitle is None
     if movie.countries:
         assert "United States of America" in [i.tag for i in movie.countries]
     if movie.producers:
@@ -579,6 +580,10 @@ def test_video_Movie_reviews(movies):
     assert review.text
 
 
+def test_video_Movie_editions(movie):
+    assert len(movie.editions()) == 0
+
+
 @pytest.mark.authenticated
 def test_video_Movie_extras(movies):
     movie = movies.get("Sita Sings The Blues")
@@ -660,6 +665,13 @@ def test_video_Movie_mixins_fields(movie):
     test_mixins.edit_summary(movie)
     test_mixins.edit_tagline(movie)
     test_mixins.edit_title(movie)
+    with pytest.raises(BadRequest):
+        test_mixins.edit_edition_title(movie)
+
+
+@pytest.mark.authenticated
+def test_video_Movie_mixins_fields(movie):
+    test_mixins.edit_edition_title(movie)
 
 
 def test_video_Movie_mixins_tags(movie):