reader 3.21__tar.gz → 3.23__tar.gz

{reader-3.21 → reader-3.23}/CHANGES.rst

@@ -6,6 +6,75 @@ Changelog
   :no-index:
 
 
+Version 3.23
+------------
+
+Released 2026-04-24
+
+* Add support for :ref:`opml`. (:issue:`165`)
+
+  * Add support for import / export in the web app; :ref:`screenshots <screenshots-import>`.
+
+* Deprecate the :func:`~reader.utils.archive_entries` ``feed_user_title`` argument.
+* Fix :meth:`get_feeds(feed='') <Reader.get_feeds>` and
+  :meth:`get_entries(entry=('', '')) <Reader.get_entries>`
+  returning wrong entries.
+  (:issue:`392`)
+
+
+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
 ------------
 
@@ -251,7 +320,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`)
@@ -294,7 +363,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.
@@ -445,7 +514,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`)
@@ -506,7 +575,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.21 → reader-3.23}/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.21/src/reader.egg-info → reader-3.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reader
-Version: 3.21
+Version: 3.23
 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
 
@@ -111,6 +113,7 @@ and without depending on a particular framework.
 * filter feeds and articles
 * full-text search articles
 * get statistics on feed and user activity
+* import / export feeds as OPML
 * write plugins to extend its functionality
 * skip all the low level stuff and focus on what makes your feed reader different
 
@@ -122,19 +125,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.21 → reader-3.23}/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
 
@@ -47,6 +49,7 @@ and without depending on a particular framework.
 * filter feeds and articles
 * full-text search articles
 * get statistics on feed and user activity
+* import / export feeds as OPML
 * write plugins to extend its functionality
 * skip all the low level stuff and focus on what makes your feed reader different
 
@@ -58,19 +61,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.21 → reader-3.23}/docs/api.rst

@@ -67,6 +67,17 @@ Data objects
 .. autoclass:: EntryUpdateStatus
     :members:
 
+.. autoclass:: FeedToImport
+    :members:
+    :undoc-members:
+
+.. autoclass:: FeedImportResult
+    :members:
+
+.. autoclass:: FeedExport
+    :members:
+
+
 
 Exceptions
 ----------
@@ -155,6 +166,9 @@ Exceptions
 .. autoexception:: PluginInitError
     :show-inheritance:
 
+.. autoexception:: FeedImportError
+    :show-inheritance:
+
 
 .. autoexception:: ReaderWarning
     :show-inheritance:
@@ -214,3 +228,10 @@ Utilities
 ---------
 
 .. autofunction:: reader.utils.archive_entries
+
+
+
+``reader.opml``
+---------------
+
+.. automodule:: reader.opml

reader-3.23/docs/app.rst

@@ -0,0 +1,153 @@
+
+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)
+
+.. _screenshots-import:
+
+.. figure:: screenshots/import-select.png
+    :width: 240px
+
+    import feeds (select)
+
+.. figure:: screenshots/import-result.png
+    :width: 240px
+
+    import feeds (result)
+
+
+
+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.21 → reader-3.23}/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.21 → reader-3.23}/docs/conf.py

@@ -6,7 +6,6 @@ import unittest.mock
 import packaging.version
 from setuptools.config.pyprojecttoml import read_configuration
 
-
 sys.path.insert(0, os.path.abspath('../src'))
 
 # mock some things "by hand", so we can import reader below without any dependencies
@@ -17,6 +16,7 @@ for name in [
     'flask.signals',
     'werkzeug',
     'werkzeug.datastructures',
+    'werkzeug.exceptions',
     'werkzeug.http',
     'yaml',
 ]:
@@ -24,7 +24,6 @@ for name in [
 
 import reader
 
-
 extensions = [
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',
@@ -45,6 +44,7 @@ autodoc_mock_imports = [
     'bs4',
     'mutagen',
     'flask',
+    'flask_wtf',
     'werkzeug',
     'humanize',
     'markupsafe',

reader-3.23/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.21 → reader-3.23}/docs/dev.rst

@@ -32,7 +32,6 @@ in my spare time,
 but I will prioritize supporting :doc:`contributors <contributing>`
 (discussions, reviews and so on).
 
-* OPML support, :issue:`165`
 * :ref:`deleting entries <deleting entries>`
 
   * archiving important entries of deleted feeds, :issue:`290`
@@ -59,22 +58,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 +92,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 +109,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 +673,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 +770,3 @@ REST API
 
 Some early thoughts: :issue:`192#issuecomment-700773138`
 (closed with `wontfix`, for now).
-
-
-Web application
-~~~~~~~~~~~~~~~
-
-.. toctree::
-    dev-app