Mirrors/python-plexapi
2
0
Fork 0
mirror of https://github.com/pkkid/python-plexapi synced 2025-02-26 04:07:09 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update search doc strings fro advanced filters

Browse source
This commit is contained in:
JonnyWong16 2021-05-16 13:26:41 -07:00
parent 900dd3e7b9
commit 7b8757419b
No known key found for this signature in database
GPG key ID: B1F1F9807184697A
2 changed files with 41 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
docs/_static/images/LibrarySection.search_filters.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 667 KiB

53
plexapi/library.py
View file

@ -977,6 +977,7 @@ class LibrarySection(PlexObject):
:class:`~plexapi.video.Episode` objects) :class:`~plexapi.video.Episode` objects)
container_start (int, optional): Default 0. container_start (int, optional): Default 0.
container_size (int, optional): Default X_PLEX_CONTAINER_SIZE in your config file. container_size (int, optional): Default X_PLEX_CONTAINER_SIZE in your config file.
filters (dict): A dictionary of advanced filters. See the details below for more info.
**kwargs (dict): Additional custom filters to apply to the search results. **kwargs (dict): Additional custom filters to apply to the search results.
See the details below for more info. See the details below for more info.
@ -1060,22 +1061,22 @@ class LibrarySection(PlexObject):
In addition, if the filter does not exist for the default library type it will fallback to the most In addition, if the filter does not exist for the default library type it will fallback to the most
specific ``libtype`` available. For example, ``show.unwatched`` does not exists so it will fallback to specific ``libtype`` available. For example, ``show.unwatched`` does not exists so it will fallback to
``episode.unwatched``. The ``libtype`` prefix cannot be included directly in the function parameters so ``episode.unwatched``. The ``libtype`` prefix cannot be included directly in the function parameters so
the ``**kwargs`` must be provided as a dictionary. the filters must be provided as a filters dictionary.
Examples: Examples:
.. code-block:: python .. code-block:: python
library.search(**{"show.collection": "Documentary", "episode.inProgress": True}) library.search(filters={"show.collection": "Documentary", "episode.inProgress": True})
library.search(**{"artist.genre": "pop", "album.decade": 2000}) library.search(filters={"artist.genre": "pop", "album.decade": 2000})
# The following three options are identical and will return Episode objects # The following three options are identical and will return Episode objects
showLibrary.search(title="Winter is Coming", libtype='episode') showLibrary.search(title="Winter is Coming", libtype='episode')
showLibrary.search(libtype='episode', **{"episode.title": "Winter is Coming"}) showLibrary.search(libtype='episode', filters={"episode.title": "Winter is Coming"})
showLibrary.searchEpisodes(title="Winter is Coming") showLibrary.searchEpisodes(title="Winter is Coming")
# The following will search for the episode title but return Show objects # The following will search for the episode title but return Show objects
showLibrary.search(**{"episode.title": "Winter is Coming"}) showLibrary.search(filters={"episode.title": "Winter is Coming"})
# The following will fallback to episode.unwatched # The following will fallback to episode.unwatched
showLibrary.search(unwatched=True) showLibrary.search(unwatched=True)
@ -1122,27 +1123,55 @@ class LibrarySection(PlexObject):
* ``=``: ``is`` * ``=``: ``is``
Operators cannot be included directly in the function parameters so the ``**kwargs`` Operators cannot be included directly in the function parameters so the filters
must be provided as a dictionary. The trailing ``=`` on the operator may be excluded. must be provided as a filters dictionary. The trailing ``=`` on the operator may be excluded.
Examples: Examples:
.. code-block:: python .. code-block:: python
# Genre is horror AND thriller # Genre is horror AND thriller
library.search(**{"genre&": ["horror", "thriller"]}) library.search(filters={"genre&": ["horror", "thriller"]})
# Director is not Steven Spielberg # Director is not Steven Spielberg
library.search(**{"director!": "Steven Spielberg"}) library.search(filters={"director!": "Steven Spielberg"})
# Title starts with Marvel and added before 2021-01-01 # Title starts with Marvel and added before 2021-01-01
library.search(**{"title<": "Marvel", "addedAt<<": "2021-01-01"}) library.search(filters={"title<": "Marvel", "addedAt<<": "2021-01-01"})
# Added in the last 30 days using relative dates # Added in the last 30 days using relative dates
library.search(**{"addedAt>>": "30d"}) library.search(filters={"addedAt>>": "30d"})
# Collection is James Bond and user rating is greater than 8 # Collection is James Bond and user rating is greater than 8
library.search(**{"collection": "James Bond", "userRating>>": 8}) library.search(filters={"collection": "James Bond", "userRating>>": 8})
**Using Advanced Filters**
Any of the Plex filters described above can be combined into a single ``filters`` dictionary that mimics
the advanced filters used in Plex Web with a tree of ``and``/``or`` branches. Each level of the tree must
start with ``and`` (Match all of the following) or ``or`` (Match any of the following) as the dictionary
key, and a list of dictionaries with the desired filters as the dictionary value.
The following example matches `this <../_static/images/LibrarySection.search_filters.png>`__ advanced filter
in Plex Web.
Examples:
.. code-block:: python
advancedFilters = {
'and': [ # Match all of the following in this list
{
'or': [ # Match any of the following in this list
{'title': 'elephant'},
{'title': 'bunny'}
]
},
{'year>>': 1990},
{'unwatched': True}
]
}
library.search(filters=advancedFilters)
**Using PlexAPI Operators** **Using PlexAPI Operators**