Replace the many-argument of mark_entry_as_read() with set_entry_read…

…(). Idem for important.

For #256 and #254.

CHANGES.rst

@@ -19,17 +19,16 @@ Unreleased
   via :attr:`~Reader.after_feed_update_hooks`.
   (:issue:`202`)
 
-* Allow :meth:`~Reader.mark_entry_as_read`
-  and :meth:`~Reader.mark_entry_as_important`
-  to mark an entry as unread/unimportant through a boolean flag.
+* Add :meth:`~Reader.set_entry_read` and :meth:`~Reader.set_entry_important`
+  to allow marking an entry as (un)read/(un)important through a boolean flag.
   (:issue:`256`)
 
-* Record the time an entry is marked as read/important,
+* Record when an entry is marked as read/important,
   and make it available through :attr:`~Entry.read_modified` and
   :attr:`~Entry.important_modified`.
-  Allow setting it to a user-provided value using the ``modified``
-  argument of :meth:`~Reader.mark_entry_as_read`
-  and :meth:`~Reader.mark_entry_as_important`.
+  Allow providing a custom value using the ``modified``
+  argument of :meth:`~Reader.set_entry_read`
+  and :meth:`~Reader.set_entry_important`.
   (:issue:`254`)
 * Make :mod:`~reader.plugins.entry_dedupe` copy
   :attr:`~Entry.read_modified` and :attr:`~Entry.important_modified`

src/reader/_app/__init__.py

@@ -484,7 +484,7 @@ def mark_as_unread(data):
     entry = reader.get_entry(id)
     # if we're in "don't care", reset important_modified
     if not entry.important and entry.important_modified:
-        reader.mark_entry_as_important(id, False, modified=None)
+        reader.set_entry_important(id, False, modified=None)
 
 
 @form_api
@@ -527,7 +527,7 @@ def mark_as_unimportant(data):
     feed_url = data['feed-url']
     entry_id = data['entry-id']
     # only "don't care" sets important_modified
-    get_reader().mark_entry_as_important((feed_url, entry_id), False, modified=None)
+    get_reader().set_entry_important((feed_url, entry_id), False, modified=None)
 
 
 @form_api(really=True)

src/reader/core.py

