Reader

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

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`)

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

Released 2021-03-29

* Allow :func:`make_reader` to load plugins through the ``plugins`` argument.
(:issue:`229`)

Enable the :mod:`~reader.plugins.ua_fallback` plugin by default.

:func:`make_reader` may now raise :exc:`InvalidPluginError`
(a :exc:`ValueError` subclass, which it already raises implicitly)
for invalid plugin names.

* The ``enclosure_dedupe``, ``feed_entry_dedupe``, and ``ua_fallback`` plugins
are now :ref:`built-in <built-in plugins>`.
(:issue:`229`)

To use them with the CLI / web application,
use the plugin name instead of the entry point::

reader._plugins.enclosure_dedupe:enclosure_dedupe -> reader.enclosure_dedupe
reader._plugins.feed_entry_dedupe:feed_entry_dedupe -> reader.entry_dedupe
reader._plugins.ua_fallback:init -> reader.ua_fallback

* Remove the ``plugins`` extra;
plugin loading machinery does not have additional dependencies anymore.

* Mention in the :doc:`guide` that all *reader* functions/methods can raise
:exc:`ValueError` or :exc:`TypeError` if passed invalid arguments.
There is no behavior change, this is just documenting existing,
previously undocumented behavior.

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

Released 2021-03-21

* Update entries whenever their content changes,
regardless of their :attr:`~Entry.updated` date.
(:issue:`179`)

Limit content-only updates (not due to an :attr:`~Entry.updated` change)
to 24 consecutive updates,
to prevent spurious updates for entries whose content changes
excessively (for example, because it includes the current time).
(:issue:`225`)

Previously, entries would be updated only if the
entry :attr:`~Entry.updated` was *newer* than the stored one.

* Fix bug causing entries that don't have :attr:`~Entry.updated`
set in the feed to not be updated if the feed is marked as stale.
Feed staleness is an internal feature used during storage migrations;
this bug could only manifest when migrating from 0.22 to 1.x.
(found during :issue:`179`)
* Minor web application improvements.
* Minor CLI improvements.

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

Released 2021-02-22

* Add the :meth:`~Reader.update_feeds_iter` method,
which yields the update status of each feed as it gets updated.
(:issue:`204`)
* Change the return type of :meth:`~Reader.update_feed`
from ``None`` to ``Optional[UpdatedFeed]``.
(:issue:`204`)
* Add the ``session_timeout`` argument to :func:`make_reader`
to set a timeout for retrieving HTTP(S) feeds.
The default (connect timeout, read timeout) is (3.05, 60) seconds;
the previous behavior was to *never time out*.
* Use ``PRAGMA user_version`` instead of a version table. (:issue:`210`)
* Use ``PRAGMA application_id`` to identify reader databases;
the id is ``0x66656564`` – ``read`` in ASCII / UTF-8. (:issue:`211`)
* Change the ``reader update`` command to show a progress bar
and update summary (with colors), instead of plain log output.
(:issue:`204`)
* Fix broken Mypy config following 0.800 release. (:issue:`213`)