reader 3.22__tar.gz → 3.24__tar.gz

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

@@ -6,6 +6,68 @@ Changelog
   :no-index:
 
 
+Version 3.24
+------------
+
+Released 2026-05-20
+
+* Support multiple authors with details (link, email).
+  Thanks to `Anshul Mittal`_ for the PR.
+  (:issue:`391`)
+
+  * Add :attr:`Feed.authors`, :attr:`Entry.authors`,
+    and :attr:`EntrySource.authors` attributes.
+  * Add matching :attr:`~Feed.authors_str` property.
+  * Deprecate :attr:`~Feed.author` attribute.
+
+* Fix bug introduced in `version 3.15 <Version 3.15_>`__
+  causing feeds to not be retrieved in parallel
+  even if :meth:`~Reader.update_feeds` was called with ``workers`` > 1.
+
+* Use :ref:`structured logging <logging>` internally,
+  with the possibility to opt into native `structlog`_ logging.
+  (:issue:`147`)
+
+* Use :meth:`datetime.datetime.fromisoformat` instead of external dependency ``iso8601``.
+  Thanks to `Sebastian Bradley`_ for the PR.
+  (:issue:`398`)
+
+* Refactor updater internals to allow reusing logic in alternate implementations.
+
+* :doc:`app` improvements.
+
+  * Add empty state and contextual help; :ref:`screenshots <screenshots-help>`.
+  * Import feeds improvements (select all/none, accept only XML / OPML files).
+
+* Add ``--json`` option to the ``list`` CLI commands.
+  Thanks to `Puneet Dixit`_ for the PR.
+  (:issue:`394`)
+
+
+
+.. _Puneet Dixit: https://github.com/puneetdixit200
+.. _Anshul Mittal: https://github.com/anderson688
+.. _Sebastian Bradley: https://github.com/bazbrad765
+
+.. _structlog: https://www.structlog.org/
+
+
+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.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reader
-Version: 3.22
+Version: 3.24
 Summary: A Python feed reader library.
 Author: lemon24
 License: BSD-3-Clause
@@ -39,12 +39,12 @@ Requires-Dist: typing-extensions>=4
 Requires-Dist: feedparser>=6
 Requires-Dist: requests>=2.18
 Requires-Dist: werkzeug>2
-Requires-Dist: iso8601>=1
 Requires-Dist: beautifulsoup4>=4.5
+Requires-Dist: structlog
 Provides-Extra: all
 Requires-Dist: reader[app,cli,unstable-plugins]; extra == "all"
 Provides-Extra: cli
-Requires-Dist: click>=7; extra == "cli"
+Requires-Dist: click!=8.4.0,>=7; extra == "cli"
 Provides-Extra: app
 Requires-Dist: flask>=0.10; extra == "app"
 Requires-Dist: humanize>=4; extra == "app"
@@ -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.24}/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.24}/docs/api.rst

@@ -27,12 +27,17 @@ Data objects
 
 .. autoclass:: Feed
     :members:
+    :inherited-members:
+
+.. autoclass:: Author
+    :members:
 
 .. autoclass:: ExceptionInfo
     :members:
 
 .. autoclass:: Entry
     :members:
+    :inherited-members:
 
 .. autoclass:: Content
     :members:
@@ -42,6 +47,7 @@ Data objects
 
 .. autoclass:: EntrySource
     :members:
+    :inherited-members:
 
 .. autoclass:: EntrySearchResult
     :members:
@@ -67,6 +73,17 @@ Data objects
 .. autoclass:: EntryUpdateStatus
     :members:
 
+.. autoclass:: FeedToImport
+    :members:
+    :undoc-members:
+
+.. autoclass:: FeedImportResult
+    :members:
+
+.. autoclass:: FeedExport
+    :members:
+
+
 
 Exceptions
 ----------
@@ -155,6 +172,9 @@ Exceptions
 .. autoexception:: PluginInitError
     :show-inheritance:
 
