Skip to content

Commit

Permalink
Document TagFilterInput. lemon24#328
Browse files Browse the repository at this point in the history
  • Loading branch information
@lemon24
lemon24 committed Dec 11, 2023
1 parent aa498be commit 852df1b
Show file tree
Hide file tree
Showing 3 changed files with 71 additions and 64 deletions.
1 change: 1 addition & 0 deletions docs/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,7 @@ The class hierarchy for :mod:`reader` exceptions is:
Type aliases
------------

.. autodata:: reader.types.TagFilterInput
.. autodata:: reader.types.TristateFilterInput


Expand Down
81 changes: 17 additions & 64 deletions src/reader/core.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -557,58 +557,11 @@ def get_feeds(
) -> Iterable[Feed]:
"""Get all or some of the feeds.
The ``tags`` argument can be a list of one or more feed tags.
Multiple tags are interpreted as a conjunction (AND).
To use a disjunction (OR), use a nested list.
To negate a tag, prefix the tag value with a minus sign (``-``).
Examples:
``['one']``
one
``['one', 'two']``
``[['one'], ['two']]``
one AND two
``[['one', 'two']]``
one OR two
``[['one', 'two'], 'three']``
(one OR two) AND three
``['one', '-two']``
one AND NOT two
Special values :const:`True` and :const:`False`
match feeds with any tags and no tags, respectively.
``True``
``[True]``
*any tags*
``False``
``[False]``
*no tags*
``[True, '-one']``
*any tags* AND NOT one
``[[False, 'one']]``
*no tags* OR one
Args:
feed (str or tuple(str) or Feed or None): Only return the feed with this URL.
tags (None or bool or list(str or bool or list(str or bool))):
Only return feeds matching these tags.
Only return feeds matching these tags;
see :data:`~reader.types.TagFilterInput` for details.
broken (bool or None): Only return broken / healthy feeds.
updates_enabled (bool or None):
Only return feeds that have updates enabled / disabled.
Expand Down Expand Up @@ -714,12 +667,11 @@ def get_feed_counts(
) -> FeedCounts:
"""Count all or some of the feeds.
See :meth:`~Reader.get_feeds()` for details on how filtering works.
Args:
feed (str or tuple(str) or Feed or None): Only count the feed with this URL.
tags (None or bool or list(str or bool or list(str or bool))):
Only count feeds matching these tags.
Only count feeds matching these tags;
see :data:`~reader.types.TagFilterInput` for details.
broken (bool or None): Only count broken / healthy feeds.
updates_enabled (bool or None):
Only count feeds that have updates enabled / disabled.
Expand Down Expand Up @@ -829,7 +781,8 @@ def update_feeds(
Args:
feed (str or tuple(str) or Feed or None): Only update the feed with this URL.
tags (None or bool or list(str or bool or list(str or bool))):
Only update feeds matching these tags.
Only update feeds matching these tags;
see :data:`~reader.types.TagFilterInput` for details.
broken (bool or None): Only update broken / healthy feeds.
updates_enabled (bool or None):
Only update feeds that have updates enabled / disabled.
Expand Down Expand Up @@ -944,7 +897,8 @@ def update_feeds_iter(
Args:
feed (str or tuple(str) or Feed or None): Only update the feed with this URL.
tags (None or bool or list(str or bool or list(str or bool))):
Only update feeds matching these tags.
Only update feeds matching these tags;
see :data:`~reader.types.TagFilterInput` for details.
broken (bool or None): Only update broken / healthy feeds.
updates_enabled (bool or None):
Only update feeds that have updates enabled / disabled.
Expand Down Expand Up @@ -1143,8 +1097,8 @@ def get_entries(
has_enclosures (bool or None): Only return entries that (don't)
have enclosures.
feed_tags (None or bool or list(str or bool or list(str or bool))):
Only return the entries from feeds matching these tags;
works like the :meth:`~Reader.get_feeds()` ``tags`` argument.
Only return entries from feeds matching these tags;
see :data:`~reader.types.TagFilterInput` for details.
sort (str): How to order entries; one of ``'recent'`` (default)
or ``'random'``.
limit (int or None): A limit on the number of entries to be returned;
Expand Down Expand Up @@ -1252,8 +1206,6 @@ def get_entry_counts(
) -> EntryCounts:
"""Count all or some of the entries.
See :meth:`~Reader.get_entries()` for details on how filtering works.
Args:
feed (str or tuple(str) or Feed or None): Only count the entries for this feed.
entry (tuple(str, str) or Entry or None):
Expand All @@ -1266,7 +1218,8 @@ def get_entry_counts(
has_enclosures (bool or None): Only count entries that (don't)
have enclosures.
feed_tags (None or bool or list(str or bool or list(str or bool))):
Only count the entries from feeds matching these tags.
Only count entries from feeds matching these tags;
see :data:`~reader.types.TagFilterInput` for details.
Returns:
EntryCounts:
Expand Down Expand Up @@ -1716,8 +1669,8 @@ def search_entries(
has_enclosures (bool or None): Only search entries that (don't)
have enclosures.
feed_tags (None or bool or list(str or bool or list(str or bool))):
Only return the entries from feeds matching these tags;
works like the :meth:`~Reader.get_feeds()` ``tags`` argument.
Only search entries from feeds matching these tags;
see :data:`~reader.types.TagFilterInput` for details.
sort (str): How to order results; one of ``'relevant'`` (default),
``'recent'``, or ``'random'``.
limit (int or None): A limit on the number of results to be returned;
Expand Down Expand Up @@ -1784,8 +1737,7 @@ def search_entry_counts(
) -> EntrySearchCounts:
"""Count entries matching a full-text search query.
See :meth:`~Reader.search_entries()` for details on how
the query syntax and filtering work.
See :meth:`~Reader.search_entries()` for details on the query syntax.
Search must be enabled to call this method.
Expand All @@ -1802,7 +1754,8 @@ def search_entry_counts(
has_enclosures (bool or None): Only count entries that (don't)
have enclosures.
feed_tags (None or bool or list(str or bool or list(str or bool))):
Only count the entries from feeds matching these tags.
Only count entries from feeds matching these tags;
see :data:`~reader.types.TagFilterInput` for details.
Returns:
EntrySearchCounts:
Expand Down
53 changes: 53 additions & 0 deletions src/reader/types.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -758,6 +758,59 @@ def _resource_argument(resource: ResourceInput) -> ResourceId:

# str explicitly excluded, to allow for a string-based query language;
# https://github.com/lemon24/reader/issues/184#issuecomment-689587006

#: Possible values for filtering resources by their tags.
#:
#: Tag filters consist of a list of one or more tags.
#: Multiple tags are interpreted as a conjunction (AND).
#: To use a disjunction (OR), use a nested list.
#: To negate a tag, prefix the tag value with a minus sign (``-``).
#: Examples:
#:
#: ``['one']``
#:
#: one
#:
#: ``['one', 'two']``
#: ``[['one'], ['two']]``
#:
#: one AND two
#:
#: ``[['one', 'two']]``
#:
#: one OR two
#:
#: ``[['one', 'two'], 'three']``
#:
#: (one OR two) AND three
#:
#: ``['one', '-two']``
#:
#: one AND NOT two
#:
#: Special values :const:`True` and :const:`False`
#: match resources with any tags and no tags, respectively.
#:
#: ``True``
#: ``[True]``
#:
#: *any tags*
#:
#: ``False``
#: ``[False]``
#:
#: *no tags*
#:
#: ``[True, '-one']``
#:
#: *any tags* AND NOT one
#:
#: ``[[False, 'one']]``
#:
#: *no tags* OR one
#:
#: .. versionadded:: 3.11
#:
TagFilterInput = Union[
None, bool, Sequence[Union[str, bool, Sequence[Union[str, bool]]]]
]
Expand Down

0 comments on commit 852df1b

Please sign in to comment.