reader 3.22__tar.gz → 3.23__tar.gz

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

@@ -6,6 +6,22 @@ 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
 ------------
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reader
-Version: 3.22
+Version: 3.23
 Summary: A Python feed reader library.
 Author: lemon24
 License: BSD-3-Clause
@@ -113,6 +113,7 @@ you'd probably call it a fat model.
 * 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
 

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

@@ -49,6 +49,7 @@ you'd probably call it a fat model.
 * 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
 

{reader-3.22 → 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.22 → reader-3.23}/docs/app.rst

@@ -62,6 +62,18 @@ Screenshots
 
     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

{reader-3.22 → 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
@@ -25,7 +24,6 @@ for name in [
 
 import reader
 
-
 extensions = [
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',

{reader-3.22 → 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`

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

@@ -705,35 +705,32 @@ you can delete entries using the low-level
 
 
 
-.. _pagination:
+.. _opml:
 
-Pagination
-----------
+OPML import / export
+--------------------
 
-:meth:`~Reader.get_feeds`, :meth:`~Reader.get_entries`,
-and :meth:`~Reader.search_entries`
-can be used in a paginated fashion.
+You can import and export feeds from and to an `OPML subscription list`_
+by using the :meth:`~Reader.import_feeds`
+and :meth:`~Reader.export_feeds` methods::
 
-The ``limit`` argument allows limiting the number of results returned;
-the ``starting_after`` argument allows skipping results until after
-a specific one.
-
-To get the first page, use only ``limit``::
-
-    >>> for entry in reader.get_entries(limit=2):
-    ...     print(entry.title)
+    >>> export = reader.export_feeds()
+    >>> export.filename
+    'reader-feeds-2026-04-24-10-00-00.opml'
+    >>> with open(export.filename, 'wb') as f:
+    ...     f.write(export.content)
     ...
-    H.I. #136: Dog Bingo
-    H.I. #135: Place Your Bets
+    >>> # with another reader instance
+    >>> reader = make_reader(':memory:')
+    >>> with open(export.filename, 'rb') as f:
+    ...     reader.import_feeds(f)
 
-To get the next page, use the last result from a call as
-``starting_after`` in the next call::
+For more detailed control over which feeds are imported,
+see :meth:`~Reader.import_feeds_iter` and the :mod:`reader.opml` module.
 
-    >>> for entry in reader.get_entries(limit=2, starting_after=entry):
-    ...     print(entry.title)
-    ...
-    # H.I. 134: Boxing Day
-    Star Wars: The Rise of Skywalker, Hello Internet Christmas Special
+.. _OPML subscription list: https://opml.org/spec2.opml#subscriptionLists
+
+.. versionadded:: 3.23
 
 
 
@@ -831,6 +828,38 @@ Some examples of how this is useful:
 
 
 
+.. _pagination:
+
+Pagination
+----------
+
+:meth:`~Reader.get_feeds`, :meth:`~Reader.get_entries`,
+and :meth:`~Reader.search_entries`
+can be used in a paginated fashion.
+
+The ``limit`` argument allows limiting the number of results returned;
+the ``starting_after`` argument allows skipping results until after
+a specific one.
+
+To get the first page, use only ``limit``::
+
+    >>> for entry in reader.get_entries(limit=2):
+    ...     print(entry.title)
+    ...
+    H.I. #136: Dog Bingo
+    H.I. #135: Place Your Bets
+
+To get the next page, use the last result from a call as
+``starting_after`` in the next call::
+
+    >>> for entry in reader.get_entries(limit=2, starting_after=entry):
+    ...     print(entry.title)
+    ...
+    # H.I. 134: Boxing Day
+    Star Wars: The Rise of Skywalker, Hello Internet Christmas Special
+
+
+
 .. _reserved names:
 
 Reserved names

{reader-3.22 → reader-3.23}/examples/podcast.py

@@ -14,7 +14,6 @@ import requests
 
 from reader import make_reader
 
-
 feed_url = "http://www.hellointernet.fm/podcast?format=rss"
 podcasts_dir = "podcasts"
 

{reader-3.22 → reader-3.23}/pyproject.toml

@@ -199,4 +199,3 @@ skip_gitignore = true
 filter_files = true
 force_single_line = true
 order_by_type = false
-lines_after_imports = 2

{reader-3.22 → reader-3.23}/scripts/bench.py

@@ -14,7 +14,6 @@ from functools import partial
 
 import click
 
-
 root_dir = os.path.dirname(__file__)
 sys.path.insert(0, os.path.join(root_dir, '../src'))
 sys.path.insert(0, os.path.join(root_dir, '../tests'))

{reader-3.22 → reader-3.23}/scripts/debug_storage_stats.py

@@ -29,7 +29,6 @@ import click
 import numpy as np
 from tabulate import tabulate
 
-
 # assumes dict()s are ordered
 
 value_funcs = {

{reader-3.22 → reader-3.23}/scripts/entry_dedupe_backtest.py

@@ -21,7 +21,6 @@ import time
 from reader import make_reader
 from reader.plugins import entry_dedupe
 
-
 DB_ARCHIVE = "_backups/reader.sqlite.2025-10-04.gz"
 
 file = sys.argv[1]

{reader-3.22 → reader-3.23}/scripts/jscontrols.py

@@ -8,14 +8,12 @@ from flask import jsonify
 from flask import redirect
 from flask import request
 
-
 root_dir = os.path.dirname(__file__)
 sys.path.insert(0, os.path.join(root_dir, '../src'))
 
 from reader._app.api_thing import APIError
 from reader._app.api_thing import APIThing
 
-
 app = Flask(
     __name__,
     template_folder='../src/reader/_app/templates',

{reader-3.22 → reader-3.23}/scripts/vendor_app_stuff.py

@@ -3,7 +3,6 @@ import shutil
 
 import requests
 
-
 STUFF = {
     "htmx.org@2.0.8": ["dist/htmx.min.js"],
     "htmx-ext-response-targets@2.0.4": ["dist/response-targets.min.js"],

{reader-3.22 → reader-3.23}/src/reader/__init__.py

@@ -37,7 +37,7 @@ Print the titles of the unread entries::
 
 """
 
-__version__ = '3.22'
+__version__ = '3.23'
 
 # isort: off
 
@@ -64,6 +64,9 @@ from .types import (
     UpdateResult as UpdateResult,
     UpdatedFeed as UpdatedFeed,
     EntryUpdateStatus as EntryUpdateStatus,
+    FeedToImport as FeedToImport,
+    FeedImportResult as FeedImportResult,
+    FeedExport as FeedExport,
 )
 
 from .exceptions import (
@@ -91,12 +94,13 @@ from .exceptions import (
     InvalidPluginError as InvalidPluginError,
     PluginInitError as PluginInitError,
     ReaderWarning as ReaderWarning,
+    FeedImportError as FeedImportError,
 )
 
-
 # Constants.
 
-USER_AGENT = f'python-reader/{__version__} (+https://github.com/lemon24/reader)'
+SOURCE_URL = 'https://github.com/lemon24/reader'
+USER_AGENT = f'python-reader/{__version__} (+{SOURCE_URL})'
 
 
 # Prevent any logging output by default. If no handler is set,

{reader-3.22 → reader-3.23}/src/reader/__main__.py

@@ -1,6 +1,5 @@
 import sys
 
-
 CANNOT_IMPORT = """\
 Error: cannot import reader._cli
 

{reader-3.22 → reader-3.23}/src/reader/_app/__init__.py

@@ -1,4 +1,6 @@
+import json
 import pathlib
+from dataclasses import asdict
 from datetime import datetime
 from datetime import timedelta
 from datetime import timezone
@@ -28,7 +30,9 @@ from werkzeug.exceptions import NotFound
 from reader import EntryNotFoundError
 from reader import FeedExistsError
 from reader import FeedNotFoundError
+from reader import FeedToImport
 from reader import InvalidFeedURLError
+from reader import opml
 from reader import UpdateError
 
 from .ext import get_reader
@@ -38,7 +42,6 @@ from .forms import ChangeFeedTitle
 from .forms import EntryFilter
 from .forms import FeedFilter
 
-
 # for a prototype with tags and search support, see
 # https://github.com/lemon24/reader/tree/3.21/src/reader/_app/v2
 
@@ -164,6 +167,10 @@ def feeds():
     if form.validate():
         feeds = reader.get_feeds(**kwargs)
 
+    if request.args.get('format', '').lower() == 'opml':
+        export = reader.export_feeds(feeds)
+        return export.content, export.headers
+
     return stream_template(
         'feeds.html',
         form=form,
@@ -270,6 +277,34 @@ def add_feed():
     return render_template('add_feed.html', form=form)
 
 
+@blueprint.route('/feeds/import', methods=['GET', 'POST'])
+def import_feeds():
+    reader = get_reader()
+    parsed_feeds = None
+    error = None
+    imported_feeds = None
+
+    if request.method == 'POST':
+        if file := request.files.get('file'):
+            try:
+                parsed_feeds = [asdict(f) for f in opml.parse(file.stream)]
+            except opml.OPMLError as e:
+                error = str(e)
+        else:
+            feeds = (
+                FeedToImport(**json.loads(f)) for f in request.form.getlist('feed')
+            )
+            imported_feeds = list(reader.import_feeds_iter(feeds))
+            # TODO: out of band update (unlike add, there's too many to do here)
+
+    return render_template(
+        'import_feeds.html',
+        parsed_feeds=parsed_feeds,
+        error=error,
+        imported_feeds=imported_feeds,
+    )
+
+
 @blueprint.route('/entry')
 def entry():
     reader = get_reader()

{reader-3.22 → reader-3.23}/src/reader/_app/ext.py

@@ -10,7 +10,6 @@ from flask import current_app
 from reader import make_reader
 from reader.plugins._loader import PluginLoader
 
-
 _plugin_loader = PluginLoader('init_app')
 
 

{reader-3.22 → reader-3.23}/src/reader/_app/legacy/__init__.py

@@ -44,7 +44,6 @@ from ..ext import ReaderExtension
 from .api_thing import APIError
 from .api_thing import APIThing
 
-
 blueprint = Blueprint(
     'reader', __name__, static_folder='static', template_folder='templates'
 )

{reader-3.22 → reader-3.23}/src/reader/_app/legacy/wsgi.py

@@ -15,7 +15,6 @@ import os
 import reader._app.legacy
 import reader._cli
 
-
 config = reader._cli.load_reader_config()
 app = reader._app.legacy.create_app(config)
 app.config['TRAP_BAD_REQUEST_ERRORS'] = bool(

{reader-3.22 → reader-3.23}/src/reader/_app/templates/add_feed.html

@@ -12,7 +12,9 @@
 
 <h1>Add feed</h1>
 
-<form action="{{ url_for(request.endpoint) }}" method="post" class="my-2">
+<p>Add a single feed:</p>
+
+<form action="{{ url_for(request.endpoint) }}" method="post" class="my-2 mb-4">
 {#- TODO: aria stuff #}
 
 {{ form.csrf_token }}
@@ -43,4 +45,10 @@
 
 </form>
 
+<p>
+  ...or
+  <a href="{{ url_for('.import_feeds') }}">import feeds</a>
+  from an OPML subscription list.
+</p>
+
 {% endblock %}

{reader-3.22 → reader-3.23}/src/reader/_app/templates/feeds.html

@@ -12,7 +12,14 @@
 
 {{ macros.flashed_messages() }}
 
-<h1>Feeds</h1>
+<h1>
+  <span class="me-1">
+    Feeds
+  </span>
+  <a href="{{ url_for(request.endpoint, format='opml', **request.args) }}" class="small" title="export as OPML">
+    <i class="bi bi-filetype-xml text-secondary"></i>
+  </a>
+</h1>
 
 
 {% call macros.filter_form(form) %}

reader-3.23/src/reader/_app/templates/import_feeds.html

@@ -0,0 +1,121 @@
+{% extends "layout.html" %}
+
+{% import "macros.html" as macros %}
+
+
+{% block page_title %}
+  Import feeds - {{ super() }}
+{% endblock %}
+
+
+{% block body %}
+
+<h1>Import feeds</h1>
+
+<form
+  action="{{ url_for(request.endpoint) }}"
+  method="post"
+  enctype="multipart/form-data"
+  class="my-2 mb-4"
+>
+{#- TODO: aria stuff #}
+
+{{ macros.csrf_token_field() }}
+
+{% if parsed_feeds is none and imported_feeds is none %}
+
+  <p>Upload OPML subscription list:</p>
+
+  <div class="mb-3">
+
+  <!-- TODO accept -->
+  <input
+    class="form-control{% if error %} is-invalid {% endif %}"
+    type="file"
+    name="file"
+  >
+  {%- if error %}
+  <div class="invalid-feedback">
+    {{ error }}
+  </div>
+  {%- endif %}
+
+  </div>
+
+  <input type="submit" class="btn btn-primary" value="upload file">
+
+  <a href="javascript:history.back()" class="btn btn-outline-secondary" role="button" >
+    cancel
+  </a>
+
+{% elif parsed_feeds is not none %}
+
+  <p>Select feeds to import:</p>
+
+  {% for feed in parsed_feeds %}
+  <div class="form-check mb-3">
+    <input
+      class="form-check-input"
+      id="feed-{{ loop.index }}"
+      type="checkbox"
+      name="feed"
+      value='{{ feed | tojson }}'
+      checked
+    >
+
+    <label class="form-check-label" for="feed-{{ loop.index }}">
+      {#- NOTE similarity to feeds page feeds #}
+      <h2 class="h5 mb-1" style="font-size: 1.125rem">
+          {{ macros.title_href(
+            feed.title or feed.url,
+            None,
+            external=feed.link,
+            feed_url=feed.url,
+          ) }}
+      </h2>
+      {{ macros.subtitle(feed.subtitle) }}
+    </label>
+
+  </div>
+  {% endfor %}
+
+  <input type="submit" class="btn btn-primary" value="import selected">
+
+  <a href="javascript:history.back()" class="btn btn-outline-secondary" role="button" >
+    cancel
+  </a>
+
+{% else %}
+
+  <p>Imported feeds:</p>
+
+  {% for result in imported_feeds %}
+  {%- set feed = result.feed %}
+  <div class="mb-3">
+
+    {#- NOTE similarity to feeds page feeds #}
+    <h2 class="h5 mb-1" style="font-size: 1.125rem">
+        {{ macros.title_href(
+          feed.title or feed.url,
+          url_for('.entries', feed=feed.url) if not result.error else None,
+          external=feed.link,
+          feed_url=feed.url,
+        ) }}
+    </h2>
+
+    {% if result.added %}
+      {{ macros.subtitle("feed added", 'text-success-emphasis') }}
+    {% elif result.error %}
+      {{ macros.subtitle("invalid feed: {}".format(result.error), 'text-danger-emphasis') }}
+    {% else %}
+      {{ macros.subtitle("feed already exists", 'text-secondary') }}
+    {% endif %}
+
+  </div>
+  {% endfor %}
+
+{% endif %}
+
+</form>
+
+{% endblock %}

{reader-3.22 → reader-3.23}/src/reader/_app/templates/layout_base.html

@@ -1,6 +1,8 @@
 <!doctype html>
 <html lang="en" data-bs-theme="auto">
   <head>
+    {% block head %}
+
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
 
@@ -18,6 +20,7 @@
     <script src="{{ find_static('htmx.min.js', 'reader') }}" defer></script>
     <script src="{{ find_static('response-targets.min.js', 'reader') }}" defer></script>
 
+    {% endblock %}
   </head>
   <body hx-ext="response-targets">
 

{reader-3.22 → reader-3.23}/src/reader/_app/templates/macros.html

@@ -245,7 +245,7 @@
 {% endmacro %}
 
 
-{% macro title_href(text, href=none, external=none) %}
+{% macro title_href(text, href=none, external=none, feed_url=none) %}
 {%- set text = text | truncate(95) -%}
 
 {%- macro maybe_href(text, href) %}
@@ -254,7 +254,7 @@
   {%- if href %}</a>{% endif -%}
 {%- endmacro %}
 
-{%- if not external %}
+{%- if not (external or feed_url) %}
   {{ maybe_href(text, href) }}
 {%- else %}
   {%- set first, _, last = text.strip().rpartition(' ') -%}
@@ -263,19 +263,34 @@
     <span class="me-1">
       {{ maybe_href(last, href) }}
     </span>
-    <a href="{{ external }}" target="_blank" class="text-nowrap small" title="external">
-      <i class="bi bi-box-arrow-up-right text-secondary"></i>
-    </a>
+    {% if external %}
+    <a
+      href="{{ external }}"
+      target="_blank"
+      class="text-nowrap small{% if feed_url %} me-1{% endif %}"
+      title="external"
+    >
+      <i class="bi bi-box-arrow-up-right text-secondary"></i></a>
+    {% endif %}
+    {% if feed_url %}
+    <a
+      href="{{ feed_url }}"
+      target="_blank"
+      class="text-nowrap small"
+      title="feed source"
+    >
+      <i class="bi bi-rss text-secondary"></i></a>
+    {% endif %}
   </span>
 {%- endif %}
 
 {%- endmacro %}
 
 
-{% macro subtitle(text) %}
+{% macro subtitle(text, class=none) %}
 {%- set text = (text or '') | striptags | trim -%}
 {%- if text %}
-<p class="small mb-2">
+<p class="small mb-1{% if class %} {{class}}{% endif %}">
   {{ text | truncate(223) }}
 </p>
 {%- endif %}