Add return self to various methods to support chaining (#986)

* Add return self to various methods to support chaining

* Fix runButlerTask test

Author: JonnyWong16

plexapi/collection.py

@@ -234,7 +234,7 @@ def filterUserUpdate(self, user=None):
         key = user_dict.get(user)
         if key is None:
             raise BadRequest('Unknown collection filtering user: %s. Options %s' % (user, list(user_dict)))
-        self.editAdvanced(collectionFilterBasedOnUser=key)
+        return self.editAdvanced(collectionFilterBasedOnUser=key)
 
     def modeUpdate(self, mode=None):
         """ Update the collection mode advanced setting.
@@ -261,7 +261,7 @@ def modeUpdate(self, mode=None):
         key = mode_dict.get(mode)
         if key is None:
             raise BadRequest('Unknown collection mode: %s. Options %s' % (mode, list(mode_dict)))
-        self.editAdvanced(collectionMode=key)
+        return self.editAdvanced(collectionMode=key)
 
     def sortUpdate(self, sort=None):
         """ Update the collection order advanced setting.
@@ -289,7 +289,7 @@ def sortUpdate(self, sort=None):
         key = sort_dict.get(sort)
         if key is None:
             raise BadRequest('Unknown sort dir: %s. Options: %s' % (sort, list(sort_dict)))
-        self.editAdvanced(collectionSort=key)
+        return self.editAdvanced(collectionSort=key)
 
     def addItems(self, items):
         """ Add items to the collection.
@@ -321,6 +321,7 @@ def addItems(self, items):
             'uri': uri
         }))
         self._server.query(key, method=self._server._session.put)
+        return self
 
     def removeItems(self, items):
         """ Remove items from the collection.
@@ -341,6 +342,7 @@ def removeItems(self, items):
         for item in items:
             key = '%s/items/%s' % (self.key, item.ratingKey)
             self._server.query(key, method=self._server._session.delete)
+        return self
 
     def moveItem(self, item, after=None):
         """ Move an item to a new position in the collection.
@@ -363,6 +365,7 @@ def moveItem(self, item, after=None):
             key += '?after=%s' % after.ratingKey
 
         self._server.query(key, method=self._server._session.put)
+        return self
 
     def updateFilters(self, libtype=None, limit=None, sort=None, filters=None, **kwargs):
         """ Update the filters for a smart collection.
@@ -394,6 +397,7 @@ def updateFilters(self, libtype=None, limit=None, sort=None, filters=None, **kwa
             'uri': uri
         }))
         self._server.query(key, method=self._server._session.put)
+        return self
 
     @deprecated('use editTitle, editSortTitle, editContentRating, and editSummary instead')
     def edit(self, title=None, titleSort=None, contentRating=None, summary=None, **kwargs):

plexapi/library.py

@@ -150,40 +150,47 @@ def cleanBundles(self):
         """
         # TODO: Should this check the response for success or the correct mediaprefix?
         self._server.query('/library/clean/bundles?async=1', method=self._server._session.put)
+        return self
 
     def emptyTrash(self):
         """ If a library has items in the Library Trash, use this option to empty the Trash. """
         for section in self.sections():
             section.emptyTrash()
+        return self
 
     def optimize(self):
         """ The Optimize option cleans up the server database from unused or fragmented data.
             For example, if you have deleted or added an entire library or many items in a
             library, you may like to optimize the database.
         """
         self._server.query('/library/optimize?async=1', method=self._server._session.put)
+        return self
 
     def update(self):
         """ Scan this library for new items."""
         self._server.query('/library/sections/all/refresh')
+        return self
 
     def cancelUpdate(self):
         """ Cancel a library update. """
         key = '/library/sections/all/refresh'
         self._server.query(key, method=self._server._session.delete)
+        return self
 
     def refresh(self):
         """ Forces a download of fresh media information from the internet.
             This can take a long time. Any locked fields are not modified.
         """
         self._server.query('/library/sections/all/refresh?force=1')
+        return self
 
     def deleteMediaPreviews(self):
         """ Delete the preview thumbnails for the all sections. This cannot be
             undone. Recreating media preview files can take hours or even days.
         """
         for section in self.sections():
             section.deleteMediaPreviews()
+        return self
 
     def add(self, name='', type='', agent='', scanner='', location='', language='en', *args, **kwargs):
         """ Simplified add for the most common options.
