Add new methods to edit object fields (#876)

* Update Collection.edit() method

* Add new EditFieldMixin and subclasses

* Add EditFieldMixin to Plex objects

* Update PlexPartialObject.edit() doc string

* Cast Track parentIndex to int

* Add base _searchTypes property

* Add kwargs to editField

* Editing album title also requires the artist ratingKey

* Add tests for editing fields

* Deprecate Collection.edit()

* Make editing fields chainable

* Add chaining example to doc string

* Add batch editing mode

* Add test for batchEdits

* Clean up mixins imports

* Reorder mixins

* Fix tests for batch edit

Author: JonnyWong16

plexapi/audio.py

@@ -5,11 +5,13 @@
 from plexapi import library, media, utils
 from plexapi.base import Playable, PlexPartialObject
 from plexapi.exceptions import BadRequest
-from plexapi.mixins import AdvancedSettingsMixin, ArtUrlMixin, ArtMixin, PosterUrlMixin, PosterMixin, ThemeMixin, \
-    ThemeUrlMixin
-from plexapi.mixins import RatingMixin, SplitMergeMixin, UnmatchMatchMixin
-from plexapi.mixins import CollectionMixin, CountryMixin, GenreMixin, LabelMixin, MoodMixin, SimilarArtistMixin, \
-    StyleMixin
+from plexapi.mixins import (
+    AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, RatingMixin,
+    ArtUrlMixin, ArtMixin, PosterUrlMixin, PosterMixin, ThemeMixin, ThemeUrlMixin,
+    OriginallyAvailableMixin, SortTitleMixin, StudioMixin, SummaryMixin, TitleMixin,
+    TrackArtistMixin, TrackDiscNumberMixin, TrackNumberMixin,
+    CollectionMixin, CountryMixin, GenreMixin, LabelMixin, MoodMixin, SimilarArtistMixin, StyleMixin
+)
 from plexapi.playlist import Playlist
 
 
@@ -127,9 +129,13 @@ def sync(self, bitrate, client=None, clientId=None, limit=None, title=None):
 
 
 @utils.registerPlexObject
-class Artist(Audio, AdvancedSettingsMixin, ArtMixin, PosterMixin, ThemeMixin, RatingMixin, SplitMergeMixin,
-             UnmatchMatchMixin, CollectionMixin, CountryMixin, GenreMixin, LabelMixin, MoodMixin,
-             SimilarArtistMixin, StyleMixin):
+class Artist(
+    Audio,
+    AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, RatingMixin,
+    ArtMixin, PosterMixin, ThemeMixin,
+    SortTitleMixin, SummaryMixin, TitleMixin,
+    CollectionMixin, CountryMixin, GenreMixin, LabelMixin, MoodMixin, SimilarArtistMixin, StyleMixin
+):
     """ Represents a single Artist.
 
         Attributes:
@@ -237,8 +243,13 @@ def station(self):
 
 
 @utils.registerPlexObject
-class Album(Audio, ArtMixin, PosterMixin, ThemeUrlMixin, RatingMixin, UnmatchMatchMixin,
-            CollectionMixin, GenreMixin, LabelMixin, MoodMixin, StyleMixin):
+class Album(
+    Audio,
+    UnmatchMatchMixin, RatingMixin,
+    ArtMixin, PosterMixin, ThemeUrlMixin,
+    OriginallyAvailableMixin, SortTitleMixin, StudioMixin, SummaryMixin, TitleMixin,
+    CollectionMixin, GenreMixin, LabelMixin, MoodMixin, StyleMixin
+):
     """ Represents a single Album.
 
         Attributes:
@@ -346,8 +357,13 @@ def _defaultSyncTitle(self):
 
 
 @utils.registerPlexObject
-class Track(Audio, Playable, ArtUrlMixin, PosterUrlMixin, ThemeUrlMixin, RatingMixin,
-        CollectionMixin, LabelMixin, MoodMixin):
+class Track(
+    Audio, Playable,
+    RatingMixin,
+    ArtUrlMixin, PosterUrlMixin, ThemeUrlMixin,
+    TitleMixin, TrackArtistMixin, TrackNumberMixin, TrackDiscNumberMixin,
+    CollectionMixin, LabelMixin, MoodMixin
+):
     """ Represents a single Track.
 
         Attributes:
@@ -369,7 +385,7 @@ class Track(Audio, Playable, ArtUrlMixin, PosterUrlMixin, ThemeUrlMixin, RatingM
             media (List<:class:`~plexapi.media.Media`>): List of media objects.
             originalTitle (str): The artist for the track.
             parentGuid (str): Plex GUID for the album (plex://album/5d07cd8e403c640290f180f9).
-            parentIndex (int): Album index.
+            parentIndex (int): Disc number of the track.
             parentKey (str): API URL of the album (/library/metadata/<parentRatingKey>).
             parentRatingKey (int): Unique key identifying the album.
             parentThumb (str): URL to album thumbnail image (/library/metadata/<parentRatingKey>/thumb/<thumbid>).
@@ -400,7 +416,7 @@ def _loadData(self, data):
         self.media = self.findItems(data, media.Media)
         self.originalTitle = data.attrib.get('originalTitle')
         self.parentGuid = data.attrib.get('parentGuid')
-        self.parentIndex = data.attrib.get('parentIndex')
+        self.parentIndex = utils.cast(int, data.attrib.get('parentIndex'))
         self.parentKey = data.attrib.get('parentKey')
         self.parentRatingKey = utils.cast(int, data.attrib.get('parentRatingKey'))
         self.parentThumb = data.attrib.get('parentThumb')

plexapi/base.py

@@ -54,6 +54,7 @@ def __init__(self, server, data, initpath=None, parent=None):
             self._loadData(data)
         self._details_key = self._buildDetailsKey()
         self._autoReload = False
+        self._edits = None  # Save batch edits for a single API call
 
     def __repr__(self):
         uid = self._clean(self.firstAttr('_baseurl', 'key', 'id', 'playQueueID', 'uri'))
@@ -419,6 +420,10 @@ def _castAttrValue(self, op, query, value):
     def _loadData(self, data):
         raise NotImplementedError('Abstract method not implemented.')
 
+    @property
+    def _searchType(self):
+        return self.TYPE
+
 
 class PlexPartialObject(PlexObject):
     """ Not all objects in the Plex listings return the complete list of elements
@@ -512,28 +517,79 @@ def isPartialObject(self):
 
     def _edit(self, **kwargs):
         """ Actually edit an object. """
+        if isinstance(self._edits, dict):
+            self._edits.update(kwargs)
+            return self
+
         if 'id' not in kwargs:
             kwargs['id'] = self.ratingKey
         if 'type' not in kwargs:
-            kwargs['type'] = utils.searchType(self.type)
+            kwargs['type'] = utils.searchType(self._searchType)
 
-        part = '/library/sections/%s/all?%s' % (self.librarySectionID,
-                                                urlencode(kwargs))
+        part = '/library/sections/%s/all%s' % (self.librarySectionID,
+                                               utils.joinArgs(kwargs))
         self._server.query(part, method=self._server._session.put)
+        return self
 
     def edit(self, **kwargs):
         """ Edit an object.
+            Note: This is a low level method and you need to know all the field/tag keys.
+            See :class:`~plexapi.mixins.EditFieldMixin` and :class:`~plexapi.mixins.EditTagsMixin`
+            for individual field and tag editing methods.
 
             Parameters:
                 kwargs (dict): Dict of settings to edit.
 
             Example:
-                {'type': 1,
-                 'id': movie.ratingKey,
-                 'collection[0].tag.tag': 'Super',
-                 'collection.locked': 0}
+
+                .. code-block:: python
+
+                    edits = {
+                        'type': 1,
+                        'id': movie.ratingKey,
+                        'title.value': 'A new title',
+                        'title.locked': 1,
+                        'summary.value': 'This is a summary.',
+                        'summary.locked': 1,
+                        'collection[0].tag.tag': 'A tag',
+                        'collection.locked': 1}
+                    }
+                    movie.edit(**edits)
+
         """
-        self._edit(**kwargs)
+        return self._edit(**kwargs)
+
+    def batchEdits(self):
+        """ Enable batch editing mode to save API calls.
+            Must call :func:`~plexapi.base.PlexPartialObject.saveEdits` at the end to save all the edits.
+            See :class:`~plexapi.mixins.EditFieldMixin` and :class:`~plexapi.mixins.EditTagsMixin`
+            for individual field and tag editing methods.
+
+            Example:
+
+                .. code-block:: python
+
+                    # Batch editing multiple fields and tags in a single API call
+                    Movie.batchEdits()
+                    Movie.editTitle('A New Title').editSummary('A new summary').editTagline('A new tagline') \\
+                        .addCollection('New Collection').removeGenre('Action').addLabel('Favorite')
+                    Movie.saveEdits()
+
+        """
+        self._edits = {}
+        return self
+
+    def saveEdits(self):
+        """ Save all the batch edits and automatically reload the object.
+            See :func:`~plexapi.base.PlexPartialObject.batchEdits` for details.
+        """
+        if not isinstance(self._edits, dict):
+            raise BadRequest('Batch editing mode not enabled. Must call `batchEdits()` first.')
+
+        edits = self._edits
+        self._edits = None
+        self._edit(**edits)
+        return self.reload()
 
     def _edit_tags(self, tag, items, locked=True, remove=False):
         """ Helper to edit tags.

plexapi/collection.py

@@ -5,15 +5,24 @@
 from plexapi.base import PlexPartialObject
 from plexapi.exceptions import BadRequest, NotFound, Unsupported
 from plexapi.library import LibrarySection
-from plexapi.mixins import AdvancedSettingsMixin, ArtMixin, PosterMixin, ThemeMixin, RatingMixin
-from plexapi.mixins import LabelMixin, SmartFilterMixin
+from plexapi.mixins import (
+    AdvancedSettingsMixin, SmartFilterMixin, RatingMixin,
+    ArtMixin, PosterMixin, ThemeMixin,
+    ContentRatingMixin, SortTitleMixin, SummaryMixin, TitleMixin,
+    LabelMixin
+)
 from plexapi.playqueue import PlayQueue
 from plexapi.utils import deprecated
 
 
 @utils.registerPlexObject
-class Collection(PlexPartialObject, AdvancedSettingsMixin, ArtMixin, PosterMixin, ThemeMixin, RatingMixin,
-                 LabelMixin, SmartFilterMixin):
+class Collection(
+    PlexPartialObject,
+    AdvancedSettingsMixin, SmartFilterMixin, RatingMixin,
+    ArtMixin, PosterMixin, ThemeMixin,
+    ContentRatingMixin, SortTitleMixin, SummaryMixin, TitleMixin,
+    LabelMixin
+):
     """ Represents a single Collection.
 
         Attributes:
@@ -343,6 +352,7 @@ def updateFilters(self, libtype=None, limit=None, sort=None, filters=None, **kwa
         }))
         self._server.query(key, method=self._server._session.put)
 
+    @deprecated('use editTitle, editSortTitle, editContentRating, and editSummary instead')
     def edit(self, title=None, titleSort=None, contentRating=None, summary=None, **kwargs):
         """ Edit the collection.
         
@@ -367,7 +377,7 @@ def edit(self, title=None, titleSort=None, contentRating=None, summary=None, **k
             args['summary.locked'] = 1
 
         args.update(kwargs)
-        super(Collection, self).edit(**args)
+        self._edit(**args)
 
     def delete(self):
         """ Delete the collection. """