reader 3.23__tar.gz → 3.25__tar.gz

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

@@ -6,6 +6,75 @@ Changelog
   :no-index:
 
 
+Version 3.25
+------------
+
+Released 2026-05-25
+
+* Stable feed autodiscovery support. (:issue:`404`)
+
+  * 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.
+
+* Fix bugs that may cause the 3.24 database migration to fail. (:issue:`405`)
+
+  * Don't fail for ``John Doe (...) (email)`` RSS authors.
+  * Support missing :attr:`EntrySource` ``author`` field during migration.
+
+  Note there should be no integrity issues,
+  as migrations happen inside a transaction.
+
+* Simplify parser lazy initialization (make it explicit and opt-in by plugins).
+* Allow before/after update hook functions to take *fewer* arguments than documented.
+
+
+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
 ------------
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reader
-Version: 3.23
+Version: 3.25
 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"
@@ -114,6 +114,7 @@ you'd probably call it a fat model.
 * full-text search articles
 * get statistics on feed and user activity
 * import / export feeds as OPML
+* automatically discover feeds in web pages
 * write plugins to extend its functionality
 * skip all the low level stuff and focus on what makes your feed reader different
 

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

@@ -50,6 +50,7 @@ you'd probably call it a fat model.
 * full-text search articles
 * get statistics on feed and user activity
 * import / export feeds as OPML
+* automatically discover feeds in web pages
 * write plugins to extend its functionality
 * skip all the low level stuff and focus on what makes your feed reader different
 

{reader-3.23 → reader-3.25}/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:
@@ -227,6 +233,8 @@ Constants
 Utilities
 ---------
 
+.. autofunction:: reader.enable_structlog
+
 .. autofunction:: reader.utils.archive_entries
 
 
@@ -235,3 +243,9 @@ Utilities
 ---------------
 
 .. automodule:: reader.opml
+
+
+``reader.discover``
+-------------------
+
+.. automodule:: reader.discover

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

@@ -74,6 +74,17 @@ Screenshots
 
     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.23 → reader-3.25}/docs/conf.py

@@ -19,8 +19,11 @@ for name in [
     'werkzeug.exceptions',
     'werkzeug.http',
     'yaml',
+    'structlog',
+    'structlog.contextvars',
+    'structlog.stdlib',
 ]:
-    sys.modules[name] = unittest.mock.Mock()
+    sys.modules[name] = unittest.mock.MagicMock()
 
 import reader
 

{reader-3.23 → reader-3.25}/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'}",
     ...     )
     ...
@@ -1001,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.23 → reader-3.25}/docs/install.rst

@@ -13,14 +13,11 @@ Dependencies
 
 These packages will be installed automatically when installing *reader*:
 