@@ -549,6 +556,7 @@ def edit(self, agent=None, **kwargs):
 
         part = '/library/sections/%s?agent=%s&%s' % (self.key, agent, urlencode(params, doseq=True))
         self._server.query(part, method=self._server._session.put)
+        return self
 
     def addLocations(self, location):
         """ Add a location to a library.
@@ -570,7 +578,7 @@ def addLocations(self, location):
             if not self._server.isBrowsable(path):
                 raise BadRequest('Path: %s does not exist.' % path)
             locations.append(path)
-        self.edit(location=locations)
+        return self.edit(location=locations)
 
     def removeLocations(self, location):
         """ Remove a location from a library.
@@ -595,7 +603,7 @@ def removeLocations(self, location):
                 raise BadRequest('Path: %s does not exist in the library.' % location)
         if len(locations) == 0:
             raise BadRequest('You are unable to remove all locations from a library.')
-        self.edit(location=locations)
+        return self.edit(location=locations)
 
     def get(self, title):
         """ Returns the media item with the specified title.
@@ -718,7 +726,7 @@ def editAdvanced(self, **kwargs):
             else:
                 raise NotFound('%s not found in %s' % (value, enums))
 
-        self.edit(**data)
+        return self.edit(**data)
 
     def defaultAdvanced(self):
         """ Edit all of library's advanced settings to default. """
@@ -730,7 +738,7 @@ def defaultAdvanced(self):
             else:
                 data[key % setting.id] = setting.default
 
-        self.edit(**data)
+        return self.edit(**data)
 
     def _lockUnlockAllField(self, field, libtype=None, locked=True):
         """ Lock or unlock a field for all items in the library. """
@@ -741,6 +749,7 @@ def _lockUnlockAllField(self, field, libtype=None, locked=True):
         }
         key = '/library/sections/%s/all%s' % (self.key, utils.joinArgs(args))
         self._server.query(key, method=self._server._session.put)
+        return self
 
     def lockAllField(self, field, libtype=None):
         """ Lock a field for all items in the library.
@@ -750,7 +759,7 @@ def lockAllField(self, field, libtype=None):
                 libtype (str, optional): The library type to lock (movie, show, season, episode,
                     artist, album, track, photoalbum, photo). Default is the main library type.
         """
-        self._lockUnlockAllField(field, libtype=libtype, locked=True)
+        return self._lockUnlockAllField(field, libtype=libtype, locked=True)
 
     def unlockAllField(self, field, libtype=None):
         """ Unlock a field for all items in the library.
@@ -760,7 +769,7 @@ def unlockAllField(self, field, libtype=None):
                 libtype (str, optional): The library type to lock (movie, show, season, episode,
                     artist, album, track, photoalbum, photo). Default is the main library type.
         """
-        self._lockUnlockAllField(field, libtype=libtype, locked=False)
+        return self._lockUnlockAllField(field, libtype=libtype, locked=False)
 
     def timeline(self):
         """ Returns a timeline query for this library section. """
@@ -794,11 +803,13 @@ def analyze(self):
         """
         key = '/library/sections/%s/analyze' % self.key
         self._server.query(key, method=self._server._session.put)
+        return self
 
     def emptyTrash(self):
         """ If a section has items in the Trash, use this option to empty the Trash. """
         key = '/library/sections/%s/emptyTrash' % self.key
         self._server.query(key, method=self._server._session.put)
+        return self
 
     def update(self, path=None):
         """ Scan this section for new media.
@@ -810,25 +821,29 @@ def update(self, path=None):
         if path is not None:
             key += '?path=%s' % quote_plus(path)
         self._server.query(key)
