Rename mark_as_...() to mark_entry_as_...().

For #183.

CHANGES.rst

@@ -69,6 +69,17 @@ Unreleased
   the old method will continue to work **until version 2.0**,
   when it **will be removed.** (:issue:`183`)
 
+* Rename :class:`Reader` ``mark_as_...`` methods:
+
+  * :meth:`~Reader.mark_as_read` to :meth:`~Reader.mark_entry_as_read`
+  * :meth:`~Reader.mark_as_unread` to :meth:`~Reader.mark_entry_as_unread`
+  * :meth:`~Reader.mark_as_important` to :meth:`~Reader.mark_entry_as_important`
+  * :meth:`~Reader.mark_as_unimportant` to :meth:`~Reader.mark_entry_as_unimportant`
+
+  For backwards compatibility,
+  the old methods will continue to work **until version 2.0**,
+  when they **will be removed.** (:issue:`183`)
+
 * Fix feeds with no title sometimes missing
   from the :meth:`~Reader.get_feeds()` results
   when there are more than 256 feeds (``Storage.chunk_size``).

docs/guide.rst

@@ -285,12 +285,12 @@ Here is an example of getting entries for a single feed::
 Entry flags
 -----------
 
-Entries can be marked as :meth:`read <Reader.mark_as_read>`
-or as :meth:`important <Reader.mark_as_important>`.
+Entries can be marked as :meth:`read <Reader.mark_entry_as_read>`
+or as :meth:`important <Reader.mark_entry_as_important>`.
 
 These flags can be used for filtering::
 
-    >>> reader.mark_as_read(entries[0])
+    >>> reader.mark_entry_as_read(entries[0])
     >>> entries = list(reader.get_entries(feed=feed, read=False))
     >>> for entry in entries[:2]:
     ...     print(entry.feed.title, '-', entry.title)

docs/plugins.rst

@@ -59,8 +59,8 @@ For these, the full entry point *must* be specified.
 To use them from within Python code,
 use the entry point as a :ref:`custom plugin <custom plugins>`::
 
-    >>> from reader._plugins.regex_mark_as_read import regex_mark_as_read
-    >>> reader = make_reader("db.sqlite", plugins=[regex_mark_as_read])
+    >>> from reader._plugins import sqlite_releases
+    >>> reader = make_reader("db.sqlite", plugins=[sqlite_releases.init])
 
 
 .. automodule:: reader._plugins.tumblr_gdpr

docs/tutorial.rst

@@ -144,7 +144,7 @@ and marking them as read after we process them::
 
     for entry in entries:
         ...
-        reader.mark_as_read(entry)
+        reader.mark_entry_as_read(entry)
 
 If you run the script once, it should have the same output as before.
 If you run it again, it will show the next 3 unread entries:
@@ -187,12 +187,12 @@ And then we use it in download_everything()::
             print("  *", filename)
             download_file(enclosure.href, os.path.join(podcasts_dir, filename))
 
-        reader.mark_as_read(entry)
+        reader.mark_entry_as_read(entry)
 
 For each :class:`Enclosure`, we extract the filename from the enclosure URL
 so we can use it as the name of the local file.
 
-:meth:`~Reader.mark_as_read` gets called *after* we download the file,
+:meth:`~Reader.mark_entry_as_read` gets called *after* we download the file,
 so if the download fails, the script won't skip it at the next re-run.
 
 We also need to make sure the directory exists before calling

examples/podcast.py

@@ -40,7 +40,7 @@ def download_everything():
             print("  *", filename)
             download_file(enclosure.href, os.path.join(podcasts_dir, filename))
 
-        reader.mark_as_read(entry)
+        reader.mark_entry_as_read(entry)
 
 
 def download_file(src_url, dst_path):

src/reader/_app/__init__.py

@@ -438,15 +438,15 @@ def readererror_to_apierror(*args):
 def mark_as_read(data):
     feed_url = data['feed-url']
     entry_id = data['entry-id']
-    get_reader().mark_as_read((feed_url, entry_id))
+    get_reader().mark_entry_as_read((feed_url, entry_id))
 
 
 @form_api
 @readererror_to_apierror()
 def mark_as_unread(data):
     feed_url = data['feed-url']
     entry_id = data['entry-id']
-    get_reader().mark_as_unread((feed_url, entry_id))
+    get_reader().mark_entry_as_unread((feed_url, entry_id))
 
 
 @form_api(really=True)
