Ensure data parity for shows, seasons and episodes retrieved by search methods and member methods

[Touchstone64]

What is your feature request?

Searching in a Library Section retrieves partial objects that include Guids, which happens to be perfect for my use case — I don't need to reload any of my objects to get the guids, greatly improving my project's elapsed time. The member methods of the Plex objects returned don't follow this behaviour, though. It would be extremely useful, to me at the very least, for them all to behave the same way.

Technically speaking, in LibrarySection, the _buildSearchKey() method ensures guids are included in any partial objects returned by search(), by ensuring includeGuids=1 is in the parameter list unless the call specified includeGuids=0.

The ten member methods don't use this technique and adding includeGuids=1 in the call (i.e. as kwargs) is not supported. The ten methods are:

• Show.season(...)
• Show.seasons()
• Show.episode(...)
• Show.episodes()
• Season.episode(...)
• Season.episodes()
• Season.show()
• Episode._season()
• Episode.season()
• Episode.show()

This issue isn't really a bug, so I've filed it as a feature request. Please feel free to re-file it as best fits the repo.

Are there any workarounds?

I've tried using kwargs with the defined object methods but that doesn't behave as expected.

With two calls on the same populated Show instance, show, show.seasons() and show.seasons(includeGuids=1) return a list of the show's seasons and an empty list respectively, suggesting the kwargs aren't behaving as one might normally expect.

Code Snippets

from plexapi import utils

class TvParentChildMixin:
    """ Mixin for Plex objects that have parent/child relationships (episode/season/show). """

    def _buildRelationKey(self, key, **kwargs):
        """ Returns a key suitable for fetching parent/child TV items """
        args = {}

        args['includeGuids'] = int(bool(kwargs.pop('includeGuids', True)))
        for name, value in list(kwargs.items()):
            args[name] = value

        params = utils.joinArgs(args).lstrip('?')

        return f"{key}?{params}"

Additional Context

I'm currently working on a single key-building method that supports this behaviour (first-pass mixin code for Show, Season and Episode above) and aim to submit a pull request when it's ready.

[Touchstone64]

Examining the code in video.py, it's clear that the kwargs specified in calls to the defined object methods are used for property filters, not field inclusion specifiers. So they are behaving as expected, it's just that I was expecting the wrong behaviour 🤦

[JonnyWong16]

You can use LibrarySection.searchSeasons(filters={'show.id': show.ratingKey}) as a work around.

It would be nice to unify it so all the methods behave the same.

[Touchstone64]

Ah yes, that would fit the bill very nicely. As you say, unifying the methods would be very satisfying, and a nice self-contained task to get me back into contributing to the project. I'm just finishing off the unit tests to show me what I've missed then I'll raise the pull request :)

(PS thanks for such an awesome resource, PlexAPI is a treat to work with)