+        return self
 
     def cancelUpdate(self):
         """ Cancel update of this Library Section. """
         key = '/library/sections/%s/refresh' % self.key
         self._server.query(key, method=self._server._session.delete)
+        return self
 
     def refresh(self):
         """ Forces a download of fresh media information from the internet.
             This can take a long time. Any locked fields are not modified.
         """
         key = '/library/sections/%s/refresh?force=1' % self.key
         self._server.query(key)
+        return self
 
     def deleteMediaPreviews(self):
         """ Delete the preview thumbnails for items in this library. This cannot
             be undone. Recreating media preview files can take hours or even days.
         """
         key = '/library/sections/%s/indexes' % self.key
         self._server.query(key, method=self._server._session.delete)
+        return self
 
     def _loadFilters(self):
         """ Retrieves and caches the list of :class:`~plexapi.library.FilteringType` and

plexapi/media.py

@@ -196,6 +196,7 @@ def setDefaultAudioStream(self, stream):
         else:
             key = "/library/parts/%d?audioStreamID=%d&allParts=1" % (self.id, stream)
         self._server.query(key, method=self._server._session.put)
+        return self
 
     def setDefaultSubtitleStream(self, stream):
         """ Set the default :class:`~plexapi.media.SubtitleStream` for this MediaPart.
@@ -208,11 +209,13 @@ def setDefaultSubtitleStream(self, stream):
         else:
             key = "/library/parts/%d?subtitleStreamID=%d&allParts=1" % (self.id, stream)
         self._server.query(key, method=self._server._session.put)
+        return self
 
     def resetDefaultSubtitleStream(self):
         """ Set default subtitle of this MediaPart to 'none'. """
         key = "/library/parts/%d?subtitleStreamID=0&allParts=1" % (self.id)
         self._server.query(key, method=self._server._session.put)
+        return self
 
 
 class MediaPartStream(PlexObject):

plexapi/mixins.py

@@ -49,6 +49,7 @@ def editAdvanced(self, **kwargs):
                 raise NotFound('%s not found in %s' % (value, list(enumValues)))
         url = key + urlencode(data)
         self._server.query(url, method=self._server._session.put)
+        return self
 
     def defaultAdvanced(self):
         """ Edit all of a Plex object's advanced settings to default. """
@@ -58,6 +59,7 @@ def defaultAdvanced(self):
             data[preference.id] = preference.default
         url = key + urlencode(data)
         self._server.query(url, method=self._server._session.put)
+        return self
 
 
 class SmartFilterMixin:
@@ -126,7 +128,8 @@ class SplitMergeMixin:
     def split(self):
         """ Split duplicated Plex object into separate objects. """
         key = f'{self.key}/split'
-        return self._server.query(key, method=self._server._session.put)
+        self._server.query(key, method=self._server._session.put)
+        return self
 
     def merge(self, ratingKeys):
         """ Merge other Plex objects into the current object.
@@ -138,7 +141,8 @@ def merge(self, ratingKeys):
             ratingKeys = str(ratingKeys).split(',')
 
         key = '%s/merge?ids=%s' % (self.key, ','.join([str(r) for r in ratingKeys]))
-        return self._server.query(key, method=self._server._session.put)
+        self._server.query(key, method=self._server._session.put)
+        return self
 
 
 class UnmatchMatchMixin:
@@ -232,6 +236,7 @@ def fixMatch(self, searchResult=None, auto=False, agent=None):
 
         data = key + '?' + urlencode(params)
         self._server.query(data, method=self._server._session.put)
+        return self
 
 
 class ExtrasMixin:
@@ -312,6 +317,7 @@ def rate(self, rating=None):
             raise BadRequest('Rating must be between 0 to 10.')
         key = '/:/rate?key=%s&identifier=com.plexapp.plugins.library&rating=%s' % (self.ratingKey, rating)
         self._server.query(key, method=self._server._session.put)
+        return self
 
 
 class ArtUrlMixin:
@@ -345,6 +351,7 @@ def uploadArt(self, url=None, filepath=None):
             key = f'/library/metadata/{self.ratingKey}/arts'
             data = open(filepath, 'rb').read()
             self._server.query(key, method=self._server._session.post, data=data)
+        return self
 
     def setArt(self, art):
         """ Set the background artwork for a Plex object.
