Add support for using MediaTag objects when editing tags (#994)

* Support using MediaTag objects when editing tags

* Update tests for editing tags with MediaTag objects

Author: JonnyWong16

plexapi/media.py

@@ -676,6 +676,10 @@ class MediaTag(PlexObject):
             thumb (str): URL to thumbnail image for :class:`~plexapi.media.Role` only.
     """
 
+    def __str__(self):
+        """ Returns the tag name. """
+        return self.tag
+
     def _loadData(self, data):
         """ Load attribute values from Plex XML response. """
         self._data = data

plexapi/mixins.py

@@ -549,8 +549,8 @@ def editField(self, field, value, locked=True, **kwargs):
 
         """
         edits = {
-            '%s.value' % field: value or '',
-            '%s.locked' % field: 1 if locked else 0
+            f'{field}.value': value or '',
+            f'{field}.locked': 1 if locked else 0
         }
         edits.update(kwargs)
         return self._edit(**edits)
@@ -733,7 +733,7 @@ def editTags(self, tag, items, locked=True, remove=False, **kwargs):
 
             Parameters:
                 tag (str): Name of the tag to edit.
-                items (List<str>): List of tags to add or remove.
+                items (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags to add or remove.
                 locked (bool): True (default) to lock the tags, False to unlock the tags.
                 remove (bool): True to remove the tags in items.
 
@@ -748,9 +748,11 @@ def editTags(self, tag, items, locked=True, remove=False, **kwargs):
         if not isinstance(items, list):
             items = [items]
 
-        value = getattr(self, self._tagPlural(tag))
-        existing_tags = [t.tag for t in value if t and remove is False]
-        edits = self._tagHelper(self._tagSingular(tag), existing_tags + items, locked, remove)
+        if not remove:
+            tags = getattr(self, self._tagPlural(tag))
+            items = tags + items
+
+        edits = self._tagHelper(self._tagSingular(tag), items, locked, remove)
         edits.update(kwargs)
         return self._edit(**edits)
 
@@ -783,15 +785,15 @@ def _tagHelper(tag, items, locked=True, remove=False):
             items = [items]
 
         data = {
-            '%s.locked' % tag: 1 if locked else 0
+            f'{tag}.locked': 1 if locked else 0
         }
 
         if remove:
-            tagname = '%s[].tag.tag-' % tag
-            data[tagname] = ','.join(items)
+            tagname = f'{tag}[].tag.tag-'
+            data[tagname] = ','.join([str(t) for t in items])
         else:
             for i, item in enumerate(items):
-                tagname = '%s[%s].tag.tag' % (tag, i)
+                tagname = f'{str(tag)}[{i}].tag.tag'
                 data[tagname] = item
 
         return data
@@ -804,7 +806,7 @@ def addCollection(self, collections, locked=True):
         """ Add a collection tag(s).
 
             Parameters:
-                collections (list): List of strings.
+                collections (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('collection', collections, locked=locked)
@@ -813,7 +815,7 @@ def removeCollection(self, collections, locked=True):
         """ Remove a collection tag(s).
 
             Parameters:
-                collections (list): List of strings.
+                collections (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('collection', collections, locked=locked, remove=True)
@@ -826,7 +828,7 @@ def addCountry(self, countries, locked=True):
         """ Add a country tag(s).
 
             Parameters:
-                countries (list): List of strings.
+                countries (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('country', countries, locked=locked)
@@ -835,7 +837,7 @@ def removeCountry(self, countries, locked=True):
         """ Remove a country tag(s).
 
             Parameters:
-                countries (list): List of strings.
+                countries (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('country', countries, locked=locked, remove=True)
@@ -848,7 +850,7 @@ def addDirector(self, directors, locked=True):
         """ Add a director tag(s).
 
             Parameters:
-                directors (list): List of strings.
+                directors (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('director', directors, locked=locked)
@@ -857,7 +859,7 @@ def removeDirector(self, directors, locked=True):
         """ Remove a director tag(s).
 
             Parameters:
-                directors (list): List of strings.
+                directors (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('director', directors, locked=locked, remove=True)
@@ -870,7 +872,7 @@ def addGenre(self, genres, locked=True):
         """ Add a genre tag(s).
 
             Parameters:
-                genres (list): List of strings.
+                genres (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('genre', genres, locked=locked)
@@ -879,7 +881,7 @@ def removeGenre(self, genres, locked=True):
         """ Remove a genre tag(s).
 
             Parameters:
-                genres (list): List of strings.
+                genres (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('genre', genres, locked=locked, remove=True)
@@ -892,7 +894,7 @@ def addLabel(self, labels, locked=True):
         """ Add a label tag(s).
 
             Parameters:
-                labels (list): List of strings.
+                labels (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('label', labels, locked=locked)
@@ -901,7 +903,7 @@ def removeLabel(self, labels, locked=True):
         """ Remove a label tag(s).
 
             Parameters:
-                labels (list): List of strings.
+                labels (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('label', labels, locked=locked, remove=True)
@@ -914,7 +916,7 @@ def addMood(self, moods, locked=True):
         """ Add a mood tag(s).
 
             Parameters:
-                moods (list): List of strings.
+                moods (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('mood', moods, locked=locked)
@@ -923,7 +925,7 @@ def removeMood(self, moods, locked=True):
         """ Remove a mood tag(s).
 
             Parameters:
-                moods (list): List of strings.
+                moods (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('mood', moods, locked=locked, remove=True)
@@ -936,7 +938,7 @@ def addProducer(self, producers, locked=True):
         """ Add a producer tag(s).
 
             Parameters:
-                producers (list): List of strings.
+                producers (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('producer', producers, locked=locked)
@@ -945,7 +947,7 @@ def removeProducer(self, producers, locked=True):
         """ Remove a producer tag(s).
 
             Parameters:
-                producers (list): List of strings.
+                producers (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('producer', producers, locked=locked, remove=True)
@@ -958,7 +960,7 @@ def addSimilarArtist(self, artists, locked=True):
         """ Add a similar artist tag(s).
 
             Parameters:
-                artists (list): List of strings.
+                artists (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('similar', artists, locked=locked)
@@ -967,7 +969,7 @@ def removeSimilarArtist(self, artists, locked=True):
         """ Remove a similar artist tag(s).
 
             Parameters:
-                artists (list): List of strings.
+                artists (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('similar', artists, locked=locked, remove=True)
@@ -980,7 +982,7 @@ def addStyle(self, styles, locked=True):
         """ Add a style tag(s).
 
             Parameters:
-                styles (list): List of strings.
+                styles (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('style', styles, locked=locked)
@@ -989,7 +991,7 @@ def removeStyle(self, styles, locked=True):
         """ Remove a style tag(s).
 
             Parameters:
-                styles (list): List of strings.
+                styles (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('style', styles, locked=locked, remove=True)
@@ -1002,7 +1004,7 @@ def addTag(self, tags, locked=True):
         """ Add a tag(s).
 
             Parameters:
-                tags (list): List of strings.
+                tags (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('tag', tags, locked=locked)
@@ -1011,7 +1013,7 @@ def removeTag(self, tags, locked=True):
         """ Remove a tag(s).
 
             Parameters:
-                tags (list): List of strings.
+                tags (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('tag', tags, locked=locked, remove=True)
@@ -1024,7 +1026,7 @@ def addWriter(self, writers, locked=True):
         """ Add a writer tag(s).
 
             Parameters:
-                writers (list): List of strings.
+                writers (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('writer', writers, locked=locked)
@@ -1033,7 +1035,7 @@ def removeWriter(self, writers, locked=True):
         """ Remove a writer tag(s).
 
             Parameters:
-                writers (list): List of strings.
+                writers (List<str> or List<:class:`~plexapi.media.MediaTag`>): List of tags.
                 locked (bool): True (default) to lock the field, False to unlock the field.
         """
         return self.editTags('writer', writers, locked=locked, remove=True)

tests/test_mixins.py

@@ -96,17 +96,33 @@ def _test_mixins_tag(obj, attr, tag_method):
     field_name = obj._tagSingular(attr)
     _tags = lambda: [t.tag for t in getattr(obj, attr)]
     _fields = lambda: [f for f in obj.fields if f.name == field_name]
+
     # Check tag is not present to begin with
     tags = _tags()
     assert TEST_MIXIN_TAG not in tags
-    # Add tag and lock the field
+
+    # Add tag string and lock the field
     add_tag_method(TEST_MIXIN_TAG)
     obj.reload()
     tags = _tags()
     fields = _fields()
     assert TEST_MIXIN_TAG in tags
     assert fields and fields[0].locked
-    # Remove tag and unlock to field to restore the clean state
+
+    # Remove MediaTag object
+    mediaTag = next(t for t in getattr(obj, attr) if t.tag == TEST_MIXIN_TAG)
+    remove_tag_method(mediaTag)
+    obj.reload()
+    tags = _tags()
+    assert TEST_MIXIN_TAG not in tags
+
+    # Add MediaTag object
+    add_tag_method(mediaTag)
+    obj.reload()
+    tags = _tags()
+    assert TEST_MIXIN_TAG in tags
+
+    # Remove tag string and unlock to field to restore the clean state
     remove_tag_method(TEST_MIXIN_TAG, locked=False)
     obj.reload()
     tags = _tags()