reader 3.23__tar.gz → 3.24__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reader
-Version: 3.23
+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"

{reader-3.23 → 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:
@@ -227,6 +233,8 @@ Constants
 Utilities
 ---------
 
+.. autofunction:: reader.enable_structlog
+
 .. autofunction:: reader.utils.archive_entries
 
 

{reader-3.23 → reader-3.24}/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.24}/docs/conf.py

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

{reader-3.23 → 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'}",
     ...     )
     ...
@@ -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.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.23 → 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

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

@@ -37,7 +37,7 @@ Print the titles of the unread entries::
 
 """
 
-__version__ = '3.23'
+__version__ = '3.24'
 
 # 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.24}/src/reader/_app/__init__.py

@@ -290,6 +290,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 +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.
@@ -385,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.23 → reader-3.24}/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.24}/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.24}/src/reader/_app/templates/add_feed.html

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

{reader-3.23 → reader-3.24}/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.24}/src/reader/_app/templates/delete_feed.html

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

{reader-3.23 → reader-3.24}/src/reader/_app/templates/entries.html

@@ -1,3 +1,4 @@
+{% set help_topic = 'entries' if request.args else None %}
 {% extends "layout.html" %}
 
 {% import "macros.html" as macros %}
@@ -142,6 +143,17 @@
           <i class="bi bi-{{ macros.bs_file_icon(enclosure.type) }}"></i>
         </a>
       {%- endfor %}
+      {%- if loop is defined and loop.first %}
+        <a
+          href="{{ url_for('.help', _anchor='entry-flags') }}"
+          target="_blank"
+          title="help: entry flags"
+          class="btn text-secondary"
+          role="button"
+        >
+          <i class="bi bi-question-lg"></i>
+        </a>
+      {%- endif %}
     </div>
 
     {% endblock %}
@@ -150,7 +162,10 @@
 </div>
 
 {% else %}
-  <p>no entries found</p>
+  <p>No entries found.</p>
+  {%- if is_new_user() %}
+    {{ macros.new_user_help_alert() }}
+  {% endif %}
 {% endfor %}
 
 

{reader-3.23 → reader-3.24}/src/reader/_app/templates/entry.html

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

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

@@ -1,3 +1,4 @@
+{% set help_topic = 'feeds' %}
 {% extends "layout.html" %}
 
 {% import "macros.html" as macros %}
@@ -76,7 +77,10 @@
 </div>
 
 {% else %}
-  <p>no entries found</p>
+  <p>No feeds found.</p>
+  {%- if is_new_user() %}
+    {{ macros.new_user_help_alert() }}
+  {%- endif %}
 {% endfor %}
 
 

reader-3.24/src/reader/_app/templates/help.html

@@ -0,0 +1,131 @@
+{% extends "layout.html" %}
+
+{% import "macros.html" as macros %}
+
+
+{% block page_title %}
+  Help - {{ super() }}
+{% endblock %}
+
+
+{% block body %}
+
+<h1>Help</h1>
+
+
+<p>
+  Welcome to <strong>reader</strong>, a feed reader web app!
+
+<p>
+  <strong>reader</strong> allows you to
+  subscribe to web feeds,
+  read articles,
+  and keep track of the ones you've read or liked.
+
+
+<h2 id="feeds">Feeds</h2>
+
+<p>
+  A <a href="https://en.wikipedia.org/wiki/Web_feed">web feed</a>
+  is an internet document used to get updates
+  from websites such as blogs, web comics, or podcasts.
+
+<p>
+  When you subscribe to a feed,
+  <em>reader</em> checks it regularly to get the latest articles
+  (unless the feed is disabled).
+
+
+<h3 id="add-feed">Adding feeds</h3>
+
+<p>
+  To add a feed, paste its link in the
+  <a href="{{ url_for('.add_feed') }}">Add feed</a> page.
+
+<p>
+  You can usually find if a website has a feed
+  by looking in its header or footer for this icon
+  <i class="bi bi-rss" aria-label="RSS logo"></i>,
+  or for links called <em>feed</em>, <em>RSS</em>, or <em>Atom</em>.
+
+
+<h3 id="import-export">Importing / exporting feeds</h3>
+
+<p>
+  You can <a href="{{ url_for('.import_feeds') }}">import feeds</a>
+  from a subscription list exported by another feed reader.
+
+<p>
+  To export your own 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.
+
+
+<h2 id="entries">Entries</h2>
+
+<p>
+  An entry is an item from a feed –
+  an article, a podcast episode, etc.
+
+<p>
+  To read an entry, click its title on the
+  <a href="{{ url_for('.import_feeds') }}">Entries</a> page.
+
+  Some feeds only include summaries, not the full content; click the
+  <i class="bi bi-box-arrow-up-right" aria-label="extenal link"></i> icon
+  to go to the original article.
+
+
+<h3 id="entry-flags">Entry flags</h3>
+
+<p>
+  Each entry has a <em>read</em> and an <em>important</em> flag.
+  Among others, they are used to filter entries
+  on the <a href="{{ url_for('.entries') }}">Entries</a> page.
+
+<p>
+  You can set the flags by using the toggles below the entry title.
+
+<dl>
+
+  <dt>
+    <i class="bi bi-check-lg me-1"></i> mark as read / mark as unread
+  <dd>
+    Mark the entry as read.
+    Hides the entry from the default entries view.
+
+  <dt>
+    <i class="bi bi-star me-1"></i> mark as important / clear important
+  <dd>
+    Mark the entry as important.
+    Important entries are never deleted.
+    <small>
+    (Currently, entries are never deleted,
+    but an upcoming feature will clean up old entries.)
+    </small>
+
+  <dt>
+    <i class="bi bi-x-lg me-1"></i> don't care / clear don't care
+  <dd>
+    Mark the entry as explicitly <em>not</em> important.
+    Hides the entry from the default entries view without marking it as read.
+    <small>
+    (An upcoming feature will allow identifying "noisy" feeds based on this.)
+    </small>
+
+</dl>
+
+
+<h3 id="enclosures">Enclosures</h3>
+
+<p>
+  Some entries have external resources you can download,
+  for example an audio file of a podcast episode.
+
+<p>
+  Click the
+  <i class="bi bi-file-earmark-music" aria-label="download ..."></i> icon
+  to download the first enclosure of an entry, if any.
+
+
+{% endblock %}

{reader-3.23 → reader-3.24}/src/reader/_app/templates/import_feeds.html

@@ -1,3 +1,4 @@
+{% set help_topic = 'import-export' %}
 {% extends "layout.html" %}
 
 {% import "macros.html" as macros %}
@@ -24,15 +25,16 @@
 
 {% if parsed_feeds is none and imported_feeds is none %}
 
-  <p>Upload OPML subscription list:</p>
+  <p>Upload an OPML subscription list:</p>
 
   <div class="mb-3">
 
-  <!-- TODO accept -->
   <input
     class="form-control{% if error %} is-invalid {% endif %}"
     type="file"
     name="file"
+    accept="application/xml, text/xml, text/x-opml, .xml, .opml"
+    required
   >
   {%- if error %}
   <div class="invalid-feedback">
@@ -52,6 +54,10 @@
 
   <p>Select feeds to import:</p>
 
+  <div class="mb-3">
+    {{ macros.select_all_none() }}
+  </div>
+
   {% for feed in parsed_feeds %}
   <div class="form-check mb-3">
     <input
@@ -79,6 +85,10 @@
   </div>
   {% endfor %}
 
+  <div class="mb-3">
+    {{ macros.select_all_none() }}
+  </div>
+
   <input type="submit" class="btn btn-primary" value="import selected">
 
   <a href="javascript:history.back()" class="btn btn-outline-secondary" role="button" >

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

@@ -62,12 +62,22 @@
       <ul class="navbar-nav mb-0">
         {% block right_hidden_navbar %}
 
+        <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"
+          >
+            <i class="bi bi-question-lg"></i>
+            <span class="d-md-none ms-2" id="theme-text">help</span>
+          </a>
+        </li>
+
         <li class="nav-item dropdown">
           <button
             class="btn btn-link nav-link dropdown-toggle d-flex align-items-center"
             type="button" id="theme"
             data-bs-toggle="dropdown" data-bs-display="static"
-            aria-expanded="false"  aria-label="toggle theme (auto)">
+            aria-expanded="false" aria-label="toggle theme (auto)">
             <i class="bi bi-circle-half theme-icon-active"></i>
             <span class="d-md-none ms-2" id="theme-text">toggle theme</span>
           </button>