@@ -1134,13 +1134,14 @@ def get_entry_counts(
         now = self._now()
         return self._storage.get_entry_counts(now, filter_options)
 
-    def mark_entry_as_read(
+    def set_entry_read(
         self,
         entry: EntryInput,
-        read: bool = True,
+        read: bool,
         modified: Union[MissingType, None, datetime] = MISSING,
     ) -> None:
-        """Mark an entry as read (or unread).
+        """Mark an entry as read or unread,
+        possibly with a custom timestamp.
 
         Args:
             entry (tuple(str, str) or Entry): (feed URL, entry id) tuple.
@@ -1156,14 +1157,7 @@ def mark_entry_as_read(
             EntryNotFoundError
             StorageError
 
-        .. versionadded:: 1.18
-            Renamed from :meth:`mark_as_read`.
-
-        .. versionadded:: 2.2
-            The ``read`` argument.
-
         .. versionadded:: 2.2
-            The ``modified`` argument.
 
         """
         modified_naive: Optional[datetime]
@@ -1177,10 +1171,28 @@ def mark_entry_as_read(
         feed_url, entry_id = _entry_argument(entry)
         self._storage.mark_as_read(feed_url, entry_id, bool(read), modified_naive)
 
+    def mark_entry_as_read(self, entry: EntryInput) -> None:
+        """Mark an entry as read.
+
+        Alias for ``set_entry_read(entry, True)``.
+
+        Args:
+            entry (tuple(str, str) or Entry): (feed URL, entry id) tuple.
+
+        Raises:
+            EntryNotFoundError
+            StorageError
+
+        .. versionadded:: 1.18
+            Renamed from :meth:`mark_as_read`.
+
+        """
+        self.set_entry_read(entry, True)
+
     def mark_entry_as_unread(self, entry: EntryInput) -> None:
         """Mark an entry as unread.
 
-        Alias for ``mark_entry_as_read(entry, False)``.
+        Alias for ``set_entry_read(entry, False)``.
 
         Args:
             entry (tuple(str, str) or Entry): (feed URL, entry id) tuple.
@@ -1193,15 +1205,16 @@ def mark_entry_as_unread(self, entry: EntryInput) -> None:
             Renamed from :meth:`mark_as_unread`.
 
         """
-        return self.mark_entry_as_read(entry, False)
+        return self.set_entry_read(entry, False)
 
-    def mark_entry_as_important(
+    def set_entry_important(
         self,
         entry: EntryInput,
-        important: bool = True,
+        important: bool,
         modified: Union[MissingType, None, datetime] = MISSING,
     ) -> None:
-        """Mark an entry as important (or unimportant).
+        """Mark an entry as important or unimportant,
+        possibly with a custom timestamp.
 
         Args:
             entry (tuple(str, str) or Entry): (feed URL, entry id) tuple.
@@ -1217,14 +1230,7 @@ def mark_entry_as_important(
             EntryNotFoundError
             StorageError
 
-        .. versionadded:: 1.18
-            Renamed from :meth:`mark_as_important`.
-
-        .. versionadded:: 2.2
-            The ``important`` argument.
-
         .. versionadded:: 2.2
-            The ``modified`` argument.
 
         """
         modified_naive: Optional[datetime]
@@ -1240,10 +1246,28 @@ def mark_entry_as_important(
             feed_url, entry_id, bool(important), modified_naive
         )
 
+    def mark_entry_as_important(self, entry: EntryInput) -> None:
+        """Mark an entry as important.
+
+        Alias for ``set_entry_important(entry, True)``.
+
+        Args:
+            entry (tuple(str, str) or Entry): (feed URL, entry id) tuple.
+
+        Raises:
+            EntryNotFoundError
+            StorageError
+
+        .. versionadded:: 1.18
+            Renamed from :meth:`mark_as_important`.
+
+        """
+        self.set_entry_important(entry, True)
+
     def mark_entry_as_unimportant(self, entry: EntryInput) -> None:
         """Mark an entry as unimportant.
 
-        Alias for ``mark_entry_as_important(entry, False)``.
+        Alias for ``set_entry_important(entry, False)``.
 
         Args:
             entry (tuple(str, str) or Entry): (feed URL, entry id) tuple.
@@ -1256,7 +1280,7 @@ def mark_entry_as_unimportant(self, entry: EntryInput) -> None:
             Renamed from :meth:`mark_as_unimportant`.
 
         """
-        return self.mark_entry_as_important(entry, False)
+        return self.set_entry_important(entry, False)
 
     def _mark_entry_as_dont_care(self, entry: EntryInput) -> None:
         """Mark an entry as read and unimportant at the same time,

src/reader/plugins/entry_dedupe.py

@@ -390,21 +390,19 @@ def _get_flag_args(entry, duplicates, name):
 def _make_actions(reader, entry, duplicates):
     args = _get_flag_args(entry, duplicates, 'read')
     if args:
-        yield partial(reader.mark_entry_as_read, entry, *args)
+        yield partial(reader.set_entry_read, entry, *args)
 
     for duplicate in duplicates:
         if not duplicate.read or duplicate.read_modified is not None:
-            yield partial(reader.mark_entry_as_read, duplicate, modified=None)
+            yield partial(reader.set_entry_read, duplicate, True, None)
 
     args = _get_flag_args(entry, duplicates, 'important')
     if args:
-        yield partial(reader.mark_entry_as_important, entry, *args)
+        yield partial(reader.set_entry_important, entry, *args)
 
     for duplicate in duplicates:
         if duplicate.important or duplicate.important_modified is not None:
-            yield partial(
-                reader.mark_entry_as_important, duplicate, False, modified=None
-            )
+            yield partial(reader.set_entry_important, duplicate, False, None)
 
 
 def _dedupe_entries(reader, entry, duplicates, *, dry_run):

tests/test_plugins_entry_dedupe.py

@@ -506,7 +506,7 @@ def _test_modified_copying(make_reader, db_path, data, expected, name):
 
     # the entry with the highest id is the last one
     for id, flag, modified in data:
-        getattr(reader, f'mark_entry_as_{name}')(('1', f'1, {id}'), flag, modified)
+        getattr(reader, f'set_entry_{name}')(('1', f'1, {id}'), flag, modified)
 
     reader = make_reader(db_path, plugins=['reader.entry_dedupe'])
     reader._parser = parser

tests/test_reader.py

@@ -3115,7 +3115,7 @@ def test_entry_read_important_modified_gets_set_to_now(reader, flag):
     assert getattr(entry, f'{flag}_modified') == datetime(2010, 1, 2)
 
     reader._now = lambda: naive_datetime(2010, 1, 3)
-    getattr(reader, f'mark_entry_as_{flag}')(entry, False)
+    getattr(reader, f'mark_entry_as_un{flag}')(entry)
     entry = next(reader.get_entries())
     assert not getattr(entry, flag)
     assert getattr(entry, f'{flag}_modified') == datetime(2010, 1, 3)
@@ -3131,13 +3131,13 @@ def test_entry_read_important_modified_argument(reader, flag, monkeypatch_tz):
     entry = next(reader.get_entries())
     reader._now = lambda: naive_datetime(2010, 1, 1)
 
-    getattr(reader, f'mark_entry_as_{flag}')(
-        entry, modified=datetime(2010, 1, 1, tzinfo=timezone(timedelta(hours=-2)))
+    getattr(reader, f'set_entry_{flag}')(
+        entry, True, modified=datetime(2010, 1, 1, tzinfo=timezone(timedelta(hours=-2)))
     )
     entry = next(reader.get_entries())
     assert getattr(entry, f'{flag}_modified') == utc_datetime(2010, 1, 1, 2)
 
-    getattr(reader, f'mark_entry_as_{flag}')(entry, modified=None)
+    getattr(reader, f'set_entry_{flag}')(entry, True, modified=None)
     entry = next(reader.get_entries())
     assert getattr(entry, f'{flag}_modified') is None
 
@@ -3146,12 +3146,12 @@ def test_entry_read_important_modified_argument(reader, flag, monkeypatch_tz):
         return
 
     monkeypatch_tz('UTC')
-    getattr(reader, f'mark_entry_as_{flag}')(entry, modified=datetime(2010, 1, 1, 4))
+    getattr(reader, f'set_entry_{flag}')(entry, True, modified=datetime(2010, 1, 1, 4))
     entry = next(reader.get_entries())
     assert getattr(entry, f'{flag}_modified') == utc_datetime(2010, 1, 1, 4)
 
     monkeypatch_tz('Etc/GMT+6')
-    getattr(reader, f'mark_entry_as_{flag}')(entry, modified=datetime(2010, 1, 1))
+    getattr(reader, f'set_entry_{flag}')(entry, True, modified=datetime(2010, 1, 1))
     entry = next(reader.get_entries())
     assert getattr(entry, f'{flag}_modified') == utc_datetime(2010, 1, 1, 6)