@@ -455,7 +455,7 @@ def mark_all_as_read(data):
     feed_url = data['feed-url']
     entry_id = json.loads(data['entry-id'])
     for entry_id in entry_id:
-        get_reader().mark_as_read((feed_url, entry_id))
+        get_reader().mark_entry_as_read((feed_url, entry_id))
 
 
 @form_api(really=True)
@@ -464,23 +464,23 @@ def mark_all_as_unread(data):
     feed_url = data['feed-url']
     entry_id = json.loads(data['entry-id'])
     for entry_id in entry_id:
-        get_reader().mark_as_unread((feed_url, entry_id))
+        get_reader().mark_entry_as_unread((feed_url, entry_id))
 
 
 @form_api
 @readererror_to_apierror()
 def mark_as_important(data):
     feed_url = data['feed-url']
     entry_id = data['entry-id']
-    get_reader().mark_as_important((feed_url, entry_id))
+    get_reader().mark_entry_as_important((feed_url, entry_id))
 
 
 @form_api
 @readererror_to_apierror()
 def mark_as_unimportant(data):
     feed_url = data['feed-url']
     entry_id = data['entry-id']
-    get_reader().mark_as_unimportant((feed_url, entry_id))
+    get_reader().mark_entry_as_unimportant((feed_url, entry_id))
 
 
 @form_api(really=True)

src/reader/core.py

@@ -336,12 +336,13 @@ def delete_feed(self, feed: FeedInput) -> None:
             StorageError
 
         .. versionadded:: 1.18
+            Renamed from :meth:`remove_feed`.
 
         """
         url = _feed_argument(feed)
         self._storage.delete_feed(url)
 
-    remove_feed = deprecated_wrapper('remove_feed', delete_feed, '1.8', '2.0')
+    remove_feed = deprecated_wrapper('remove_feed', delete_feed, '1.18', '2.0')
 
     def change_feed_url(self, old: FeedInput, new: FeedInput) -> None:
         """Change the URL of a feed.
@@ -1054,7 +1055,7 @@ def get_entry_counts(
         )
         return self._storage.get_entry_counts(filter_options)
 
-    def mark_as_read(self, entry: EntryInput) -> None:
+    def mark_entry_as_read(self, entry: EntryInput) -> None:
         """Mark an entry as read.
 
         Args:
@@ -1064,11 +1065,14 @@ def mark_as_read(self, entry: EntryInput) -> None:
             EntryNotFoundError
             StorageError
 
+        .. versionadded:: 1.18
+            Renamed from :meth:`mark_as_read`.
+
         """
         feed_url, entry_id = _entry_argument(entry)
         self._storage.mark_as_read_unread(feed_url, entry_id, True)
 
-    def mark_as_unread(self, entry: EntryInput) -> None:
+    def mark_entry_as_unread(self, entry: EntryInput) -> None:
         """Mark an entry as unread.
 
         Args:
@@ -1078,11 +1082,14 @@ def mark_as_unread(self, entry: EntryInput) -> None:
             EntryNotFoundError
             StorageError
 
+        .. versionadded:: 1.18
+            Renamed from :meth:`mark_as_unread`.
+
         """
         feed_url, entry_id = _entry_argument(entry)
         self._storage.mark_as_read_unread(feed_url, entry_id, False)
 
-    def mark_as_important(self, entry: EntryInput) -> None:
+    def mark_entry_as_important(self, entry: EntryInput) -> None:
         """Mark an entry as important.
 
         Args:
@@ -1092,11 +1099,14 @@ def mark_as_important(self, entry: EntryInput) -> None:
             EntryNotFoundError
             StorageError
 
+        .. versionadded:: 1.18
+            Renamed from :meth:`mark_as_important`.
+
         """
         feed_url, entry_id = _entry_argument(entry)
         self._storage.mark_as_important_unimportant(feed_url, entry_id, True)
 
-    def mark_as_unimportant(self, entry: EntryInput) -> None:
+    def mark_entry_as_unimportant(self, entry: EntryInput) -> None:
         """Mark an entry as unimportant.
 
         Args:
@@ -1106,10 +1116,24 @@ def mark_as_unimportant(self, entry: EntryInput) -> None:
             EntryNotFoundError
             StorageError
 
+        .. versionadded:: 1.18
+            Renamed from :meth:`mark_as_unimportant`.
+
         """
         feed_url, entry_id = _entry_argument(entry)
         self._storage.mark_as_important_unimportant(feed_url, entry_id, False)
 
