get_entries(important: TristateFilter), also search_entries() and counts.

For #254.

Author: lemon24

src/reader/_storage.py

@@ -1417,6 +1417,16 @@ def entry_factory(t: tuple[Any, ...]) -> Entry:
     return Entry._make(entry)
 
 
+TRISTATE_FILTER_TO_SQL = dict(
+    istrue="({expr} IS NOT NULL AND {expr})",
+    isfalse="({expr} IS NOT NULL AND NOT {expr})",
+    notset="{expr} IS NULL",
+    nottrue="({expr} IS NULL OR NOT {expr})",
+    notfalse="({expr} IS NULL OR {expr})",
+    isset="{expr} IS NOT NULL",
+)
+
+
 def apply_entry_filter_options(
     query: Query, filter_options: EntryFilterOptions, keyword: str = 'WHERE'
 ) -> dict[str, Any]:
@@ -1435,10 +1445,8 @@ def apply_entry_filter_options(
     if read is not None:
         add(f"{'' if read else 'NOT'} entries.read")
 
-    if important is not None:
-        add(
-            f"{'' if important else 'NOT'} (entries.important IS NOT NULL AND entries.important)"
-        )
+    if important != 'any':
+        add(TRISTATE_FILTER_TO_SQL[important].format(expr='entries.important'))
 
     if has_enclosures is not None:
         add(

src/reader/_types.py

@@ -10,6 +10,8 @@
 from types import MappingProxyType
 from types import SimpleNamespace
 from typing import Any
+from typing import get_args
+from typing import Literal
 from typing import NamedTuple
 from typing import TypeVar
 from typing import Union
@@ -27,6 +29,7 @@
 from .types import Feed
 from .types import FeedInput
 from .types import TagFilterInput
+from .types import TristateFilterInput
 
 # Private API
 # https://github.com/lemon24/reader/issues/111
@@ -388,6 +391,31 @@ def normalize_tag(tag: str | bool) -> bool | tuple[bool, str]:
     return rv
 
 
+TristateFilter = Literal[
+    'istrue',
+    'isfalse',
+    'notset',
+    'nottrue',
+    'notfalse',
+    'isset',
+    'any',
+]
+
+
+def tristate_filter_argument(value: TristateFilterInput, name: str) -> TristateFilter:
+    # https://github.com/lemon24/reader/issues/254#issuecomment-1435648359
+    if value is None:
+        return 'any'
+    if value == True:  # noqa: E712
+        return 'istrue'
+    if value == False:  # noqa: E712
+        return 'nottrue'
+    args = get_args(TristateFilter)
+    if value in args:
+        return value
+    raise ValueError(f"{name} must be none, bool, or one of {args}")
+
+
 _EFO = TypeVar('_EFO', bound='EntryFilterOptions')
 
 
@@ -398,7 +426,7 @@ class EntryFilterOptions(NamedTuple):
     feed_url: str | None = None
     entry_id: str | None = None
     read: bool | None = None
-    important: bool | None = None
+    important: TristateFilter = 'any'
     has_enclosures: bool | None = None
     feed_tags: TagFilter = ()
 
@@ -408,7 +436,7 @@ def from_args(
         feed: FeedInput | None = None,
         entry: EntryInput | None = None,
         read: bool | None = None,
-        important: bool | None = None,
+        important: TristateFilterInput = None,
         has_enclosures: bool | None = None,
         feed_tags: TagFilterInput = None,
     ) -> _EFO:
@@ -422,14 +450,16 @@ def from_args(
 
         if read not in (None, False, True):
             raise ValueError("read should be one of (None, False, True)")
-        if important not in (None, False, True):
-            raise ValueError("important should be one of (None, False, True)")
+
+        important_filter = tristate_filter_argument(important, 'important')
         if has_enclosures not in (None, False, True):
             raise ValueError("has_enclosures should be one of (None, False, True)")
 
         feed_tag_filter = tag_filter_argument(feed_tags, 'feed_tags')
 
-        return cls(feed_url, entry_id, read, important, has_enclosures, feed_tag_filter)
+        return cls(
+            feed_url, entry_id, read, important_filter, has_enclosures, feed_tag_filter
+        )
 
 
 _FFO = TypeVar('_FFO', bound='FeedFilterOptions')

src/reader/core.py

@@ -66,6 +66,7 @@
 from .types import ResourceInput
 from .types import SearchSortOrder
 from .types import TagFilterInput
+from .types import TristateFilterInput
 from .types import UpdatedFeed
 from .types import UpdateResult
 
@@ -1096,7 +1097,7 @@ def get_entries(
         feed: FeedInput | None = None,
         entry: EntryInput | None = None,
         read: bool | None = None,
-        important: bool | None = None,
+        important: TristateFilterInput = None,
         has_enclosures: bool | None = None,
         feed_tags: TagFilterInput = None,
         sort: EntrySortOrder = 'recent',
@@ -1264,7 +1265,7 @@ def get_entry_counts(
         feed: FeedInput | None = None,
         entry: EntryInput | None = None,
         read: bool | None = None,
-        important: bool | None = None,
+        important: TristateFilterInput = None,
         has_enclosures: bool | None = None,
         feed_tags: TagFilterInput = None,
     ) -> EntryCounts:
@@ -1642,7 +1643,7 @@ def search_entries(
         feed: FeedInput | None = None,
         entry: EntryInput | None = None,
         read: bool | None = None,
-        important: bool | None = None,
+        important: TristateFilterInput = None,
         has_enclosures: bool | None = None,
         feed_tags: TagFilterInput = None,
         sort: SearchSortOrder = 'relevant',
@@ -1778,7 +1779,7 @@ def search_entry_counts(
         feed: FeedInput | None = None,
         entry: EntryInput | None = None,
         read: bool | None = None,
-        important: bool | None = None,
+        important: TristateFilterInput = None,
         has_enclosures: bool | None = None,
         feed_tags: TagFilterInput = None,
     ) -> EntrySearchCounts:

src/reader/types.py

@@ -770,6 +770,20 @@ def _resource_argument(resource: ResourceInput) -> ResourceId:
 ]
 
 
+TristateFilterInput = Literal[
+    None,
+    True,
+    False,
+    'istrue',
+    'isfalse',
+    'notset',
+    'nottrue',
+    'notfalse',
+    'isset',
+    'any',
+]
+
+
 @dataclass(frozen=True)
 class FeedCounts(_namedtuple_compat):
 

tests/conftest.py

@@ -183,16 +183,7 @@ def chunk_size(request):
     return request.param
 
 
-@pytest.fixture(
-    params=[
-        # defaults not included
-        reader_methods.get_entries_recent,
-        reader_methods.get_entries_random,
-        reader_methods.search_entries_relevant,
-        reader_methods.search_entries_recent,
-        reader_methods.search_entries_random,
-    ],
-)
+@pytest.fixture(params=reader_methods.get_entries_methods)
 def get_entries(request):
     yield request.param
 

tests/reader_methods.py

@@ -70,7 +70,30 @@ def get_feeds(reader, **kwargs):
 for name, obj in dict(globals()).items():
     if name.startswith('get_'):
         obj.after_update = do_nothing
+    if name.startswith('search_entries'):
+        obj.after_update = enable_and_update_search
+
+
+def get_entry_counts(reader, **kwargs):
+    return reader.get_entry_counts(**kwargs)
+
+
+def search_entry_counts(reader, **kwargs):
+    return reader.search_entry_counts('entry', **kwargs)
+
 
 for name, obj in dict(globals()).items():
+    if name.startswith('get_entries'):
+        obj.counts = get_entry_counts
     if name.startswith('search_entries'):
-        obj.after_update = enable_and_update_search
+        obj.counts = search_entry_counts
+
+
+get_entries_methods = [
+    # defaults not included
+    get_entries_recent,
+    get_entries_random,
+    search_entries_relevant,
+    search_entries_recent,
+    search_entries_random,
+]

tests/test__types.py

@@ -7,6 +7,7 @@
 from reader._types import FeedData
 from reader._types import fix_datetime_tzinfo
 from reader._types import tag_filter_argument
+from reader._types import tristate_filter_argument
 
 
 TAG_DATA = [
@@ -51,6 +52,30 @@ def test_tag_filter_argument_error(input, error):
     assert error in str(excinfo.value)
 
 
+TRISTATE_FILTER_DATA = [
+    (v, v)
+    for v in ['istrue', 'isfalse', 'notset', 'nottrue', 'notfalse', 'isset', 'any']
+] + [
+    (None, 'any'),
+    (True, 'istrue'),
+    (False, 'nottrue'),
+    (1, 'istrue'),
+    (0, 'nottrue'),
+]
+
+
+@pytest.mark.parametrize('input, expected', TRISTATE_FILTER_DATA)
+def test_tristate_filter_argument(input, expected):
+    tristate_filter_argument(input, 'name')
+
+
+@pytest.mark.parametrize('input', ['all', 2, -1, ()])
+def test_tristate_filter_argument_error(input):
+    with pytest.raises(ValueError) as excinfo:
+        tristate_filter_argument(input, 'name')
+    assert 'name' in str(excinfo.value)
+
+
 @pytest.mark.parametrize('data_file', ['full', 'empty'])
 def test_entry_data_from_obj(data_dir, data_file):
     expected = {'url_base': '', 'rel_base': ''}

tests/test_reader.py

@@ -1713,6 +1713,47 @@ def test_entries_filtering_error(reader, get_entries, kwargs):
         list(get_entries(reader, **kwargs))
 
 
+@pytest.mark.parametrize('modified', [None, datetime(2010, 1, 1)])
+def test_entries_filtering_important(reader, subtests, get_entries, modified):
+    reader._parser = parser = Parser()
+
+    reader.add_feed(parser.feed(1))
+    one = parser.entry(1, 1)
+    two = parser.entry(1, 2)
+    reader.add_feed(parser.feed(2))
+    three = parser.entry(2, 3)
+
+    reader.update_feeds()
+    reader.update_search()
+
+    reader.set_entry_important(one, None, modified)
+    reader.set_entry_important(two, True, modified)
+    reader.set_entry_important(three, False, modified)
+
+    data = {
+        'istrue':   {'1, 2'},
+        True:       {'1, 2'},
+        'isfalse':  {'2, 3'},
+        'notset':   {'1, 1'},
+        'nottrue':  {'1, 1', '2, 3'},
+        False:      {'1, 1', '2, 3'},
+        'notfalse': {'1, 1', '1, 2'},
+        'isset':    {'1, 2', '2, 3'},
+        'any':      {'1, 1', '1, 2', '2, 3'},
+        None:       {'1, 1', '1, 2', '2, 3'},
+    }  # fmt: skip
+
+    for important, expected in data.items():
+        with subtests.test(important=important):
+            actual = {e.id for e in get_entries(reader, important=important)}
+            assert actual == expected
+            assert get_entries.counts(reader, important=important).total == len(
+                expected
+            )
+
+
+# TODO: ideally, systematize all filtering tests?
+
 # END entry filtering tests
 
 

tests/test_storage.py

@@ -535,7 +535,7 @@ def test_important_unimportant_by_default(storage):
     assert {
         e.id
         for e in storage.get_entries(
-            datetime(2010, 1, 1), EntryFilterOptions(important=False)
+            datetime(2010, 1, 1), EntryFilterOptions(important='nottrue')
         )
     } == {'one', 'two'}
 
@@ -551,19 +551,19 @@ def test_important_get_entries(storage):
     assert {
         e.id
         for e in storage.get_entries(
-            datetime(2010, 1, 1), EntryFilterOptions(important=None)
+            datetime(2010, 1, 1), EntryFilterOptions(important='any')
         )
     } == {'one', 'two'}
     assert {
         e.id
         for e in storage.get_entries(
-            datetime(2010, 1, 1), EntryFilterOptions(important=True)
+            datetime(2010, 1, 1), EntryFilterOptions(important='istrue')
         )
     } == {'one'}
     assert {
         e.id
         for e in storage.get_entries(
-            datetime(2010, 1, 1), EntryFilterOptions(important=False)
+            datetime(2010, 1, 1), EntryFilterOptions(important='nottrue')
         )
     } == {'two'}
 
@@ -586,7 +586,7 @@ def test_important_mark_as_unimportant(storage):
     assert {
         e.id
         for e in storage.get_entries(
-            datetime(2010, 1, 1), EntryFilterOptions(important=True)
+            datetime(2010, 1, 1), EntryFilterOptions(important='istrue')
         )
     } == set()