Reader

-----------

Released 2021-08-18

* Return :ref:`entry averages <entry averages>` for the past 1, 3, 12 months
from the entry count methods. (:issue:`249`)

* Use an index for ``get_entry_counts(feed=...)`` calls.
Makes the /feeds?counts=yes page load 2-4x faster. (:issue:`251`)

* Add :class:`UpdateResult` :attr:`~UpdateResult.updated_feed`,
:attr:`~UpdateResult.error`, and :attr:`~UpdateResult.not_modified`
convenience properties. (:issue:`204`)

* In the web application, show the feed entry count averages as a bar sparkline.
(:issue:`249`)

* Make the minimum SQLite version and required SQLite compile options
``reader._storage`` module globals, for easier monkeypatching. (:issue:`163`)

This is allows supplying a user-defined ``json_array_length`` function
on platforms where SQLite doesn't come with the JSON1 extension
(e.g. on Windows with stock Python earlier than 3.9;
`details <https://github.com/lemon24/reader/issues/163#issuecomment-895041943>`_).

Note these globals are private, and thus *not* covered by the
:ref:`backwards compatibility policy <compat>`.

-----------

Released 2021-07-17


.. attention::

This release contains backwards incompatible changes.


* Remove old database migrations.

If you are upgrading from *reader* 1.15 or newer, no action is required.

.. _removed migrations 2.0:

.. attention::

If you are upgrading to *reader* 2.0 from a version **older than 1.15**,
you must open your database with *reader* 1.15 or newer once,
to run the removed migrations:

.. code-block:: sh

pip install 'reader>=1.15,<2' && \
python - db.sqlite << EOF
import sys
from reader import make_reader
make_reader(sys.argv[1])
print("OK")
EOF

* Remove code that issued deprecation warnings in versions 1.* (:issue:`183`):

* :meth:`Reader.remove_feed`
* :meth:`Reader.mark_as_read`
* :meth:`Reader.mark_as_unread`
* :meth:`Reader.mark_as_important`
* :meth:`Reader.mark_as_unimportant`
* :meth:`Reader.iter_feed_metadata`
* the ``get_feed_metadata(feed, key, default=no value, /)``
form of :meth:`Reader.get_feed_metadata`
* :meth:`Reader.set_feed_metadata`
* :meth:`Reader.delete_feed_metadata`
* the ``new_only`` parameter of
:meth:`~Reader.update_feeds()` and :meth:`~Reader.update_feeds_iter()`
* :attr:`EntryError.url`
* :attr:`UpdatedFeed.updated`

* The :class:`~datetime.datetime` attributes
of :class:`Feed` and :class:`Entry` objects are now timezone-aware,
with the timezone set to :attr:`~datetime.timezone.utc`.
Previously, they were naive datetimes representing UTC times.
(:issue:`233`)

* The parameters of
:meth:`~Reader.update_feeds()` and :meth:`~Reader.update_feeds_iter()`
are now keyword-only. (:issue:`183`)

