Add support for Square Art (#1557)

* Add support for Square Art

* Add tests for square art

* Add square art to artist/album/track, collection, photoalbum/photo, playlist

* Add square art tests

* Add sqaureArt property

* Fix docstring typos

Author: JonnyWong16

plexapi/audio.py

@@ -12,7 +12,7 @@
 from plexapi.exceptions import BadRequest
 from plexapi.mixins import (
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, PlayedUnplayedMixin, RatingMixin,
-    ArtUrlMixin, ArtMixin, PosterUrlMixin, PosterMixin, ThemeMixin, ThemeUrlMixin,
+    ArtUrlMixin, ArtMixin, PosterUrlMixin, PosterMixin, SquareArtMixin, SquareArtUrlMixin, ThemeMixin, ThemeUrlMixin,
     ArtistEditMixins, AlbumEditMixins, TrackEditMixins
 )
 from plexapi.playlist import Playlist
@@ -181,7 +181,7 @@ def sonicallySimilar(
 class Artist(
     Audio,
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin,
-    ArtMixin, PosterMixin, ThemeMixin,
+    ArtMixin, PosterMixin, SquareArtMixin, ThemeMixin,
     ArtistEditMixins
 ):
     """ Represents a single Artist.
@@ -351,7 +351,7 @@ def metadataDirectory(self):
 class Album(
     Audio,
     SplitMergeMixin, UnmatchMatchMixin, RatingMixin,
-    ArtMixin, PosterMixin, ThemeUrlMixin,
+    ArtMixin, PosterMixin, SquareArtMixin, ThemeUrlMixin,
     AlbumEditMixins
 ):
     """ Represents a single Album.
@@ -504,7 +504,7 @@ def metadataDirectory(self):
 class Track(
     Audio, Playable,
     ExtrasMixin, RatingMixin,
-    ArtUrlMixin, PosterUrlMixin, ThemeUrlMixin,
+    ArtUrlMixin, PosterUrlMixin, SquareArtUrlMixin, ThemeUrlMixin,
     TrackEditMixins
 ):
     """ Represents a single Track.

plexapi/collection.py

@@ -8,7 +8,7 @@
 from plexapi.library import LibrarySection, ManagedHub
 from plexapi.mixins import (
     AdvancedSettingsMixin, SmartFilterMixin, HubsMixin, RatingMixin,
-    ArtMixin, PosterMixin, ThemeMixin,
+    ArtMixin, PosterMixin, SquareArtMixin, ThemeMixin,
     CollectionEditMixins
 )
 from plexapi.utils import deprecated
@@ -18,7 +18,7 @@
 class Collection(
     PlexPartialObject,
     AdvancedSettingsMixin, SmartFilterMixin, HubsMixin, RatingMixin,
-    ArtMixin, PosterMixin, ThemeMixin,
+    ArtMixin, PosterMixin, SquareArtMixin, ThemeMixin,
     CollectionEditMixins
 ):
     """ Represents a single Collection.

plexapi/media.py

@@ -1116,6 +1116,11 @@ class Poster(BaseResource):
     TAG = 'Photo'
 
 
+class SquareArt(BaseResource):
+    """ Represents a single Square Art object. """
+    TAG = 'Photo'
+
+
 class Theme(BaseResource):
     """ Represents a single Theme object. """
     TAG = 'Track'

plexapi/mixins.py

@@ -382,7 +382,7 @@ def uploadArt(self, url=None, filepath=None):
 
             Parameters:
                 url (str): The full URL to the image to upload.
-                filepath (str): The full file path the the image to upload or file-like object.
+                filepath (str): The full file path to the image to upload or file-like object.
         """
         if url:
             key = f'/library/metadata/{self.ratingKey}/arts?url={quote_plus(url)}'
@@ -437,7 +437,7 @@ def uploadLogo(self, url=None, filepath=None):
 
             Parameters:
                 url (str): The full URL to the image to upload.
-                filepath (str): The full file path the the image to upload or file-like object.
+                filepath (str): The full file path to the image to upload or file-like object.
         """
         if url:
             key = f'/library/metadata/{self.ratingKey}/clearLogos?url={quote_plus(url)}'
@@ -499,7 +499,7 @@ def uploadPoster(self, url=None, filepath=None):
 
             Parameters:
                 url (str): The full URL to the image to upload.
-                filepath (str): The full file path the the image to upload or file-like object.
+                filepath (str): The full file path to the image to upload or file-like object.
         """
         if url:
             key = f'/library/metadata/{self.ratingKey}/posters?url={quote_plus(url)}'
@@ -520,6 +520,71 @@ def setPoster(self, poster):
         return self
 
 
+class SquareArtUrlMixin:
+    """ Mixin for Plex objects that can have a square art url. """
+
+    @property
+    def squareArt(self):
+        """ Return the API path to the square art image. """
+        return next((i.url for i in self.images if i.type == 'backgroundSquare'), None)
+
+    @property
+    def squareArtUrl(self):
+        """ Return the square art url for the Plex object. """
+        return self._server.url(self.squareArt, includeToken=True) if self.squareArt else None
+
+
+class SquareArtLockMixin:
+    """ Mixin for Plex objects that can have a locked square art. """
+
+    def lockSquareArt(self):
+        """ Lock the square art for a Plex object. """
+        return self._edit(**{'squareArt.locked': 1})
+
+    def unlockSquareArt(self):
+        """ Unlock the square art for a Plex object. """
+        return self._edit(**{'squareArt.locked': 0})
+
+
+class SquareArtMixin(SquareArtUrlMixin, SquareArtLockMixin):
+    """ Mixin for Plex objects that can have square art. """
+
+    def squareArts(self):
+        """ Returns list of available :class:`~plexapi.media.SquareArt` objects. """
+        return self.fetchItems(f'/library/metadata/{self.ratingKey}/squareArts', cls=media.SquareArt)
+
+    def uploadSquareArt(self, url=None, filepath=None):
+        """ Upload a square art from a url or filepath.
+
+            Parameters:
+                url (str): The full URL to the image to upload.
+                filepath (str): The full file path to the image to upload or file-like object.
+        """
+        if url:
+            key = f'/library/metadata/{self.ratingKey}/squareArts?url={quote_plus(url)}'
+            self._server.query(key, method=self._server._session.post)
+        elif filepath:
+            key = f'/library/metadata/{self.ratingKey}/squareArts'
+            data = openOrRead(filepath)
+            self._server.query(key, method=self._server._session.post, data=data)
+        return self
+
+    def setSquareArt(self, squareArt):
+        """ Set the square art for a Plex object.
+
+            Parameters:
+                squareArt (:class:`~plexapi.media.SquareArt`): The square art object to select.
+        """
+        squareArt.select()
+        return self
+
+    def deleteSquareArt(self):
+        """ Delete the square art from a Plex object. """
+        key = f'/library/metadata/{self.ratingKey}/squareArt'
+        self._server.query(key, method=self._server._session.delete)
+        return self
+
+
 class ThemeUrlMixin:
     """ Mixin for Plex objects that can have a theme url. """
 

plexapi/photo.py

@@ -8,7 +8,7 @@
 from plexapi.exceptions import BadRequest
 from plexapi.mixins import (
     RatingMixin,
-    ArtUrlMixin, ArtMixin, PosterUrlMixin, PosterMixin,
+    ArtUrlMixin, ArtMixin, PosterUrlMixin, PosterMixin, SquareArtMixin, SquareArtUrlMixin,
     PhotoalbumEditMixins, PhotoEditMixins
 )
 
@@ -17,7 +17,7 @@
 class Photoalbum(
     PlexPartialObject,
     RatingMixin,
-    ArtMixin, PosterMixin,
+    ArtMixin, PosterMixin, SquareArtMixin,
     PhotoalbumEditMixins
 ):
     """ Represents a single Photoalbum (collection of photos).
@@ -159,7 +159,7 @@ def metadataDirectory(self):
 class Photo(
     PlexPartialObject, Playable,
     RatingMixin,
-    ArtUrlMixin, PosterUrlMixin,
+    ArtUrlMixin, PosterUrlMixin, SquareArtUrlMixin,
     PhotoEditMixins
 ):
     """ Represents a single Photo.

plexapi/playlist.py

@@ -8,15 +8,15 @@
 from plexapi.base import Playable, PlexPartialObject, cached_data_property
 from plexapi.exceptions import BadRequest, NotFound, Unsupported
 from plexapi.library import LibrarySection, MusicSection
-from plexapi.mixins import SmartFilterMixin, ArtMixin, PosterMixin, PlaylistEditMixins
+from plexapi.mixins import SmartFilterMixin, ArtMixin, PosterMixin, SquareArtMixin, PlaylistEditMixins
 from plexapi.utils import deprecated
 
 
 @utils.registerPlexObject
 class Playlist(
     PlexPartialObject, Playable,
     SmartFilterMixin,
-    ArtMixin, PosterMixin,
+    ArtMixin, PosterMixin, SquareArtMixin,
     PlaylistEditMixins
 ):
     """ Represents a single Playlist.

plexapi/utils.py

@@ -95,6 +95,7 @@
     'showOrdering': 322,
     'clearLogo': 323,
     'commonSenseMedia': 324,
+    'squareArt': 325,
     'place': 400,
     'sharedWidth': 500,
 }

plexapi/video.py

@@ -8,7 +8,8 @@
 from plexapi.exceptions import BadRequest
 from plexapi.mixins import (
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, PlayedUnplayedMixin, RatingMixin,
-    ArtUrlMixin, ArtMixin, LogoMixin, PosterUrlMixin, PosterMixin, ThemeUrlMixin, ThemeMixin,
+    ArtUrlMixin, ArtMixin, LogoMixin, LogoUrlMixin, PosterUrlMixin, PosterMixin, SquareArtMixin, SquareArtUrlMixin,
+    ThemeUrlMixin, ThemeMixin,
     MovieEditMixins, ShowEditMixins, SeasonEditMixins, EpisodeEditMixins,
     WatchlistMixin
 )
@@ -338,7 +339,7 @@ def sync(self, videoQuality, client=None, clientId=None, limit=None, unwatched=F
 class Movie(
     Video, Playable,
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin,
-    ArtMixin, LogoMixin, PosterMixin, ThemeMixin,
+    ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeMixin,
     MovieEditMixins,
     WatchlistMixin
 ):
@@ -550,7 +551,7 @@ def metadataDirectory(self):
 class Show(
     Video,
     AdvancedSettingsMixin, SplitMergeMixin, UnmatchMatchMixin, ExtrasMixin, HubsMixin, RatingMixin,
-    ArtMixin, LogoMixin, PosterMixin, ThemeMixin,
+    ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeMixin,
     ShowEditMixins,
     WatchlistMixin
 ):
@@ -802,7 +803,7 @@ def metadataDirectory(self):
 class Season(
     Video,
     AdvancedSettingsMixin, ExtrasMixin, RatingMixin,
-    ArtMixin, LogoMixin, PosterMixin, ThemeUrlMixin,
+    ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeUrlMixin,
     SeasonEditMixins
 ):
     """ Represents a single Season.
@@ -984,7 +985,7 @@ def metadataDirectory(self):
 class Episode(
     Video, Playable,
     ExtrasMixin, RatingMixin,
-    ArtMixin, LogoMixin, PosterMixin, ThemeUrlMixin,
+    ArtMixin, LogoMixin, PosterMixin, SquareArtMixin, ThemeUrlMixin,
     EpisodeEditMixins
 ):
     """ Represents a single Episode.
@@ -1260,7 +1261,7 @@ def metadataDirectory(self):
 @utils.registerPlexObject
 class Clip(
     Video, Playable,
-    ArtUrlMixin, PosterUrlMixin
+    ArtUrlMixin, LogoUrlMixin, PosterUrlMixin, SquareArtUrlMixin
 ):
     """ Represents a single Clip.
 

tests/test_audio.py

@@ -104,10 +104,13 @@ def test_audio_Artist_mixins_edit_advanced_settings(artist):
 def test_audio_Artist_mixins_images(artist):
     test_mixins.lock_art(artist)
     test_mixins.lock_poster(artist)
+    test_mixins.lock_square_art(artist)
     test_mixins.edit_art(artist)
     test_mixins.edit_poster(artist)
+    test_mixins.edit_square_art(artist)
     test_mixins.attr_artUrl(artist)
     test_mixins.attr_posterUrl(artist)
+    test_mixins.attr_squareArtUrl(artist)
 
 
 def test_audio_Artist_mixins_themes(artist):
@@ -234,10 +237,13 @@ def test_audio_Album_artist(album):
 def test_audio_Album_mixins_images(album):
     test_mixins.lock_art(album)
     test_mixins.lock_poster(album)
+    test_mixins.lock_square_art(album)
     test_mixins.edit_art(album)
     test_mixins.edit_poster(album)
+    test_mixins.edit_square_art(album)
     test_mixins.attr_artUrl(album)
     test_mixins.attr_posterUrl(album)
+    test_mixins.attr_squareArtUrl(album)
 
 
 def test_audio_Album_mixins_themes(album):
@@ -425,6 +431,7 @@ def test_audio_Track_sonicAdventure(account_plexpass, music):
 def test_audio_Track_mixins_images(track):
     test_mixins.attr_artUrl(track)
     test_mixins.attr_posterUrl(track)
+    test_mixins.attr_squareArtUrl(track)
 
 
 def test_audio_Track_mixins_themes(track):

tests/test_collection.py

@@ -353,10 +353,13 @@ def test_Collection_art(collection):
 def test_Collection_mixins_images(collection):
     test_mixins.lock_art(collection)
     test_mixins.lock_poster(collection)
+    test_mixins.lock_square_art(collection)
     test_mixins.edit_art(collection)
     test_mixins.edit_poster(collection)
+    test_mixins.edit_square_art(collection)
     test_mixins.attr_artUrl(collection)
     test_mixins.attr_posterUrl(collection)
+    test_mixins.attr_squareArtUrl(collection)
 
 
 def test_Collection_mixins_themes(collection):