reader 3.25__tar.gz → 3.27__tar.gz

{reader-3.25 → reader-3.27}/CHANGES.rst

@@ -6,6 +6,41 @@ Changelog
   :no-index:
 
 
+Version 3.27
+------------
+
+Released 2026-10-11
+
+* Add the ``migrate`` :func:`make_reader` argument.
+  Thanks to `Divyanshi Purohit`_ for the PR.
+  (:issue:`403`)
+* Add :attr:`~EntryCounts.unread` property to
+  :class:`EntryCounts` and :class:`EntrySearchCounts`.
+  (:issue:`283`)
+
+* Support Python 3.15. (:issue:`418`)
+* Support PyPy 3.12. (:issue:`419`)
+* Drop Python 3.11 support. (:issue:`419`)
+
+* Stop vendoring `feedparser`_ and
+  :ref:`recommend installing it from GitHub instead <no-vendored-feedparser>`.
+* Pin GitHub Actions and add zizmor to CI.
+
+.. _Divyanshi Purohit: https://github.com/divyanshi555
+
+
+Version 3.26
+------------
+
+Released 2026-06-24
+
+* Allow exporting the entire database (e.g. for backup or migration).
+
+  * Through the :meth:`~reader._types.StorageType.export` storage method.
+  * In the web app, on the settings page; :ref:`screenshots <screenshots-export>`.
+  * In the CLI, as a new ``export`` command.
+
+
 Version 3.25
 ------------
 
@@ -15,7 +50,8 @@ Released 2026-05-25
 
   * Add :mod:`~reader.plugins.autodiscover` built-in plugin.
   * Add :mod:`reader.discover` module providing low level discovery.
-  * In the web app, show :mod:`~reader.plugins.autodiscover` suggestions when adding a feed.
+  * In the web app, show :mod:`~reader.plugins.autodiscover` suggestions
+    when adding a feed; :ref:`screenshots <screenshots-autodiscovery>`.
 
 * Fix bugs that may cause the 3.24 database migration to fail. (:issue:`405`)
 
@@ -579,7 +615,7 @@ Released 2023-08-20
 
 * Make :exc:`ReaderWarning` inherit from :exc:`ReaderError`.
 
-* Include a diagram of the :ref:`exctree` in the :doc:`api`.
+* Include a diagram of the :ref:`exception hierarchy <exctree>` in the :doc:`api`.
 
 * Add werkzeug dependency,
   instead of vendoring selected :mod:`werkzeug.http` utilities.

