Merge pull request #693 from JonnyWong16/feature/library_search

Fix and update library searching

Author: Hellowlol

docs/_static/images/LibrarySection.listFilters.png

@@ -52,7 +52,7 @@ def _loadData(self, data):
         self.index = utils.cast(int, data.attrib.get('index'))
         self.key = data.attrib.get('key', '')
         self.lastViewedAt = utils.toDatetime(data.attrib.get('lastViewedAt'))
-        self.librarySectionID = data.attrib.get('librarySectionID')
+        self.librarySectionID = utils.cast(int, data.attrib.get('librarySectionID'))
         self.librarySectionKey = data.attrib.get('librarySectionKey')
         self.librarySectionTitle = data.attrib.get('librarySectionTitle')
         self.listType = 'audio'

docs/_static/images/LibrarySection.listSorts.png

@@ -144,34 +144,9 @@ def fetchItem(self, ekey, cls=None, **kwargs):
                     it only returns those items. By default we convert the xml elements
                     with the best guess PlexObjects based on tag and type attrs.
                 etag (str): Only fetch items with the specified tag.
-                **kwargs (dict): Optionally add attribute filters on the items to fetch. For
-                    example, passing in viewCount=0 will only return matching items. Filtering
-                    is done before the Python objects are built to help keep things speedy.
-                    Note: Because some attribute names are already used as arguments to this
-                    function, such as 'tag', you may still reference the attr tag byappending
-                    an underscore. For example, passing in _tag='foobar' will return all items
-                    where tag='foobar'. Also Note: Case very much matters when specifying kwargs
-                    -- Optionally, operators can be specified by append it
-                    to the end of the attribute name for more complex lookups. For example,
-                    passing in viewCount__gte=0 will return all items where viewCount >= 0.
-                    Available operations include:
-
-                    * __contains: Value contains specified arg.
-                    * __endswith: Value ends with specified arg.
-                    * __exact: Value matches specified arg.
-                    * __exists (bool): Value is or is not present in the attrs.
-                    * __gt: Value is greater than specified arg.
-                    * __gte: Value is greater than or equal to specified arg.
-                    * __icontains: Case insensative value contains specified arg.
-                    * __iendswith: Case insensative value ends with specified arg.
-                    * __iexact: Case insensative value matches specified arg.
-                    * __in: Value is in a specified list or tuple.
-                    * __iregex: Case insensative value matches the specified regular expression.
-                    * __istartswith: Case insensative value starts with specified arg.
-                    * __lt: Value is less than specified arg.
-                    * __lte: Value is less than or equal to specified arg.
-                    * __regex: Value matches the specified regular expression.
-                    * __startswith: Value starts with specified arg.
+                **kwargs (dict): Optionally add XML attribute to filter the items.
+                    See :func:`~plexapi.base.PlexObject.fetchItems` for more details
+                    on how this is used.
         """
         if ekey is None:
             raise BadRequest('ekey was not provided')
@@ -185,12 +160,76 @@ def fetchItem(self, ekey, cls=None, **kwargs):
 
     def fetchItems(self, ekey, cls=None, container_start=None, container_size=None, **kwargs):
         """ Load the specified key to find and build all items with the specified tag
-            and attrs. See :func:`~plexapi.base.PlexObject.fetchItem` for more details
-            on how this is used.
+            and attrs.
 
             Parameters:
+                ekey (str): API URL path in Plex to fetch items from.
+                cls (:class:`~plexapi.base.PlexObject`): If you know the class of the
+                    items to be fetched, passing this in will help the parser ensure
+                    it only returns those items. By default we convert the xml elements
+                    with the best guess PlexObjects based on tag and type attrs.
+                etag (str): Only fetch items with the specified tag.
                 container_start (None, int): offset to get a subset of the data
                 container_size (None, int): How many items in data
