reader 3.25__tar.gz → 3.26__tar.gz

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

@@ -6,6 +6,18 @@ Changelog
   :no-index:
 
 
+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 +27,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`)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reader
-Version: 3.25
+Version: 3.26
 Summary: A Python feed reader library.
 Author: lemon24
 License: BSD-3-Clause
@@ -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.26}/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.26}/docs/guide.rst

@@ -139,15 +139,18 @@ since each connection would be to a *different* database::
 
 .. _backups:
 
-Back-ups
-~~~~~~~~
+Backups
+~~~~~~~
 
-Making back-ups depends on the storage used.
+Making backups generally depends on the storage used.
 
-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).
+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 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.26}/pyproject.toml

@@ -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",

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

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

{reader-3.25 → reader-3.26}/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.26}/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.26/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.26}/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.26}/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.26}/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.26}/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.26}/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.26/src/reader/_app/templates/settings.html

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

reader-3.26/src/reader/_app/templates/settings_base.html

@@ -0,0 +1,67 @@
+{% extends "layout.html" %}
+
+{% import "macros.html" as macros %}
+
+
+{% block page_title %}
+  Settings - {{ super() }}
+{% endblock %}
+
+
+{% block body %}
+
+<h1>Settings</h1>
+
+
+<h2 id="exports">Export database</h2>
+
+<p>
+  Export your entire <em>reader</em> database,
+  for backup or use with another installation.
+
+{{ macros.flashed_messages(['exports.danger']) }}
+
+<div class="card my-3">
+  <div class="card-header">
+   Recent exports
+  </div>
+
+  <ul class="list-group list-group-flush">
+    {%- for path, date in exports | sort(reverse=True) %}
+    <li class="list-group-item d-flex flex-wrap justify-content-between align-items-center gap-2">
+      <span>
+        <a href="{{ url_for('.get_export', name=path.name) }}" class="d-inline-block">
+          <time datetime="{{ date }}" title="{{ date }}">
+            {{ date | humanize_naturaltime }}
+          </time>
+        </a>
+        <span class="text-secondary">({{ path.stat().st_size | filesizeformat }})</span>
+      </span>
+
+      <form action="{{ url_for('.delete_export', name=path.name) }}" method="post">
+        {{ macros.csrf_token_field() }}
+        <input type="submit" class="btn btn-outline-danger btn-sm" value="delete">
+      </form>
+
+    </li>
+    {%- else %}
+    <li class="list-group-item">
+      no exports found
+    </li>
+    {%- endfor %}
+  </ul>
+
+</div>
+
+<form action="{{ url_for('.create_export') }}" method="post" class="my-3">
+  {{ macros.csrf_token_field() }}
+  <input type="submit" class="btn btn-secondary" value="create new export">
+</form>
+
+<p class="text-secondary">
+  To export feeds as a subscription list, click the
+  <i class="bi bi-filetype-xml" aria-label="export as OPML"></i> icon
+  on the <a href="{{ url_for('.feeds') }}">Feeds</a> page.
+
+
+{% endblock %}

{reader-3.25 → reader-3.26}/src/reader/_cli.py

@@ -459,6 +459,18 @@ def search_entries(reader, query):
         click.echo(f"{entry.feed.url} {entry.link or entry.id}")
 
 
+@cli.command()
+@click.argument('outdir', type=click.Path(exists=True, file_okay=False), default='.')
+@click.option('--prefix', default="reader.%Y-%m-%d-%H-%M-%S", show_default=True)
+@pass_reader
+def export(reader, outdir, prefix):
+    """Export all data to a file in OUTDIR (defaults to cwd)."""
+
+    concrete_prefix = reader._now().strftime(prefix)
+    export_path = reader._storage.export(outdir, concrete_prefix)
+    click.echo(export_path)
+
+
 try:
     import reader._app.cli
 except ImportError:

{reader-3.25 → reader-3.26}/src/reader/_storage/_base.py

@@ -2,12 +2,14 @@ from __future__ import annotations
 
 import json
 import os
+import pathlib
 import sqlite3
 import sys
 from collections.abc import Callable
 from collections.abc import Iterable
 from functools import partial
 from typing import Any
+from typing import Self
 from typing import TypeVar
 
 from ..exceptions import StorageError
@@ -82,8 +84,9 @@ class StorageBase:
         )
 
     @wrap_exceptions()
-    def __enter__(self) -> None:
+    def __enter__(self) -> Self:
         self.factory.__enter__()
+        return self
 
     @wrap_exceptions()
     def __exit__(self, *_: Any) -> None:
@@ -109,3 +112,30 @@ class StorageBase:
                 last,
                 row_factory,
             )
+
+    def export(self, outdir: str | os.PathLike[str], prefix: str) -> pathlib.Path:
+        import gzip
+        import shutil
+        import tempfile
+
+        outdir = pathlib.Path(outdir)
+        gz = outdir / self.export_name(prefix)
+
+        with tempfile.TemporaryDirectory(f".{prefix}", dir=outdir) as tmpdir_str:
+            tmpdir = pathlib.Path(tmpdir_str)
+
+            tmp_db = tmpdir / 'db'
+            self.get_db().execute("vacuum into ?", (str(tmp_db),))
+
+            # the file name is stored in the .gz file
+            tmp_gz = tmpdir / gz.with_suffix('').name
+            with tmp_db.open('rb') as db_file:
+                with gzip.open(tmp_gz, 'wb') as gz_file:
+                    shutil.copyfileobj(db_file, gz_file)
+
+            tmp_gz.replace(gz)
+
+        return gz
+
+    def export_name(self, prefix: str) -> str:
+        return f"{prefix}.sqlite.gz"

{reader-3.25 → reader-3.26}/src/reader/_types.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import os
+import pathlib
 from collections.abc import Iterable
 from collections.abc import Mapping
 from collections.abc import Sequence
@@ -727,7 +729,7 @@ class StorageType(Protocol):  # pragma: no cover
 
     """
 
-    def __enter__(self) -> None:
+    def __enter__(self) -> Self:
         """Called when :class:`.Reader` is used as a context manager."""
 
     def __exit__(self, *_: Any) -> None:
@@ -1113,6 +1115,17 @@ class StorageType(Protocol):  # pragma: no cover
 
         """
 
+    def export(self, outdir: str | os.PathLike[str], prefix: str) -> pathlib.Path:
+        """Export all data to a file in ``outdir`` and return its full path.
+
+        Aside from starting with ``prefix``,
+        the file name and contents are storage-dependent.
+
+        """
+
+    def export_name(self, prefix: str) -> str:
+        """Return the file name of an export."""
+
 
 @runtime_checkable
 class BoundSearchStorageType(StorageType, Protocol):

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reader
-Version: 3.25
+Version: 3.26
 Summary: A Python feed reader library.
 Author: lemon24
 License: BSD-3-Clause
@@ -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.26}/src/reader.egg-info/SOURCES.txt

@@ -20,11 +20,13 @@ docs/internal.rst
 docs/plugins.rst
 docs/tutorial.rst
 docs/why.rst
+docs/screenshots/autodiscovery.png
 docs/screenshots/empty.png
 docs/screenshots/entries-filters-light.png
 docs/screenshots/entries.png
 docs/screenshots/entry-image-light.png
 docs/screenshots/entry.png
+docs/screenshots/export-database.png
 docs/screenshots/feed.png
 docs/screenshots/feeds.png
 docs/screenshots/help.png
@@ -36,7 +38,6 @@ examples/feed_slugs.py
 examples/parser_only.py
 examples/podcast.py
 examples/terminal.py
-scripts/backup.sh
 scripts/bench.py
 scripts/debug_storage_stats.py
 scripts/entry_dedupe_backtest.py
@@ -67,6 +68,7 @@ src/reader.egg-info/requires.txt
 src/reader.egg-info/top_level.txt
 src/reader/_app/__init__.py
 src/reader/_app/cli.py
+src/reader/_app/exports.py
 src/reader/_app/ext.py
 src/reader/_app/forms.py
 src/reader/_app/wsgi.py
@@ -104,6 +106,8 @@ src/reader/_app/templates/import_feeds.html
 src/reader/_app/templates/layout.html
 src/reader/_app/templates/layout_base.html
 src/reader/_app/templates/macros.html
+src/reader/_app/templates/settings.html
+src/reader/_app/templates/settings_base.html
 src/reader/_parser/__init__.py
 src/reader/_parser/_http_utils.py
 src/reader/_parser/_url_utils.py