+    mark_as_read = deprecated_wrapper('mark_as_read', mark_entry_as_read, '1.18', '2.0')
+    mark_as_unread = deprecated_wrapper(
+        'mark_as_unread', mark_entry_as_unread, '1.18', '2.0'
+    )
+    mark_as_important = deprecated_wrapper(
+        'mark_as_important', mark_entry_as_important, '1.18', '2.0'
+    )
+    mark_as_unimportant = deprecated_wrapper(
+        'mark_as_unimportant', mark_entry_as_unimportant, '1.18', '2.0'
+    )
+
     def get_feed_metadata(
         self,
         feed: FeedInput,
@@ -1197,6 +1221,7 @@ def get_feed_metadata_item(
             StorageError
 
         .. versionadded:: 1.18
+            Renamed from :meth:`get_feed_metadata`.
 
         """
         return zero_or_one(
@@ -1221,6 +1246,7 @@ def set_feed_metadata_item(
             StorageError
 
         .. versionadded:: 1.18
+            Renamed from :meth:`set_feed_metadata`.
 
         """
         feed_url = _feed_argument(feed)
@@ -1238,19 +1264,20 @@ def delete_feed_metadata_item(self, feed: FeedInput, key: str) -> None:
             StorageError
 
         .. versionadded:: 1.18
+            Renamed from :meth:`delete_feed_metadata`.
 
         """
         feed_url = _feed_argument(feed)
         self._storage.delete_metadata((feed_url,), key)
 
     iter_feed_metadata = deprecated_wrapper(
-        'iter_feed_metadata', get_feed_metadata, '1.8', '2.0'
+        'iter_feed_metadata', get_feed_metadata, '1.18', '2.0'
     )
     set_feed_metadata = deprecated_wrapper(
-        'set_feed_metadata', set_feed_metadata_item, '1.8', '2.0'
+        'set_feed_metadata', set_feed_metadata_item, '1.18', '2.0'
     )
     delete_feed_metadata = deprecated_wrapper(
-        'delete_feed_metadata', delete_feed_metadata_item, '1.8', '2.0'
+        'delete_feed_metadata', delete_feed_metadata_item, '1.18', '2.0'
     )
 
     def enable_search(self) -> None:

src/reader/plugins/entry_dedupe.py

@@ -127,10 +127,10 @@ def _entry_dedupe_plugin(reader, entry):
             (entry.feed_url, entry.id),
             entry.title,
         )
-        reader.mark_as_read(entry)
+        reader.mark_entry_as_read(entry)
     else:
         for duplicate in duplicates:
-            reader.mark_as_read(duplicate)
+            reader.mark_entry_as_read(duplicate)
         log.info(
             "%r (%s): found unread duplicates, marking duplicates as read",
             (entry.feed_url, entry.id),
@@ -144,9 +144,9 @@ def _entry_dedupe_plugin(reader, entry):
             (entry.feed_url, entry.id),
             entry.title,
         )
-        reader.mark_as_important(entry)
+        reader.mark_entry_as_important(entry)
         for duplicate in duplicates:
-            reader.mark_as_unimportant(duplicate)
+            reader.mark_entry_as_unimportant(duplicate)
 
 
 def init_reader(reader):

src/reader/plugins/mark_as_read.py

@@ -1,11 +1,11 @@
 """
-reader.mark_as_read
-~~~~~~~~~~~~~~~~~~~
+reader.mark_entry_as_read
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Mark added entries of specific feeds as read if their title matches a regex.
 
 To configure, set the ``make_reader_reserved_name('mark_as_read')``
-(by default, ``.reader.mark_as_read``)
+(by default, ``.reader.mark_entry_as_read``)
 feed metadata to something like::
 
     {
@@ -58,7 +58,7 @@ def _mark_as_read(reader, entry):
 
     for pattern in patterns or ():
         if re.search(pattern, entry.title):
-            reader.mark_as_read(entry)
+            reader.mark_entry_as_read(entry)
             return
 
 

tests/test_plugins_entry_dedupe.py

@@ -97,8 +97,8 @@ def test_plugin(make_reader):
 
     reader.add_feed(one.url)
     reader.update_feeds()
-    reader.mark_as_read((one.url, read_one.id))
-    reader.mark_as_important((one.url, important_one.id))
+    reader.mark_entry_as_read((one.url, read_one.id))
+    reader.mark_entry_as_important((one.url, important_one.id))
 
     one = parser.feed(1, datetime(2010, 1, 2))
     new = parser.entry(1, 11, datetime(2010, 1, 2), title='title', summary='new')