+                **kwargs (dict): Optionally add XML attribute to filter the items.
+                    See the details below for more info.
+
+            **Filtering XML Attributes**
+
+            Any XML attribute can be filtered when fetching results. Filtering is done before
+            the Python objects are built to help keep things speedy. For example, passing in
+            ``viewCount=0`` will only return matching items where the view count is ``0``.
+            Note that case matters when specifying attributes. Attributes futher down in the XML
+            tree can be filtered by *prepending* the attribute with each element tag ``Tag__``.
+
+            Examples:
+
+                .. code-block:: python
+
+                    fetchItem(ekey, viewCount=0)
+                    fetchItem(ekey, contentRating="PG")
+                    fetchItem(ekey, Genre__tag="Animation")
+                    fetchItem(ekey, Media__videoCodec="h265")
+                    fetchItem(ekey, Media__Part__container="mp4)
+
+            Note that because some attribute names are already used as arguments to this
+            function, such as ``tag``, you may still reference the attr tag by prepending an
+            underscore. For example, passing in ``_tag='foobar'`` will return all items where
+            ``tag='foobar'``.
+
+            **Using PlexAPI Operators**
+
+            Optionally, PlexAPI operators can be specified by *appending* it to the end of the
+            attribute for more complex lookups. For example, passing in ``viewCount__gte=0``
+            will return all items where ``viewCount >= 0``.
+
+            List of Available Operators:
+
+            * ``__contains``: Value contains specified arg.
+            * ``__endswith``: Value ends with specified arg.
+            * ``__exact``: Value matches specified arg.
+            * ``__exists`` (*bool*): Value is or is not present in the attrs.
+            * ``__gt``: Value is greater than specified arg.
+            * ``__gte``: Value is greater than or equal to specified arg.
+            * ``__icontains``: Case insensative value contains specified arg.
+            * ``__iendswith``: Case insensative value ends with specified arg.
+            * ``__iexact``: Case insensative value matches specified arg.
+            * ``__in``: Value is in a specified list or tuple.
+            * ``__iregex``: Case insensative value matches the specified regular expression.
+            * ``__istartswith``: Case insensative value starts with specified arg.
+            * ``__lt``: Value is less than specified arg.
+            * ``__lte``: Value is less than or equal to specified arg.
+            * ``__regex``: Value matches the specified regular expression.
+            * ``__startswith``: Value starts with specified arg.
+
+            Examples:
+
+                .. code-block:: python
+
+                    fetchItem(ekey, viewCount__gte=0)
+                    fetchItem(ekey, Media__container__in=["mp4", "mkv"])
+                    fetchItem(ekey, guid__iregex=r"(imdb:\/\/|themoviedb:\/\/)")
+                    fetchItem(ekey, Media__Part__file__startswith="D:\\Movies")
 
         """
         url_kw = {}
@@ -204,7 +243,7 @@ def fetchItems(self, ekey, cls=None, container_start=None, container_size=None,
         data = self._server.query(ekey, params=url_kw)
         items = self.findItems(data, cls, ekey, **kwargs)
 
-        librarySectionID = data.attrib.get('librarySectionID')
+        librarySectionID = utils.cast(int, data.attrib.get('librarySectionID'))
         if librarySectionID:
             for item in items:
                 item.librarySectionID = librarySectionID

docs/_static/images/LibrarySection.search.png

@@ -59,7 +59,7 @@ def _loadData(self, data):
         self.index = utils.cast(int, data.attrib.get('index'))
         self.key = data.attrib.get('key', '').replace('/children', '')  # FIX_BUG_50
         self.labels = self.findItems(data, media.Label)
-        self.librarySectionID = data.attrib.get('librarySectionID')
+        self.librarySectionID = utils.cast(int, data.attrib.get('librarySectionID'))
         self.librarySectionKey = data.attrib.get('librarySectionKey')
         self.librarySectionTitle = data.attrib.get('librarySectionTitle')
         self.maxYear = utils.cast(int, data.attrib.get('maxYear'))