-* `feedparser`_ parses feeds; *reader* is essentially feedparser + state.
-* `requests`_ retrieves feeds from the internet;
-  it replaces feedparser's default use of :mod:`urllib`
-  to make it easier to write plugins.
+* `feedparser`_ parses Atom and RSSfeeds.
+* `requests`_ retrieves feeds from the internet.
 * `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.
+* `beautifulsoup4`_ is used to strip HTML tags and by various plugins.
+* `structlog`_ is used for structured logging.
 * `typing-extensions`_ is used for :mod:`typing` backports.
 
 *reader* also depends on the :mod:`sqlite3` standard library module
@@ -58,12 +55,18 @@ As of version |version|, *reader* has the following extras:
 * Specific plugins may require additional dependencies;
   refer to their documentation for details.
 
+Beautiful Soup supports `multiple parsers`_,
+and will use the best available one;
+for speed, install `lxml`_.
 
 .. _beautifulsoup4: https://www.crummy.com/software/BeautifulSoup/
+.. _multiple parsers: https://www.crummy.com/software/BeautifulSoup/bs4/doc/#installing-a-parser
+.. _lxml: https://lxml.de/
 .. _feedparser: https://feedparser.readthedocs.io/en/latest/
 .. _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.23 → reader-3.25}/docs/internal.rst

@@ -31,16 +31,6 @@ Parser
     :special-members: __call__
 
 
-.. module:: reader._parser.requests
-
-.. autoclass:: SessionFactory(...)
-    :members:
-    :special-members: __call__
-
-.. autoclass:: SessionWrapper(...)
-    :members:
-
-
 Protocols
 ~~~~~~~~~
 
@@ -79,18 +69,6 @@ Protocols
     :show-inheritance:
 
 
-.. module:: reader._parser.requests
-    :no-index:
-
-.. autoclass:: RequestHook
-    :members:
-    :special-members: __call__
-
-.. autoclass:: ResponseHook
-    :members:
-    :special-members: __call__
-
-
 Data objects
 ~~~~~~~~~~~~
 
@@ -113,6 +91,35 @@ Data objects
     :members:
 
 
+Built-in retrievers and parsers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. module:: reader._parser.http
+
+.. autoclass:: HTTPRetriever
+    :members: request_hooks, response_hooks
+
+.. autoclass:: RequestHook
+    :members:
+    :special-members: __call__
+
+.. autoclass:: ResponseHook
+    :members:
+    :special-members: __call__
+
+.. module:: reader._parser.file
+
+.. autoclass:: FileRetriever
+
+.. module:: reader._parser.feedparser
+
+.. autoclass:: FeedparserParser
+
+.. module:: reader._parser.jsonfeed
+
+.. autoclass:: JSONFeedParser
+
+
 .. _storage:
 
 Storage

{reader-3.23 → reader-3.25}/docs/plugins.rst

@@ -16,6 +16,7 @@ This is a list of built-in plugins that are considered stable.
 See the :ref:`Plugins <plugins>` section of the user guide
 for details on how built-in plugins are loaded.
 
+.. automodule:: reader.plugins.autodiscover
 .. automodule:: reader.plugins.enclosure_dedupe
 .. automodule:: reader.plugins.entry_dedupe
 .. automodule:: reader.plugins.mark_as_read

{reader-3.23 → reader-3.25}/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",
@@ -186,10 +186,15 @@ module = [
     "reader.plugins.ua_fallback",
     "reader.plugins.readtime",
     "reader.plugins.mark_as_read",
+    "reader.plugins.autodiscover",
     "reader._vendor.feedparser.*",
 ]
 ignore_errors = true
 
+[tool.black]
+skip-string-normalization = true
+extend-exclude = "src/reader/_vendor/.*"
+
 [tool.isort]
 profile = "black"
 py_version = 311

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

@@ -37,7 +37,7 @@ Print the titles of the unread entries::
 
 """
 
-__version__ = '3.23'
+__version__ = '3.25'
 
 # isort: off
 
@@ -67,6 +67,7 @@ from .types import (
     FeedToImport as FeedToImport,
     FeedImportResult as FeedImportResult,
     FeedExport as FeedExport,
+    Author as Author,
 )
 
 from .exceptions import (
@@ -106,6 +107,8 @@ 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.23 → reader-3.25}/src/reader/_app/__init__.py

@@ -88,6 +88,15 @@ def entries():
     if feed_url := form.feed.data:
         feed = reader.get_feed(feed_url)
 
+    autodiscover = None
+    if feed and feed.last_exception and not feed.last_updated:
+        autodiscover_tag = reader.make_reader_reserved_name('autodiscover')
+        hostname = urlparse(feed.url).hostname
+        autodiscover = [
+            (link, hostname and urlparse(link['href']).hostname == hostname)
+            for link in reader.get_tag(feed, autodiscover_tag, None)
+        ]
+
     kwargs = dict(form.data)
 
     if not (feed or kwargs.get('starting_after')):
@@ -106,6 +115,7 @@ def entries():
         form=form,
         entries=entries,
         feed=feed,
+        autodiscover=autodiscover,
         limit=limit,
     )
 
@@ -277,6 +287,31 @@ def add_feed():
     return render_template('add_feed.html', form=form)
 
 
+@blueprint.route('/feeds/change', methods=['POST'])
+def change_feed_url():
+    # NOTE: currently only for post-add autodiscover change,
+    # actual "change feed URL" UX needs design (e.g. needs preview)
+
+    reader = get_reader()
+    old = request.form['old']
+    new = request.form['new']
+
+    try:
+        reader.change_feed_url(old, new)
+    except FeedExistsError:
+        flash(f"Feed {new} already exists.", 'secondary')
+        return redirect(url_for('.entries', feed=old), code=303)
+    else:
+        # TODO: updating should be out of band
+        try:
+            reader.update_feed(new)
+        except UpdateError:
+            pass
+        else:
+            flash("Changed and updated feed.", 'success')
+        return redirect(url_for('.entries', feed=new), code=303)
+
+
 @blueprint.route('/feeds/import', methods=['GET', 'POST'])
 def import_feeds():
     reader = get_reader()
@@ -290,6 +325,10 @@ def import_feeds():
                 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')
@@ -312,6 +351,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.
@@ -385,6 +429,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.23 → reader-3.25}/src/reader/_app/legacy/templates/entry.html

@@ -18,7 +18,15 @@
 <ul class="controls">
 
 <li>
-    {% if entry.author %} by {{ entry.author }}{% endif %}
+    {% if entry.authors %}
+        by
+        {% for author in entry.authors -%}
+            {% if author.href %}<a href="{{ author.href }}" title="{{ author.email or '' }}">{% endif %}
+            {{- author.name or author.email or 'unknown' -}}
+            {% if author.href %}</a>{% endif %}
+            {%- if not loop.last %}, {% endif %}
+        {%- endfor %}
+    {% endif %}
     in <a href="{{ url_for('.entries', feed=entry.feed.url) }}">{{ entry.feed_resolved_title or feed.url }}</a>
 <li>
     {%- set published = entry.published or entry.updated_not_none -%}

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

@@ -68,3 +68,9 @@
   max-width: 100%;
   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);
+}

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

@@ -1,3 +1,4 @@
+{% set help_topic = 'add-feed' %}
 {% extends "layout.html" %}
 
 {% import "macros.html" as macros %}
@@ -12,7 +13,15 @@
 
 <h1>Add feed</h1>
 
-<p>Add a single feed:</p>
+<p>
+  Paste a feed or website URL:
+  <a
+    href="{{ url_for('.help', _anchor=help_topic) }}"
+    class="link-secondary d-inline-block px-2"
+  >
+    <i class="bi bi-question-lg" aria-label="help: adding feeds"></i>
+  </a>
+</p>
 
 <form action="{{ url_for(request.endpoint) }}" method="post" class="my-2 mb-4">
 {#- TODO: aria stuff #}

{reader-3.23 → reader-3.25}/src/reader/_app/templates/change_feed_title.html

@@ -1,3 +1,4 @@
+{% set help_topic = 'feeds' %}
 {% extends "layout.html" %}
 
 {% import "macros.html" as macros %}

{reader-3.23 → reader-3.25}/src/reader/_app/templates/delete_feed.html

@@ -1,3 +1,4 @@
+{% set help_topic = 'feeds' %}
 {% extends "layout.html" %}
 
 {% import "macros.html" as macros %}