+.. autoexception:: FeedImportError
+    :show-inheritance:
+
 
 .. autoexception:: ReaderWarning
     :show-inheritance:
@@ -213,4 +233,13 @@ Constants
 Utilities
 ---------
 
+.. autofunction:: reader.enable_structlog
+
 .. autofunction:: reader.utils.archive_entries
+
+
+
+``reader.opml``
+---------------
+
+.. automodule:: reader.opml

{reader-3.22 → reader-3.24}/docs/app.rst

@@ -62,6 +62,29 @@ 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)
+
+.. _screenshots-help:
+
+.. figure:: screenshots/empty.png
+    :width: 240px
+
+    new user / empty state
+
+.. figure:: screenshots/help.png
+    :width: 240px
+
+    contextual help
 
 
 Serving the web app

{reader-3.22 → reader-3.24}/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
@@ -20,12 +19,14 @@ for name in [
     'werkzeug.exceptions',
     'werkzeug.http',
     'yaml',
+    'structlog',
+    'structlog.contextvars',
+    'structlog.stdlib',
 ]:
     sys.modules[name] = unittest.mock.Mock()
 
 import reader
 
-
 extensions = [
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',

{reader-3.22 → reader-3.24}/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.24}/docs/guide.rst

@@ -374,7 +374,7 @@ As seen in the previous sections,
         updated=datetime.datetime(2020, 2, 28, 9, 34, 2, tzinfo=datetime.timezone.utc),
         title='Hello Internet',
         link='http://www.hellointernet.fm/',
-        author='CGP Grey',
+        authors=(Author(name='CGP Grey'),),
         subtitle='CGP Grey and Brady Haran talk about YouTube, life, work, whatever.',
         version='rss20',
         user_title=None,
@@ -386,9 +386,10 @@ As seen in the previous sections,
 To get all the feeds, use the :meth:`~Reader.get_feeds` method::
 
     >>> for feed in reader.get_feeds():
+    ...     authors = ", ".join(a.name for a in feed.authors if a.name) or 'unknown author'
     ...     print(
     ...         feed.title or feed.url,
-    ...         f"by {feed.author or 'unknown author'},",
+    ...         f"by {authors},",
     ...         f"updated on {feed.updated or 'never'}",
     ...     )
     ...
@@ -705,35 +706,32 @@ you can delete entries using the low-level
 
 
 
-.. _pagination:
+.. _opml:
 
-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.
+OPML import / export
+--------------------
 
-To get the first page, use only ``limit``::
+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::
 
-    >>> 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 +829,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
@@ -972,6 +1002,34 @@ depending on their type attribute or feedparser defaults:
 
 
 
+.. _logging:
+
+Logging
+-------
+
+*reader* uses structured logging internally, through `structlog`_.
+
+By default, output goes to the standard library :mod:`logging` module;
+if you don't care about structlog,
+configure :mod:`logging` as you normally would.
+The *reader* root logger is called ``reader``;
+the names of its children are an implementation detail,
+and may change without any notice.
+
+To enable native structlog logging,
+call :func:`enable_structlog` **before** configuring structlog::
+
+    import reader, structlog
+
+    reader.enable_structlog()
+    structlog.configure(...)
+
+    ... # do stuff with reader
+
+.. _structlog: https://www.structlog.org/
+
+
+
 .. _errors:
 
 Errors and exceptions

{reader-3.22 → reader-3.24}/docs/install.rst

@@ -18,9 +18,9 @@ These packages will be installed automatically when installing *reader*:
   it replaces feedparser's default use of :mod:`urllib`
   to make it easier to write plugins.
 * `werkzeug`_ provides HTTP utilities.
-* `iso8601`_  parses dates in ISO 8601 / RFC 3339; used for JSON Feed parsing.
 * `beautifulsoup4`_ is used to strip HTML tags before adding entries
   to the search index.
