Allow query parameters in LibrarySection.hubs() and add Playlist.centroid

* LibrarySection.hubs() now accepts optional query parameters
  (e.g. count=10, includeMyMixes=1), matching Library.hubs();
  includeStations=1 remains the default and may be overridden.
* Add Playlist.centroid returning the nested centroid Artist a
  personalized 'Mix For You' playlist is built around (its only
  artwork source), guarded against auto-reload on partial objects.

Author: ajacobson

plexapi/base.py

@@ -16,7 +16,7 @@
 MediaContainerT = TypeVar("MediaContainerT", bound="MediaContainer")
 
 USER_DONT_RELOAD_FOR_KEYS = set()
-_DONT_RELOAD_FOR_KEYS = {'key', 'sourceURI'}
+_DONT_RELOAD_FOR_KEYS = {'centroid', 'key', 'sourceURI'}
 OPERATORS = {
     'exact': lambda v, q: v == q,
     'iexact': lambda v, q: v.lower() == q.lower(),

plexapi/library.py

@@ -710,10 +710,17 @@ def resetManagedHubs(self):
         key = f'/hubs/sections/{self.key}/manage'
         self._server.query(key, method=self._server._session.delete)
 
-    def hubs(self):
+    def hubs(self, **kwargs):
         """ Returns a list of available :class:`~plexapi.library.Hub` for this library section.
+
+            Parameters:
+                **kwargs (dict): Optional query parameters to add to the request
+                    (e.g. ``count=10`` to limit the number of items per hub or
+                    ``includeMyMixes=1`` to include the personalized "Mixes For You" hub).
+                    ``includeStations=1`` is included by default and may be overridden.
         """
-        key = self._buildQueryKey(f'/hubs/sections/{self.key}', includeStations=1)
+        kwargs.setdefault('includeStations', 1)
+        key = self._buildQueryKey(f'/hubs/sections/{self.key}', **kwargs)
         return self.fetchItems(key)
 
     def agents(self):

plexapi/playlist.py

@@ -21,6 +21,8 @@ class Playlist(
             TYPE (str): 'playlist'
             addedAt (datetime): Datetime the playlist was added to the server.
             allowSync (bool): True if you allow syncing playlists.
+            centroid (:class:`~plexapi.audio.Artist`): The centroid artist a personalized
+                'Mix For You' playlist is built around, or None for regular playlists.
             composite (str): URL to composite image (/playlist/<ratingKey>/composite/<compositeid>)
             content (str): The filter URI string for smart playlists.
             duration (int): Duration of the playlist in milliseconds.
@@ -76,6 +78,11 @@ def _loadData(self, data):
     def fields(self):
         return self.findItems(self._data, media.Field)
 
+    @cached_data_property
+    def centroid(self):
+        from plexapi.audio import Artist
+        return self.findItem(self._data, cls=Artist, centroid='1')
+
     def __len__(self):  # pragma: no cover
         return len(self.items())
 

tests/payloads.py

@@ -44,3 +44,15 @@
 </Invite>
 </MediaContainer>
 """
+
+MUSIC_MIXES_HUB = """<MediaContainer size="2" identifier="com.plexapp.plugins.library" librarySectionID="1" librarySectionTitle="Music">
+<Hub hubIdentifier="music.mixes.1" context="hub.music.mixes" type="playlist" title="Mixes For You" size="1" more="0" style="shelf">
+<Playlist guid="" type="playlist" title="Centroid Mix" summary="" smart="1" playlistType="" icon="playlist://image.smart" leafCount="0" key="/library/sections/1/all?artist.id=&amp;or=1&amp;album.id=1,2,3">
+<Directory centroid="1" ratingKey="100" key="/library/metadata/100/children" guid="plex://artist/abc" type="artist" title="Centroid Artist" librarySectionTitle="Music" librarySectionID="1" librarySectionKey="/library/sections/1" thumb="/library/metadata/100/thumb/1"/>
+</Playlist>
+</Hub>
+<Hub hubIdentifier="music.playlists.1" context="hub.music.playlists" type="playlist" title="Playlists" size="1" more="0" style="shelf">
+<Playlist ratingKey="200" guid="com.plexapp.agents.none://xxx" type="playlist" title="Ordinary Playlist" summary="" smart="0" playlistType="audio" composite="/playlists/200/composite/1" leafCount="5" key="/playlists/200/items"/>
+</Hub>
+</MediaContainer>
+"""

tests/test_library.py

@@ -391,6 +391,13 @@ def test_library_MovieSection_PlexWebURL_hub(plex, movies):
     assert quote_plus(hub.key) in url
 
 
+def test_library_MusicSection_hubs_kwargs(music):
+    hubs = music.hubs(count=5)
+    assert hubs
+    for hub in hubs:
+        assert len(hub._partialItems) <= 5
+
+
 def test_library_ShowSection_all(tvshows):
     assert len(tvshows.all(title__iexact="The 100"))
 

tests/test_playlist.py

@@ -6,6 +6,7 @@
 
 from . import conftest as utils
 from . import test_mixins
+from .payloads import MUSIC_MIXES_HUB
 
 
 def test_Playlist_attrs(playlist):
@@ -31,6 +32,25 @@ def test_Playlist_attrs(playlist):
     assert playlist.isVideo is True
     assert playlist.isAudio is False
     assert playlist.isPhoto is False
+    assert playlist.centroid is None
+
+
+def test_Playlist_centroid(plex, music, requests_mock):
+    # 'Mix For You' playlists cannot be generated on the bootstrap server,
+    # so serve a representative hubs response and parse it through the normal path.
+    requests_mock.get(plex.url(f"/hubs/sections/{music.key}"), text=MUSIC_MIXES_HUB)
+    hubs = music.hubs(includeMyMixes=1)
+    mix = next(h for h in hubs if h.context == "hub.music.mixes").items()[0]
+    assert mix.smart is True
+    centroid = mix.centroid
+    assert centroid.type == "artist"
+    assert centroid.title == "Centroid Artist"
+    assert centroid.thumb == "/library/metadata/100/thumb/1"
+    # accessing centroid on a partial playlist without one must not trigger a reload
+    other = next(h for h in hubs if h.context == "hub.music.playlists").items()[0]
+    assert other.isPartialObject()
+    assert other.centroid is None
+    assert len(requests_mock.request_history) == 1
 
 
 def test_Playlist_create(plex, show):