@@ -353,6 +360,7 @@ def setArt(self, art):
                 art (:class:`~plexapi.media.Art`): The art object to select.
         """
         art.select()
+        return self
 
     def lockArt(self):
         """ Lock the background artwork for a Plex object. """
@@ -394,6 +402,7 @@ def uploadBanner(self, url=None, filepath=None):
             key = f'/library/metadata/{self.ratingKey}/banners'
             data = open(filepath, 'rb').read()
             self._server.query(key, method=self._server._session.post, data=data)
+        return self
 
     def setBanner(self, banner):
         """ Set the banner for a Plex object.
@@ -402,6 +411,7 @@ def setBanner(self, banner):
                 banner (:class:`~plexapi.media.Banner`): The banner object to select.
         """
         banner.select()
+        return self
 
     def lockBanner(self):
         """ Lock the banner for a Plex object. """
@@ -448,6 +458,7 @@ def uploadPoster(self, url=None, filepath=None):
             key = f'/library/metadata/{self.ratingKey}/posters'
             data = open(filepath, 'rb').read()
             self._server.query(key, method=self._server._session.post, data=data)
+        return self
 
     def setPoster(self, poster):
         """ Set the poster for a Plex object.
@@ -456,6 +467,7 @@ def setPoster(self, poster):
                 poster (:class:`~plexapi.media.Poster`): The poster object to select.
         """
         poster.select()
+        return self
 
     def lockPoster(self):
         """ Lock the poster for a Plex object. """
@@ -499,6 +511,7 @@ def uploadTheme(self, url=None, filepath=None):
             key = f'/library/metadata/{self.ratingKey}/themes'
             data = open(filepath, 'rb').read()
             self._server.query(key, method=self._server._session.post, data=data)
+        return self
 
     def setTheme(self, theme):
         raise NotImplementedError(
@@ -508,11 +521,11 @@ def setTheme(self, theme):
 
     def lockTheme(self):
         """ Lock the theme for a Plex object. """
-        self._edit(**{'theme.locked': 1})
+        return self._edit(**{'theme.locked': 1})
 
     def unlockTheme(self):
         """ Unlock the theme for a Plex object. """
-        self._edit(**{'theme.locked': 0})
+        return self._edit(**{'theme.locked': 0})
 
 
 class EditFieldMixin:
@@ -1056,6 +1069,7 @@ def addToWatchlist(self, account=None):
         except AttributeError:
             account = self._server
         account.addToWatchlist(self)
+        return self
 
     def removeFromWatchlist(self, account=None):
         """ Remove this item from the specified user's watchlist.
@@ -1070,6 +1084,7 @@ def removeFromWatchlist(self, account=None):
         except AttributeError:
             account = self._server
         account.removeFromWatchlist(self)
+        return self
 
     def streamingServices(self, account=None):
         """ Return a list of :class:`~plexapi.media.Availability`

plexapi/myplex.py

@@ -832,6 +832,7 @@ def addToWatchlist(self, items):
                 raise BadRequest('"%s" is already on the watchlist' % item.title)
             ratingKey = item.guid.rsplit('/', 1)[-1]
             self.query(f'{self.METADATA}/actions/addToWatchlist?ratingKey={ratingKey}', method=self._session.put)
+        return self
 
     def removeFromWatchlist(self, items):
         """ Remove media items from the user's watchlist
@@ -852,6 +853,7 @@ def removeFromWatchlist(self, items):
                 raise BadRequest('"%s" is not on the watchlist' % item.title)
             ratingKey = item.guid.rsplit('/', 1)[-1]
             self.query(f'{self.METADATA}/actions/removeFromWatchlist?ratingKey={ratingKey}', method=self._session.put)
+        return self
 
     def userState(self, item):
         """ Returns a :class:`~plexapi.myplex.UserState` object for the specified item.