+* `structlog`_ is used for structured logging.
 * `typing-extensions`_ is used for :mod:`typing` backports.
 
 *reader* also depends on the :mod:`sqlite3` standard library module
@@ -64,6 +64,7 @@ As of version |version|, *reader* has the following extras:
 .. _requests: https://requests.readthedocs.io/
 .. _werkzeug: https://werkzeug.palletsprojects.com/
 .. _iso8601: http://pyiso8601.readthedocs.org/
+.. _structlog: https://www.structlog.org/
 .. _typing-extensions: https://pypi.org/project/typing-extensions/
 .. _JSON1: https://www.sqlite.org/json1.html
 .. _FTS5: https://www.sqlite.org/fts5.html

{reader-3.22 → reader-3.24}/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.24}/pyproject.toml

@@ -40,10 +40,9 @@ dependencies = [
     "requests>=2.18",
     # for _http_utils
     "werkzeug>2",
-    # for JSON Feed date parsing
-    "iso8601>=1",
     # search
     "beautifulsoup4>=4.5",
+    "structlog",
 ]
 dynamic = ["version"]
 
@@ -60,7 +59,8 @@ Changelog = "https://reader.readthedocs.io/en/latest/changelog.html"
 all = ["reader[cli,app,unstable-plugins]"]
 
 cli = [
-    "click>=7",
+    # != 8.4.0 because of https://github.com/pallets/click/issues/3458
+    "click>=7,!=8.4.0",
 ]
 app = [
     "flask>=0.10",
@@ -190,6 +190,10 @@ module = [
 ]
 ignore_errors = true
 
+[tool.black]
+skip-string-normalization = true
+extend-exclude = "src/reader/_vendor/.*"
+
 [tool.isort]
 profile = "black"
 py_version = 311
@@ -199,4 +203,3 @@ skip_gitignore = true
 filter_files = true
 force_single_line = true
 order_by_type = false
-lines_after_imports = 2

{reader-3.22 → reader-3.24}/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.24}/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.24}/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.24}/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.24}/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.24}/src/reader/__init__.py

@@ -37,7 +37,7 @@ Print the titles of the unread entries::
 
 """
 
-__version__ = '3.22'
+__version__ = '3.24'
 
 # isort: off
 
@@ -64,6 +64,10 @@ from .types import (
     UpdateResult as UpdateResult,
     UpdatedFeed as UpdatedFeed,
     EntryUpdateStatus as EntryUpdateStatus,
+    FeedToImport as FeedToImport,
+    FeedImportResult as FeedImportResult,
+    FeedExport as FeedExport,
+    Author as Author,
 )
 
 from .exceptions import (
@@ -91,17 +95,20 @@ 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,
 # the messages bubble up to the root logger and get printed on stderr.
 # https://docs.python.org/3/howto/logging.html#library-config
+
 import logging  # noqa: E402
+from ._logging import enable_structlog as enable_structlog  # noqa: E402
 
 logging.getLogger('reader').addHandler(logging.NullHandler())

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

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

{reader-3.22 → reader-3.24}/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,38 @@ 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:
+                if not parsed_feeds:
+                    parsed_feeds = None
+                    error = "file contains no feeds"
+        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()
@@ -277,6 +316,11 @@ def entry():
     return render_template('entry.html', entry=entry)
 
 
+@blueprint.route('/help')
+def help():
+    return render_template('help.html')
+
+
 def stream_template(template_name_or_list, **kwargs):
     # Ensure flashed messages get removed from the session,
     # otherwise they keep adding up and never disappear.
@@ -350,6 +394,11 @@ def _find_static(folder, filename):
     return matches[0]
 
 
+@blueprint.app_template_global()
+def is_new_user():
+    return not list(get_reader().get_feeds(limit=1))
+
+
 def create_app(reader_config):
     app = Flask(__name__)
     app.config['SECRET_KEY'] = 'secret'

{reader-3.22 → reader-3.24}/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.24}/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'
 )