* The ``feed_root`` argument of :func:`make_reader`
now defaults to ``None`` (don't open local feeds)
instead of ``''`` (full filesystem access).

* :func:`make_reader` may now raise any :exc:`ReaderError`,
not just :exc:`StorageError`.

* :attr:`Entry.updated` may now be :const:`None`;
use :attr:`~Entry.updated_not_none` for the pre-2.0 behavior.

------------

Released 2021-07-12

* Add :attr:`~Reader.after_entry_update_hooks`,
which allow running arbitrary actions for updated entries.
Thanks to `Mirek Długosz`_ for the issue and pull request.
(:issue:`241`)
* Raise :exc:`StorageError` when opening / operating on an invalid database,
instead of a plain :exc:`sqlite3.DatabaseError`.
(:issue:`243`)

.. _Mirek Długosz: https://github.com/mirekdlugosz

------------

Released 2021-06-16

* Drop Python 3.6 support. (:issue:`237`)
* Support PyPy 3.7. (:issue:`234`)
* Skip enclosures with no ``href``/``url``;
previously, they would result in a parse error.
(:issue:`240`)
* Stop using Travis CI (only use GitHub Actions). (:issue:`199`)
* Add the ``new`` argument to
:meth:`~Reader.update_feeds()` and :meth:`~Reader.update_feeds_iter()`;
``new_only`` is deprecated and **will be removed in 2.0**.
(:issue:`217`)

* Rename :attr:`UpdatedFeed.updated` to :attr:`~UpdatedFeed.modified`;
for backwards compatibility,
the old attribute will be available as a property **until version 2.0**,
when it **will be removed.**. (:issue:`241`)

.. warning::

The signature of :class:`UpdatedFeed`
changed from ``UpdatedFeed(url, new, updated)``
to ``UpdatedFeed(url, new, modified)``.

**This is a minor compatibility break**,
but only affects third-party code that instantiates
UpdatedFeed *directly* with ``updated`` as a *keyword argument*.

------------

Released 2021-06-03

* Rename :class:`Reader` feed metadata methods:

* :meth:`~Reader.iter_feed_metadata` to :meth:`~Reader.get_feed_metadata`
* :meth:`~Reader.get_feed_metadata` to :meth:`~Reader.get_feed_metadata_item`
* :meth:`~Reader.set_feed_metadata` to :meth:`~Reader.set_feed_metadata_item`
* :meth:`~Reader.delete_feed_metadata` to :meth:`~Reader.delete_feed_metadata_item`

For backwards compatibility,
the old method signatures will continue to work **until version 2.0**,
when they **will be removed.** (:issue:`183`)

.. warning::

The ``get_feed_metadata(feed, key[, default]) -> value`` form
is backwards-compatible *only when the arguments are positional*.

**This is a minor compatibility break**;
the following work in 1.17, but do not in 1.18::

raises TypeError
reader.get_feed_metadata(feed, key, default=None)

returns `(key, value), ...` instead of `value`
reader.get_feed_metadata(feed, key=key)

The pre-1.18 :meth:`~Reader.get_feed_metadata`
(1.18 :meth:`~Reader.get_feed_metadata_item`)
is intended to have positional-only arguments,
but this cannot be expressed easily until Python 3.8.

* Rename :exc:`MetadataNotFoundError` to :exc:`FeedMetadataNotFoundError`.
:exc:`MetadataNotFoundError` remains available,
and is a superclass of :exc:`FeedMetadataNotFoundError`
for backwards compatibility.
(:issue:`228`)

.. warning::

The signatures of the following exceptions changed:

:exc:`MetadataError`
Takes a new required ``key`` argument, instead of no required arguments.

:exc:`MetadataNotFoundError`
Takes only one required argument, ``key``;
the ``url`` argument has been removed.

Use :exc:`FeedMetadataNotFoundError` instead.

**This is a minor compatibility break**,
but only affects third-party code that instantiates
these exceptions *directly*.

* Rename :attr:`EntryError.url` to :attr:`~EntryError.feed_url`;
for backwards compatibility,
the old attribute will be available as a property **until version 2.0**,
when it **will be removed.** (:issue:`183`).

.. warning::

The signature of :exc:`EntryError` (and its subclasses)
changed from ``EntryError(url, id)`` to ``EntryError(feed_url, id)``.

**This is a minor compatibility break**,
but only affects third-party code that instantiates
these exceptions *directly* with ``url`` as a *keyword argument*.

* Rename :meth:`~Reader.remove_feed` to :meth:`~Reader.delete_feed`.
For backwards compatibility,
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``).
(:issue:`203`)

* When serving the web application with ``python -m reader serve``,
don't set the ``Referer`` header for cross-origin requests.
(:issue:`209`)

------------

Released 2021-05-06

* Reserve tags and metadata keys starting with ``.reader.`` and ``.plugin.``
for *reader*- and plugin-specific uses.
See the :ref:`reserved names` user guide section for details.
(:issue:`186`)

* Ignore :attr:`~Feed.updated` when updating feeds;
only update the feed if other feed data changed
or if any entries were added/updated.
(:issue:`231`)

Prevents spurious updates for feeds whose :attr:`~Feed.updated`
changes excessively
(either because the entries' content changes excessively,
or because an RSS feed does not have a ``dc:date`` element,
and feedparser falls back to ``lastBuildDate`` for :attr:`~Feed.updated`).

* The ``regex_mark_as_read`` experimental plugin is now
:ref:`built-in <built-in plugins>`.
To use it with the CLI / web application,
use the plugin name instead of the entry point (``reader.mark_as_read``).

The config metadata key and format changed;
the config will be migrated automatically on the next feed update,
**during reader version 1.17 only**.
If you used ``regex_mark_as_read`` and are upgrading to a version >1.17,
install 1.17 (``pip install reader==1.17``)
and run a full feed update (``python -m reader update``)
before installing the newer version.

* The ``enclosure-tags``, ``preview-feed-list``, and ``sqlite-releases``
unstable extras are not available anymore.
Use the ``unstable-plugins`` extra to install
dependencies of the unstable plugins instead.

* In the web application, allow updating a feed manually.
(:issue:`195`)