reader 3.20__tar.gz → 3.22__tar.gz

{reader-3.20 → reader-3.22}/CHANGES.rst

@@ -6,6 +6,93 @@ Changelog
   :no-index:
 
 
+Version 3.22
+------------
+
+Released 2026-04-01
+
+* :func:`make_reader` plugin loading improvements. (:issue:`395`)
+
+  * ``plugins`` now supports arbitrary import paths.
+  * :ref:`Built-in plugins <built-in plugins>` now use the
+    ``.<plugin>`` naming scheme, instead of ``reader.<plugin>``;
+    support for the latter is deprecated and will be removed in version 4.0.
+
+* :meth:`~Reader.get_feeds`, :meth:`~Reader.get_entries`, and
+  :meth:`~Reader.search_entries` now raise exceptions
+  for invalid ``query`` and ``starting_after`` eagerly,
+  before the iterable is consumed.
+  Thanks to `Omprakash Choudhary`_ for the PR.
+  (:issue:`388`)
+
+* :doc:`app` improvements.
+
+  * Finish the web app re-design MVP,
+    including:
+    add / list / filter / delete feeds,
+    list / filter articles,
+    article view,
+    mark articles as read / (un)important,
+    article view,
+    custom feed titles,
+    dark mode,
+    CSRF protection,
+    vendored CSS / JS dependencies.
+
+  * Make the new web app the default (entry point ``reader._app.wsgi:app``);
+    the :ref:`legacy web app <legacy web app>` remains available
+    at ``reader._app.legacy.wsgi:app``.
+
+  * Update both web apps to use the new configuration infrastructure (see below).
+
+* :doc:`CLI <cli>` and :doc:`config file <config>` breaking changes. (:issue:`395`)
+
+  * The config file format changed from YAML to TOML,
+    and follows the shape of the CLI.
+  * The ``reader serve`` command was renamed to ``reader web``.
+  * Plugin loading environment variables changed:
+    ``READER_PLUGIN`` -> ``READER_PLUGINS``,
+    ``READER_CLI_PLUGIN`` -> ``READER_CLI_PLUGINS``,
+    ``READER_APP_PLUGIN`` -> ``READER_WEB_PLUGINS``.
+
+
+.. _Omprakash Choudhary: https://github.com/omseervi098
+
+
+Version 3.21
+------------
+
+Released 2026-01-12
+
+* :ref:`Scheduled updates <scheduled>` improvements.
+
+  * Only update scheduled feeds by default
+    (:meth:`update_feeds(scheduled=...) <Reader.update_feeds>`
+    defaults to :const:`True`);
+    previously, all feeds would be updated.
+    (:issue:`379`)
+
+    .. warning::
+
+      **This is a minor compatibility break**;
+      the previous behavior is a bug –
+      *reader* should do the right thing
+      even if the user doesn't read the documentation.
+
+    In the CLI, make ``update --scheduled`` the default.
+
+  * Honor the Cache-Control (max-age) and Expires HTTP headers.
+    (:issue:`376`)
+
+  * Limit the :attr:`~Feed.update_after` derived from HTTP headers
+    to a month in the future.
+    (:issue:`384`)
+
+  * If the Retry-After value is a date,
+    make the update interval relative to Date.
+
+
+
 Version 3.20
 ------------
 
@@ -217,7 +304,7 @@ Released 2024-07-23
 * Fix bug in the :mod:`~reader.plugins.entry_dedupe` plugin causing entries
   to flip-flop if there were multiple *new* duplicates of the same issue
   (on the first update, one entry remains, on the second update, the other);
-  related to the bug fixed in `version 3.2 <Version 3.2_>`_.
+  related to the bug fixed in `version 3.2 <Version 3.2_>`__.
   (:issue:`340`)
 
 * :mod:`~reader._plugins.enclosure_tags` plugin improvements. (:issue:`344`)