{reader-3.25/src/reader.egg-info → reader-3.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reader
-Version: 3.25
+Version: 3.27
 Summary: A Python feed reader library.
 Author: lemon24
 License: BSD-3-Clause
@@ -19,10 +19,10 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Internet
@@ -32,7 +32,7 @@ Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: typing-extensions>=4
@@ -49,6 +49,8 @@ Provides-Extra: app
 Requires-Dist: flask>=0.10; extra == "app"
 Requires-Dist: humanize>=4; extra == "app"
 Requires-Dist: PyYAML; extra == "app"
+Requires-Dist: click; extra == "app"
+Requires-Dist: platformdirs; extra == "app"
 Requires-Dist: WTForms; extra == "app"
 Requires-Dist: Flask-WTF; extra == "app"
 Requires-Dist: jinja2-fragments; extra == "app"

{reader-3.25 → reader-3.27}/docs/api.rst

@@ -60,9 +60,11 @@ Data objects
 
 .. autoclass:: EntryCounts
     :members:
+    :inherited-members:
 
 .. autoclass:: EntrySearchCounts
     :members:
+    :inherited-members:
 
 .. autoclass:: UpdateResult
     :members:
@@ -85,9 +87,16 @@ Data objects
 
 
 
+.. _exctree:
+
 Exceptions
 ----------
 
+The class hierarchy for :mod:`reader` exceptions is:
+
+.. classtree:: ReaderError
+
+
 .. autoexception:: ReaderError
     :members:
 
@@ -180,16 +189,6 @@ Exceptions
     :show-inheritance:
 
 
-.. _exctree:
-
-Exception hierarchy
-~~~~~~~~~~~~~~~~~~~
-
-The class hierarchy for :mod:`reader` exceptions is:
-
-.. classtree:: ReaderError
-
-
 
 Enumerations
 ------------

{reader-3.25 → reader-3.27}/docs/app.rst

@@ -19,6 +19,8 @@ Features, as of *reader* version |version|:
 * article view
 * custom feed titles
 * dark mode
+* feed autodiscovery
+* full data export
 
 More features already implemented in the library
 and the :ref:`legacy web app <legacy web app>`
@@ -86,6 +88,20 @@ Screenshots
 
     contextual help
 
+.. _screenshots-autodiscovery:
+
+.. figure:: screenshots/autodiscovery.png
+    :width: 240px
+
+    feed autodiscovery
+
+.. _screenshots-export:
+
+.. figure:: screenshots/export-database.png
+    :width: 240px
+
+    database exports
+
 
 Serving the web app
 -------------------

{reader-3.25 → reader-3.27}/docs/conf.py

@@ -78,7 +78,7 @@ autodoc_typehints_description_target = 'documented'
 autodoc_type_aliases = {
     'ResourceInput': 'reader.types.ResourceInput',
     'AnyResourceInput': 'reader.types.AnyResourceInput',
-    'JSONType': 'reader.types.JSONType',
+    'JSON': 'reader.types.JSON',
     'TagFilter': 'reader._types.TagFilter',
     'TristateFilter': 'reader._types.TristateFilter',
 }
@@ -226,5 +226,19 @@ def class_tree(cls):
     return '\n'.join(output(classes)) + '\n'
 
 
+import builtins
+
+std_dir = builtins.dir
+
+
+def source_order_dir(obj):
+    if isinstance(obj, type):
+        return [name for cls in obj.mro() for name in cls.__dict__.keys()]
+    return std_dir(obj)
+
+
 def setup(app):
     app.add_directive("classtree", ClassTree)
+
+    # TODO: remove when https://github.com/sphinx-doc/sphinx/issues/628 is resolved
+    builtins.dir = source_order_dir

{reader-3.25 → reader-3.27}/docs/guide.rst

@@ -137,17 +137,30 @@ since each connection would be to a *different* database::
 .. _temporary: https://sqlite.org/inmemorydb.html#temp_db
 
 
+Migrations
+~~~~~~~~~~
+
+Schema migrations depend on the storage used.
+
+For the default SQLite storage,
+migrations happen automatically during :func:`make_reader`,
+unless you pass ``migrate=False``.
+
+
 .. _backups:
 
-Back-ups
-~~~~~~~~
+Backups
+~~~~~~~
+
+Making backups generally depends on the storage used.
 
-Making back-ups depends on the storage used.
+If the storage implements it, you can use
+the :meth:`~reader._types.StorageType.export` method
+or the ``export`` :doc:`CLI <cli>` command.
 
-For the SQLite storage, you should use
-the `sqlite3 .backup command <https://sqlite.org/cli.html>`_
-or `VACUUM INTO <https://www.sqlite.org/lang_vacuum.html>`_
-(see :gh:`backup.sh <scripts/backup.sh>` for an example).
+For the SQLite storage, you can also use
+the `.backup command <https://sqlite.org/cli.html>`_
+or `VACUUM INTO <https://www.sqlite.org/lang_vacuum.html>`_.
 
 
 

{reader-3.25 → reader-3.27}/docs/install.rst

@@ -28,14 +28,12 @@ These packages will be installed automatically when installing *reader*:
 
 .. note::
 
-  Because `feedparser`_ makes PyPI releases at a lower cadence,
-  *reader* uses a vendored version of feedparser's `develop`_ branch
-  by default since :ref:`version 2.9`.
-  To opt out of this behavior, and make *reader* use
-  the installed ``feedparser`` package,
-  set the ``READER_NO_VENDORED_FEEDPARSER`` environment variable to ``1``.
-
-.. _develop: https://github.com/kurtmckee/feedparser
+  The `feedparser`_ ``main`` branch contains a `change`_
+  that decreases memory usage by ~35% during feed updates;
+  as of feedparser 6.0.14, this change is not yet included in PyPI releases;
+  to benefit from it, install feedparser directly from GitHub.
+
+  .. _change: https://github.com/kurtmckee/feedparser/pull/302
 
 
 .. _optional dependencies:

{reader-3.25 → reader-3.27}/docs/internal.rst

@@ -87,7 +87,7 @@ Data objects
 .. autoclass:: ParsedFeed
     :members:
 
-.. autoclass:: HTTPInfo
+.. autoclass:: RetrieveMetadata
     :members:
 
 

{reader-3.25 → reader-3.27}/pyproject.toml

@@ -19,10 +19,10 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",
     "Topic :: Internet",
@@ -33,7 +33,7 @@ classifiers = [
     "Topic :: Utilities",
     "Typing :: Typed",
 ]
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 dependencies = [
     "typing-extensions>=4",
     "feedparser>=6",
@@ -65,8 +65,11 @@ cli = [
 app = [
     "flask>=0.10",
     "humanize>=4",
-    # for config
+    # for legacy (tags)
     "PyYAML",
+    # for cli
+    "click",
+    "platformdirs",
     # for v2
     "WTForms",
     "Flask-WTF",
@@ -173,6 +176,9 @@ files = ["src"]
 show_error_codes = true
 pretty = true
 strict = true
+strict_equality_for_none = true
+warn_unreachable = true
+
 [[tool.mypy.overrides]]
 module = [
     "reader.__main__",
@@ -187,7 +193,6 @@ module = [
     "reader.plugins.readtime",
     "reader.plugins.mark_as_read",
     "reader.plugins.autodiscover",
-    "reader._vendor.feedparser.*",
 ]
 ignore_errors = true
 

{reader-3.25 → reader-3.27}/scripts/release.py

@@ -20,18 +20,8 @@ def run(*args, **kwargs):
     return subprocess.run(*args, check=True, **kwargs)
 
 
-def run_no_venv(*args, **kwargs):
-    env = os.environ.copy()
-    virtual_env = env.pop('VIRTUAL_ENV', None)
-    if virtual_env:
-        env['PATH'] = ':'.join(
-            p for p in env['PATH'].split(':') if not p.startswith(virtual_env)
-        )
-    return run(*args, env=env, **kwargs)
-
-
 def run_tox():
-    run_no_venv('tox -p all', shell=True)
+    run('tox -p all', shell=True)
 
 
 def path_sub(pattern, repl, path):

{reader-3.25 → reader-3.27}/src/reader/__init__.py

@@ -37,7 +37,7 @@ Print the titles of the unread entries::
 
 """
 
-__version__ = '3.25'
+__version__ = '3.27'
 
 # isort: off
 

{reader-3.25 → reader-3.27}/src/reader/_app/__init__.py

@@ -19,6 +19,7 @@ from flask import render_template
 from flask import render_template_string
 from flask import request
 from flask import Response
+from flask import send_from_directory
 from flask import stream_with_context
 from flask import url_for
 from flask_wtf.csrf import CSRFError
@@ -35,6 +36,9 @@ from reader import InvalidFeedURLError
 from reader import opml
 from reader import UpdateError
 
+from .exports import ExportNotFoundError
+from .exports import TooManyExportsError
+from .ext import get_exports
 from .ext import get_reader
 from .ext import ReaderExtension
 from .forms import AddFeed
@@ -94,7 +98,7 @@ def entries():
         hostname = urlparse(feed.url).hostname
         autodiscover = [
             (link, hostname and urlparse(link['href']).hostname == hostname)
-            for link in reader.get_tag(feed, autodiscover_tag, None)
+            for link in reader.get_tag(feed, autodiscover_tag, ())
         ]
 
     kwargs = dict(form.data)
@@ -356,6 +360,38 @@ def help():
     return render_template('help.html')
 
 
+@blueprint.route('/settings')
+def settings():
+    return render_template('settings.html', exports=get_exports().list())
+
+
+@blueprint.route('/settings/exports', methods=['POST'])
+def create_export():
+    try:
+        get_exports().create()
+    except TooManyExportsError:
+        flash("Too many exports, delete some of them first.", 'exports.danger')
+    return redirect(url_for('.settings', _anchor='exports'), code=303)
+
+
+@blueprint.route('/settings/exports/<name>')
+def get_export(name):
+    exports = get_exports()
+    if not exports.exists(name):
+        abort(404)
+    return send_from_directory(exports.path, name, as_attachment=True)
+
+
+@blueprint.route('/settings/exports/<name>/delete', methods=['POST'])
+def delete_export(name):
+    # flask should ensure <name> doesn't contain slashes etc.
+    try:
+        get_exports().delete(name)
+    except ExportNotFoundError:
+        abort(404)
+    return redirect(url_for('.settings', _anchor='exports'), code=303)
+
+
 def stream_template(template_name_or_list, **kwargs):
     # Ensure flashed messages get removed from the session,
     # otherwise they keep adding up and never disappear.

{reader-3.25 → reader-3.27}/src/reader/_app/cli.py

@@ -1,5 +1,9 @@
+import pathlib
+
 import click
+import platformdirs
 
+from reader._cli import app_name
 from reader._cli import load_reader_config_from_context
 from reader._cli import setup_logging
 
@@ -26,9 +30,16 @@ def make_add_response_headers_middleware(wsgi_app, headers):
     help="Import path to a web app plug-in. Can be passed multiple times.",
 )
 @click.option('--legacy/--no-legacy', help="Serve the legacy app.")
+@click.option(
+    '--cache-dir',
+    type=click.Path(file_okay=False, path_type=pathlib.Path),
+    default=platformdirs.user_cache_dir(app_name),
+    show_default=True,
+    help="The directory to store cache data in.",
+)
 @click.option('-v', '--verbose', count=True)
 @click.pass_context
-def cli(ctx, host, port, plugins, legacy, verbose):
+def cli(ctx, host, port, plugins, legacy, cache_dir, verbose):
     """Run a local HTTP reader server."""
 
     setup_logging(verbose)

reader-3.27/src/reader/_app/exports.py

@@ -0,0 +1,58 @@
+import pathlib
+from datetime import datetime
+from datetime import timezone
+
+
+class TooManyExportsError(Exception):
+    pass
+
+
+class ExportNotFoundError(Exception):
+    pass
+
+
+class Exports:
+
+    max_files = 2
+    prefix_fmt = "reader.%Y-%m-%d-%H-%M-%S"
+
+    def __init__(self, reader, path):
+        self.reader = reader
+        self.path = pathlib.Path(path)
+        self.path.mkdir(parents=True, exist_ok=True)
+
+    def parse_name(self, name):
+        name_fmt = self.reader._storage.export_name(self.prefix_fmt)
+        try:
+            dt = datetime.strptime(name, name_fmt)
+        except ValueError:
+            return None
+        else:
+            return dt.replace(tzinfo=timezone.utc)
+
+    def create(self):
+        # not looking at file names accounts for exports in progress
+        if len(list(self.path.iterdir())) >= self.max_files:
+            raise TooManyExportsError
+        prefix = self.reader._now().strftime(self.prefix_fmt)
+        self.reader._storage.export(self.path, prefix)
+
+    def exists(self, name):
+        if not self.parse_name(name):
+            return False
+        return (self.path / name).exists()
+
+    def list(self):
+        rv = []
+        for path in self.path.iterdir():
+            if dt := self.parse_name(path.name):
+                rv.append((path, dt))
+        return rv
+
+    def delete(self, name):
+        if not self.parse_name(name):
+            raise ExportNotFoundError
+        try:
+            (self.path / name).unlink()
+        except FileNotFoundError:
+            raise ExportNotFoundError from None

{reader-3.25 → reader-3.27}/src/reader/_app/ext.py

@@ -3,6 +3,7 @@ Flask extension that encapsulates configurable reader-related aspects.
 
 """
 
+import pathlib
 from dataclasses import dataclass
 
 from flask import current_app
@@ -10,13 +11,20 @@ from flask import current_app
 from reader import make_reader
 from reader.plugins._loader import PluginLoader
 
-_plugin_loader = PluginLoader('init_app')
+from .exports import Exports
 
 
 def get_reader():
     return current_app.extensions['reader'].get_reader()
 
 
+def get_exports():
+    return current_app.extensions['reader'].get_exports()
+
+
+_plugin_loader = PluginLoader('init_app')
+
+
 class ReaderExtension:
 
     def __init__(self, app=None, state_cls=None):
@@ -26,26 +34,45 @@ class ReaderExtension:
 
     def init_app(self, app):
         config = app.config['READER']
-        app.extensions['reader'] = self.state_cls(config[''])
+        app.extensions['reader'] = self.state_cls(
+            config[''], config.get('web', {}).get('cache_dir')
+        )
         _plugin_loader.oneshot(app, config.get('web', {}).get('plugins', ()))
 
 
 @dataclass
 class ReaderStateBase:
     args: dict
+    cache_dir: pathlib.Path | None
 
     def get_reader(self):
         raise NotImplementedError
 
+    def get_user_cache_dir(self):
+        raise NotImplementedError
+
     def _make_reader(self, **kwargs):
         return make_reader(**self.args | kwargs)
 
+    def get_exports(self):
+        cache_dir = self.get_user_cache_dir()
+        if not cache_dir:
+            return None
+        return Exports(self.get_reader(), cache_dir / 'exports')
+
 
 class _ReaderState(ReaderStateBase):
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self._reader = self._make_reader()
+        self._exports = super().get_exports()
 
     def get_reader(self):
         return self._reader
+
+    def get_user_cache_dir(self):
+        return self.cache_dir
+
+    def get_exports(self):
+        return self._exports

{reader-3.25 → reader-3.27}/src/reader/_app/static/style.css

@@ -69,8 +69,6 @@
   height: auto;
 }
 
-
-:target {
-  outline: 0;
-  box-shadow: var(--bs-focus-ring-x, 0) var(--bs-focus-ring-y, 0) var(--bs-focus-ring-blur, 0) var(--bs-focus-ring-width) var(--bs-focus-ring-color);
+h1:target, h2:target, h3:target, h4:target, h5:target, h6:target {
+  text-decoration: underline;
 }

{reader-3.25 → reader-3.27}/src/reader/_app/templates/entries.html

@@ -19,7 +19,7 @@
 {{ macros.flashed_messages() }}
 
 {%- if feed and not feed.url.startswith('reader:') %}
-  <ul class="list-unstyled mt-3">
+  <ul class="list-unstyled">
 
     {%- if not feed.last_updated and not feed.last_exception %}
       <li class="alert alert-secondary">

{reader-3.25 → reader-3.27}/src/reader/_app/templates/layout_base.html

@@ -62,10 +62,13 @@
       <ul class="navbar-nav mb-0">
         {% block right_hidden_navbar %}
 
+        {% block right_hidden_navbar_common %}
+
         <li class="nav-item">
           <a
             href="{{ url_for('reader.help', _anchor=help_topic | default(none)) }}"
             class="btn btn-link nav-link d-flex align-items-center"
+            title="help"
           >
             <i class="bi bi-question-lg"></i>
             <span class="d-md-none ms-2">help</span>
@@ -78,7 +81,7 @@
             type="button" id="theme"
             data-bs-toggle="dropdown" data-bs-display="static"
             aria-expanded="false" aria-label="toggle theme (auto)">
-            <i class="bi bi-circle-half theme-icon-active"></i>
+            <i class="bi bi-circle-half theme-icon-active" title="toggle theme"></i>
             <span class="d-md-none ms-2" id="theme-text">toggle theme</span>
           </button>
           <ul class="dropdown-menu dropdown-menu-end mb-2" aria-labelledby="theme-text">
@@ -110,6 +113,19 @@
         </li>
 
         {% endblock %}
+
+        <li class="nav-item">
+          <a
+            href="{{ url_for('reader.settings') }}"
+            class="btn btn-link nav-link d-flex align-items-center"
+            title="settings"
+          >
+            <i class="bi bi-gear-fill"></i>
+            <span class="d-md-none ms-2">settings</span>
+          </a>
+        </li>
+
+        {% endblock %}
       </ul>
     </div>
   </div>

{reader-3.25 → reader-3.27}/src/reader/_app/templates/macros.html

@@ -1,9 +1,10 @@
 
-{% macro flashed_messages() %}
-{%- if get_flashed_messages() %}
+{% macro flashed_messages(category_filter=()) %}
+{%- set messages = get_flashed_messages(True, category_filter) %}
+{%- if messages %}
 <ul class="list-unstyled">
-{%- for category, message in get_flashed_messages(with_categories=true) %}
-  <li class="alert alert-{{ category }}">{{ message }}</li>
+{%- for category, message in messages %}
+  <li class="alert alert-{{ category.rpartition('.')[2] }}">{{ message }}</li>
 {%- endfor %}
 </ul>
 {%- endif %}

reader-3.27/src/reader/_app/templates/settings.html

@@ -0,0 +1 @@
+{% extends "settings_base.html" %}