Skip to content

Commit

Permalink
Document Storage.delete_entries().
Browse files Browse the repository at this point in the history
Closes #301.

Related to #96.
  • Loading branch information
lemon24 committed Mar 19, 2023
1 parent 93bddde commit 4bf159b
Show file tree
Hide file tree
Showing 5 changed files with 59 additions and 0 deletions.
5 changes: 5 additions & 0 deletions CHANGES.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,11 @@ Version 3.6

Unreleased

* Document the low-level
:meth:`~reader._storage.Storage.delete_entries`
storage method.
(:issue:`301`, :issue:`96`)


Version 3.5
-----------
Expand Down
21 changes: 21 additions & 0 deletions docs/guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -527,6 +527,7 @@ although UIs might want to restrict this to a smaller set of characters.
Support entry and global tags.



Counting things
---------------

Expand Down Expand Up @@ -585,6 +586,26 @@ This example shows how to convert them to monthly statistics::



Deleting entries
----------------

As of version |version|, entries are **not** deleted automatically,
and there is no high-level way of deleting entries;
see :issue:`96` for details and updates.

Deleting entries properly is non-trivial for two reasons:

* Deleted entries should stay deleted;
right now, if you delete an entry that still appears in the feed,
it will be added again on the next update.
* The :mod:`~reader.plugins.entry_dedupe` plugin needs the old entry in order to work.

If you do not care about these issues,
you can delete entries using the low-level
:meth:`~reader._storage.Storage.delete_entries` storage method.



.. _pagination:

Pagination
Expand Down
15 changes: 15 additions & 0 deletions docs/internal.rst
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,9 @@ without using :class:`~reader.Reader` itself.
Parser
------

.. autoattribute:: reader.Reader._parser


.. module:: reader._parser

.. autofunction:: default_parser
Expand Down Expand Up @@ -109,6 +112,18 @@ Data objects
:members:


Storage
-------

.. autoattribute:: reader.Reader._storage


.. module:: reader._storage

.. autoclass:: Storage()
:members:


Recipes
-------

Expand Down
15 changes: 15 additions & 0 deletions src/reader/_storage.py
Original file line number Diff line number Diff line change
Expand Up @@ -385,6 +385,7 @@ def setup_db(db: sqlite3.Connection, wal_enabled: bool | None) -> None:


class Storage:
"""Data access object used for all storage except search."""

# chunk_size and entry_counts_average_periods
# are not part of the Storage interface,
Expand Down Expand Up @@ -1015,6 +1016,20 @@ def add_entry(self, intent: EntryUpdateIntent) -> None:
def delete_entries(
self, entries: Iterable[tuple[str, str]], *, added_by: str | None = None
) -> None:
r"""Delete a list of entries.
Args:
entries (list(tuple(str, str))):
A list of :attr:`~reader.Entry.resource_id`\s.
added_by (str or None):
If given, only delete the entries if their
:attr:`~reader.Entry.added_by` is equal to this.
Raises:
EntryNotFoundError: An entry does not exist.
EntryError: An entry has a different ``added_by`` from the given one.
"""
# This must be atomic (unlike add_or_update_entries()); hence, no paging.
# We'll deal with locking issues only if they start appearing
# (hopefully, there are both fewer entries to be deleted and
Expand Down
3 changes: 3 additions & 0 deletions src/reader/core.py
Original file line number Diff line number Diff line change
Expand Up @@ -356,8 +356,11 @@ def __init__(
_enable_search: bool = False,
_called_directly: bool = True,
):
#: The :class:`~reader._storage.Storage` instance used by this reader.
self._storage = _storage
#: The :class:`~reader._search.Search` instance used by this reader.
self._search = _search
#: The :class:`~reader._parser.Parser` instance used by this reader.
self._parser = _parser

self._reserved_name_scheme = _reserved_name_scheme
Expand Down

0 comments on commit 4bf159b

Please sign in to comment.