@@ -260,7 +347,7 @@ Released 2024-06-19
   * Update an entry whenever its :attr:`~Entry.updated` changes
     (don't require it to be newer).
 
-* Fix bug introduced in `version 3.12 <Version 3.12_>`_ causing an assertion error
+* Fix bug introduced in `version 3.12 <Version 3.12_>`__ causing an assertion error
   when there are multiple entries with the same id in the same feed,
   or when parallel :meth:`~Reader.update_feeds` calls add the same entry.
   The fix restores the pre-3.12 first-entry-wins / last-write-wins behavior.
@@ -411,7 +498,7 @@ Released 2023-08-20
 
 * Add werkzeug dependency,
   instead of vendoring selected :mod:`werkzeug.http` utilities.
-* Rework lazy imports introduced in `version 3.3 <Version 3.3_>`_.
+* Rework lazy imports introduced in `version 3.3 <Version 3.3_>`__.
   (:issue:`316`)
 * Make :mod:`reader._parser` a package, and move parsing-related modules into it.
   (:issue:`316`)
@@ -472,7 +559,7 @@ Released 2023-03-19
   so one can express "explicitly unimportant" (*don't care*)
   by setting it to :const:`False`.
   This replaces the semantics for *don't care* introduced
-  in `version 2.2 <Version 2.2_>`_.
+  in `version 2.2 <Version 2.2_>`__.
   (:issue:`254`)
 
   .. warning::

{reader-3.20 → reader-3.22}/MANIFEST.in

@@ -1,7 +1,9 @@
 recursive-include src/reader/_app/templates *
 recursive-include src/reader/_app/static *
-recursive-include src/reader/_app/v2 *
 recursive-include src/reader/_plugins/templates *
+recursive-include src/reader/_app/legacy/templates *
+recursive-include src/reader/_app/legacy/static *
+recursive-include src/reader/_plugins/legacy/templates *
 recursive-include src/reader *.pyi
 recursive-include src/reader py.typed
 include run.sh CHANGES.rst LICENSE tox.ini

{reader-3.20/src/reader.egg-info → reader-3.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reader
-Version: 3.20
+Version: 3.22
 Summary: A Python feed reader library.
 Author: lemon24
 License: BSD-3-Clause
@@ -45,12 +45,12 @@ Provides-Extra: all
 Requires-Dist: reader[app,cli,unstable-plugins]; extra == "all"
 Provides-Extra: cli
 Requires-Dist: click>=7; extra == "cli"
-Requires-Dist: PyYAML; extra == "cli"
 Provides-Extra: app
 Requires-Dist: flask>=0.10; extra == "app"
 Requires-Dist: humanize>=4; extra == "app"
 Requires-Dist: PyYAML; extra == "app"
 Requires-Dist: WTForms; extra == "app"
+Requires-Dist: Flask-WTF; extra == "app"
 Requires-Dist: jinja2-fragments; extra == "app"
 Provides-Extra: unstable-plugins
 Requires-Dist: requests; extra == "unstable-plugins"
@@ -68,7 +68,9 @@ Dynamic: license-file
 
 It is designed to allow writing feed reader applications
 without any business code,
-and without depending on a particular framework.
+and without depending on a particular framework;
+in MVC terms,
+you'd probably call it a fat model.
 
 .. end-intro
 
@@ -122,19 +124,13 @@ and without depending on a particular framework.
 
 What *reader* doesn't do:
 
-* provide an UI
-* provide a REST API (yet)
 * depend on a web framework
-* have an opinion of how/where you use it
+* have an opinion of how or where you use it
 
-The following exist, but are optional (and frankly, a bit unpolished):
+In addition, *reader* provides:
 
-* a minimal web interface
-
-  * that works even with text-only browsers
-  * with automatic tag fixing for podcasts (MP3 enclosures)
-
-* a command-line interface
+* an optional web application based on Flask, Bootstrap, and htmx
+* an optional command-line interface
 
 .. end-features
 

{reader-3.20 → reader-3.22}/README.rst

@@ -4,7 +4,9 @@
 
 It is designed to allow writing feed reader applications
 without any business code,
-and without depending on a particular framework.
+and without depending on a particular framework;
+in MVC terms,
+you'd probably call it a fat model.
 
 .. end-intro
 
@@ -58,19 +60,13 @@ and without depending on a particular framework.
 
 What *reader* doesn't do:
 
-* provide an UI
-* provide a REST API (yet)
 * depend on a web framework
-* have an opinion of how/where you use it
+* have an opinion of how or where you use it
 
-The following exist, but are optional (and frankly, a bit unpolished):
+In addition, *reader* provides:
 
-* a minimal web interface
-
-  * that works even with text-only browsers
-  * with automatic tag fixing for podcasts (MP3 enclosures)
-
-* a command-line interface
+* an optional web application based on Flask, Bootstrap, and htmx
+* an optional command-line interface
 
 .. end-features
 

reader-3.22/docs/app.rst

@@ -0,0 +1,141 @@
+
+Web application
+===============
+
+*reader* comes with a web application
+based on  `Flask`_, `Bootstrap`_, and `htmx`_,
+intended to work across all browsers,
+including mobile and light-weight / text-only ones.
+
+.. _Flask: https://flask.palletsprojects.com/
+.. _Bootstrap: https://getbootstrap.com/
+.. _htmx: https://htmx.org/
+
+Features, as of *reader* version |version|:
+
+* add / list / filter / delete feeds
+* list / filter articles
+* mark articles as read / (un)important
+* article view
+* custom feed titles
+* dark mode
+
+More features already implemented in the library
+and the :ref:`legacy web app <legacy web app>`
+should be added in the next releases;
+see the :ref:`roadmap <app roadmap>` for details.
+
+
+
+.. _app screenshots:
+
+Screenshots
+-----------
+
+.. figure:: screenshots/entries.png
+    :width: 240px
+
+    main page (dark mode)
+
+.. figure:: screenshots/entries-filters-light.png
+    :width: 240px
+
+    main page – more filters (light mode)
+
+.. figure:: screenshots/feed.png
+    :width: 240px
+
+    feed page (dark mode)
+
+.. figure:: screenshots/feeds.png
+    :width: 240px
+
+    feeds page (dark mode)
+
+.. figure:: screenshots/entry.png
+    :width: 240px
+
+    article view (dark mode)
+
+.. figure:: screenshots/entry-image-light.png
+    :width: 240px
+
+    article view (light mode)
+
+
+
+Serving the web app
+-------------------
+
+.. note::
+
+    The web application is optional, use the ``app`` extra to install
+    its :ref:`dependencies <Optional dependencies>`.
+
+
+*reader* exposes a standard WSGI application as ``reader._app.wsgi:app``.
+See the `Flask documentation`_ for more details on how to deploy it.
+The path to the reader database can be configured through the
+:doc:`config file <config>`
+or the ``READER_DB`` environment variable.
+
+.. warning::
+
+    The web application has no authentication / authorization whatsoever;
+    it is expected a server / middleware will provide that.
+
+
+An example uWSGI configuration file (probably not idiomatic, from `here`_)::
+
+    [uwsgi]
+    socket = /apps/reader/uwsgi/sock
+    manage-script-name = true
+    mount = /reader=reader._app.wsgi:app
+    plugin = python3
+    virtualenv = /apps/reader/
+    env = READER_CONFIG=/apps/reader/reader.toml
+
+
+You can also run the web application with the ``web`` command.
+``web`` uses `Werkzeug's development server`_,
+so it probably won't scale well past a single user.
+
+.. note::
+
+    For privacy reasons,
+    you may want to configure your web server to not send a ``Referer`` header
+    (by setting ``Referrer-Policy`` header to ``same-origin``
+    for all responses; `nginx example`_).
+    The ``web`` command does it by default.
+
+
+If running on a personal computer, you can use cron to run it at boot::
+
+    @reboot     sleep 60; reader web -p 8080 2>&1 ) >>"/tmp/$LOGNAME.reader.web.run.boot.log"
+
+
+.. _here: https://github.com/lemon24/owncloud/blob/8009f227ef60ebaab621e7bb3363ec9071d8a2e8/reader.yaml#L103-L116
+.. _nginx example: https://github.com/lemon24/owncloud/blob/8009f227ef60ebaab621e7bb3363ec9071d8a2e8/secure.conf#L23
+.. _Flask documentation: https://flask.palletsprojects.com/en/stable/deploying/
+.. _Werkzeug's development server: https://werkzeug.palletsprojects.com/en/stable/serving/#werkzeug.serving.run_simple
+
+
+
+.. _legacy web app:
+
+Legacy web app
+--------------
+
+Before the current web application,
+there was another one,
+serving as test bed for new features.
+It is usable, if a bit unpolished,
+but was never meant to be a long-term thing,
+hence the new app;
+you can find screenshots
+`here <https://github.com/lemon24/reader/blob/3.21/docs/app.rst#screenshots-legacy>`_.
+
+The WSGI entry point is ``reader._app.legacy.wsgi:app``.
+
+The legacy web app should remain available
+until the new app reaches feature parity.

{reader-3.20 → reader-3.22}/docs/cli.rst

@@ -2,18 +2,12 @@
 Command-line interface
 ======================
 
-*reader* comes with a command-line interface
-that exposes basic management functionality.
-
-
-.. warning::
-
-    The CLI is is not fully stable,
-    see the :ref:`roadmap <cli roadmap>` for details.
+*reader* comes with a CLI
+that exposes management functionality.
 
 .. note::
 
-    The command-line interface is optional, use the ``cli`` extra to install
+    The CLI is optional, use the ``cli`` extra to install
     its :ref:`dependencies <Optional dependencies>`.
 
 Most commands need a database to work. The following are equivalent:
@@ -42,7 +36,7 @@ Serve the web application locally (at http://localhost:8080/):
 
 .. code-block:: bash
 
-    python -m reader serve
+    python -m reader web
 
 
 .. _cli-update:

{reader-3.20 → reader-3.22}/docs/conf.py

@@ -17,6 +17,7 @@ for name in [
     'flask.signals',
     'werkzeug',
     'werkzeug.datastructures',
+    'werkzeug.exceptions',
     'werkzeug.http',
     'yaml',
 ]:
@@ -45,6 +46,7 @@ autodoc_mock_imports = [
     'bs4',
     'mutagen',
     'flask',
+    'flask_wtf',
     'werkzeug',
     'humanize',
     'markupsafe',

reader-3.22/docs/config.rst

@@ -0,0 +1,30 @@
+
+Configuration
+=============
+
+Both the :doc:`CLI <cli>` and the :doc:`web application <app>` can
+be configured from a TOML file.
+
+.. note::
+
+    Configuration file loading dependencies get installed automatically when
+    installing the CLI or the web application
+    :ref:`extras <Optional dependencies>`.
+
+
+The configuration file path can be specified either through the ``--config``
+CLI option or through the ``READER_CONFIG`` environment variable
+(also usable with the web application).
+
+The configuration file matches the shape of the :doc:`CLI <cli>`
+(the ``reader`` section has options for the ``reader`` command,
+the ``reader.update`` section has options for the ``reader update`` command, etc.).
+In general, option names match those in the CLI
+(``--feed-root`` -> ``feed_root``);
+options that can be passed multiple times in the CLI
+are pluralized in the config
+(``--cli-plugin`` -> ``cli_plugins``).
+
+Example:
+
+.. literalinclude:: ../examples/config.toml

{reader-3.20 → reader-3.22}/docs/dev.rst

@@ -59,22 +59,22 @@ but I will prioritize supporting :doc:`contributors <contributing>`
 * resource tags
 
   * :ref:`searchable tag values <searchable tags>`, e.g. for comments
-  * :ref:`unification with entry.read/important <entry flag unification>`
   * optimistic locking, :issue:`308`
   * filter tags by prefix, :issue:`309`
 
-
-* HTTP compliance, likely as plugins
+* HTTP behavior / compliance, likely as plugins, :issue:`377`
 
   * 301 Moved Permanently, :issue:`246`
   * 410 Gone, :issue:`246`
-  * 429 Too Many Requests, :issue:`307`
+  * slow down on throttling / max-age, :issue:`378`
+  * match the rhythm of the feed, :issue:`382`
 
 * add more fields to data objects
 
+  * .links attribute, :issue:`320`
+  * .authors attribute, :issue:`391`
   * extra data, as an escape hatch, :issue:`277`
 
-* :ref:`multiple storage implementations <multiple storage implementations>`
 * :ref:`batch get methods <batch get methods>`
 * :doc:`internal` stabilization
 * arbitrary website scraping, :issue:`222`
@@ -93,15 +93,16 @@ but I will prioritize supporting :doc:`contributors <contributing>`
 Command-line interface
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The :doc:`cli` is more or less stable,\ [*]_
-although both the output and config loading need more polish
-and additional tests.
+The :doc:`cli` is more or less stable,
+although it could use additional tests.
 
-A full-blown terminal feed reader is *not* in scope,
+A terminal feed reader is *not* in scope,
 since I don't need one,
-but I'm not opposed to the idea.
+but I'm not opposed to the idea;
+note that the web app should already
+work with text-based browsers such as `Lynx`_.
 
-.. [*] With the exception of ``serve``, which is provided by the web app.
+.. _Lynx: https://en.wikipedia.org/wiki/Lynx_(web_browser)
 
 
 .. _app roadmap:
@@ -109,27 +110,23 @@ but I'm not opposed to the idea.
 Web application
 ~~~~~~~~~~~~~~~
 
-The :doc:`app` is "unsupported",
-in that it's not all that polished,
-and I don't have time to do major improvments.
-But, I am using it daily,
-and it will keep working until a better one exists.
-
-Long term, I'd like to:
-
-* re-design it from scratch to improve usability
-  (see :issue:`318` for a wishlist)
-* switch to `htmx`_ instead of using a home-grown solution
-* spin it off into a separate package/project
+The new :doc:`app` is under active development.
+I am working on adding features
+already implemented in the library
+and the :ref:`legacy web app <legacy web app>`,
+and possibly on a hosted version.
 
-**2025 update**:
-I've started working on a re-design based on `htmx`_ and `Bootstrap`_;
-some :ref:`screenshots <app screenshots>`.
-The new app will be available in parallel with the old one
-until it reaches feature parity.
+Like with the library,
+the goal is to keep it simple to use
+and sustainable to maintain long-term;
+the decision to use `Flask`_, `Bootstrap`_, and `htmx`_ is part of this
+(if they were around for ~15 years,
+they should be around for 15 more).
 
-.. _htmx: https://htmx.org/
+.. _Flask: https://flask.palletsprojects.com/
 .. _Bootstrap: https://getbootstrap.com/
+.. _htmx: https://htmx.org/
+
 
 
 .. _compat:
@@ -677,7 +674,10 @@ Why I want to postpone batch update/set methods:
 tl:dr: Performance is likely a non-issue with SQLite,
 convenience can be added on top as a plugin.
 
-(2025) Why it may be worth adding batch interfaces anyway (even if underneath the storage implementation doesn't actually batch) – it allows for future optimization: https://blog.glyph.im/2022/12/potato-programming.html
+(2025 update) Why it may be worth adding batch interfaces anyway
+(even if underneath the storage implementation doesn't actually batch)
+– it allows for future optimization:
+https://blog.glyph.im/2022/12/potato-programming.html
 
 See the 2.12 reader._app.ResourceTags class for an idea of how to
 represent a bunch of tags in a reserved-name-scheme-agnostic way
@@ -771,10 +771,3 @@ REST API
 
 Some early thoughts: :issue:`192#issuecomment-700773138`
 (closed with `wontfix`, for now).
-
-
-Web application
-~~~~~~~~~~~~~~~
-
-.. toctree::
-    dev-app

{reader-3.20 → reader-3.22}/docs/guide.rst

@@ -21,7 +21,7 @@ The Reader object
 Most *reader* functionality is available through a :class:`Reader` instance,
 which persists feed and entry state
 and provides operations on them;
-in :abbr:`MVC (model–view–controller)` parlance,
+in :abbr:`MVC (model–view–controller)` terms,
 you would probably call it a fat model.
 
 
@@ -270,11 +270,12 @@ Scheduled updates
 ~~~~~~~~~~~~~~~~~
 
 Because different feeds need to be updated at different rates,
-*reader* also provides a mechanism for scheduling updates.
+*reader* also provides a mechanism for scheduling updates
+that is enabled by default.
 
 On every update, *reader* determines when a feed should be updated next
 based on a configurable update interval;
-:meth:`update_feeds(scheduled=True) <Reader.update_feeds>`
+:meth:`~Reader.update_feeds`
 updates only the feeds that should be updated at or before the current time.
 
 The interval can be **configured by the user**
@@ -289,9 +290,9 @@ such that updates don't happen exactly at the the same time;
 for example, with a one-hour interval, a jitter of 0.25 means
 updates will occur any time in the first 15 minutes of each hour.
 
-If the server sends the Retry-After HTTP header with
-429 Too Many Requests or 503 Service Unavailable responses,
-:meth:`update_feeds(scheduled=True) <Reader.update_feeds>` will honor it.
+If the server responds with any of the
+Cache-Control max-age, Expires, or Retry-After HTTP headers,
+:meth:`update_feeds(scheduled=True) <Reader.update_feeds>` will honor them.
 
 
 .. note::
@@ -308,6 +309,12 @@ If the server sends the Retry-After HTTP header with
 .. versionchanged:: 3.15
     Honor the Retry-After HTTP header.
 
+.. versionchanged:: 3.21
+    Honor the Cache-Control max-age and Expires HTTP headers.
+
+.. versionchanged:: 3.21
+    Only update scheduled feeds by default.
+
 
 Update status
 ~~~~~~~~~~~~~
@@ -740,8 +747,8 @@ Plugins
 To use a built-in plugin, pass the plugin name to :func:`make_reader`::
 
     >>> reader = make_reader("db.sqlite", plugins=[
-    ...     "reader.enclosure_dedupe",
-    ...     "reader.entry_dedupe",
+    ...     ".enclosure_dedupe",
+    ...     ".entry_dedupe",
     ... ])
 
 

{reader-3.20 → reader-3.22}/docs/plugins.rst

@@ -39,11 +39,19 @@ use the entry point as a :ref:`custom plugin <custom plugins>`::
 
 
 .. automodule:: reader._plugins.cli_status
-.. automodule:: reader._plugins.preview_feed_list
-.. automodule:: reader._plugins.enclosure_tags
 .. automodule:: reader._plugins.sqlite_releases
 .. automodule:: reader._plugins.timer
-.. automodule:: reader._plugins.share
+
+
+
+Legacy web app plugins
+----------------------
+
+Following are experimental plugins that work with the legacy web app:
+
+.. automodule:: reader._plugins.legacy.preview_feed_list
+.. automodule:: reader._plugins.legacy.enclosure_tags
+.. automodule:: reader._plugins.legacy.share
 
 
 
@@ -92,30 +100,23 @@ You can still find the code on GitHub:
 Loading plugins from the CLI and the web application
 ----------------------------------------------------
 
-There is experimental support of plugins in the CLI and the web application.
-
-.. warning::
-
-    The plugin system/hooks are not stable yet and may change without any notice.
-
-
-To load plugins, set the ``READER_PLUGIN`` environment variable to the plugin
+To load plugins, set the ``READER_PLUGINS`` environment variable to the plugin
 entry point (e.g. ``package.module:entry_point``); multiple entry points should
-be separated by one space::
+be separated by space::
 
-    READER_PLUGIN='first.plugin:entry_point second_plugin:main' \
+    READER_PLUGINS='first.plugin:entry_point second_plugin' \
     python -m reader some-command
 
-For `built-in plugins`_, it is enough to use the plugin name (``reader.XYZ``).
+For `built-in plugins`_, it is enough to use the plugin name (``.plugin``).
 
 .. note::
 
     :func:`make_reader` ignores the plugin environment variables.
 
 
-To load web application plugins, set the ``READER_APP_PLUGIN`` environment variable.
+To load web application plugins, set the ``READER_WEB_PLUGINS`` environment variable.
 To load CLI plugins (that customize the CLI),
-set the ``READER_CLI_PLUGIN`` environment variable.
+set the ``READER_CLI_PLUGINS`` environment variable.