reader 3.16__tar.gz → 3.17__tar.gz

{reader-3.16 → reader-3.17}/CHANGES.rst

@@ -6,6 +6,36 @@ Changelog
   :no-index:
 
 
+Version 3.17
+------------
+
+Released 2025-03-08
+
+.. attention::
+
+    This is the last release to support Python 3.10;
+    see :issue:`354` for details.
+
+* Support PyPy 3.11. (:issue:`354`)
+
+* Start working on a web app :ref:`re-design <app roadmap>`
+  based on `htmx`_ and `Bootstrap`_,
+  beginning with a new version of the main entries page,
+  and dark mode support;
+  some :ref:`screenshots <app screenshots>`.
+  (:issue:`318`)
+
+* :attr:`Entry.feed_resolved_title`:
+  return both the source and feed titles only if they are different.
+
+* The :mod:`~reader._plugins.cli_status` plugin
+  now creates only one entry per command,
+  with the newest run first.
+
+.. _htmx: https://htmx.org/
+.. _Bootstrap: https://getbootstrap.com/
+
+
 Version 3.16
 ------------
 

{reader-3.16 → reader-3.17}/MANIFEST.in

@@ -1,5 +1,6 @@
 recursive-include src/reader/_app/templates *
 recursive-include src/reader/_app/static *
+recursive-include src/reader/_app/v2 *
 recursive-include src/reader/_plugins/templates *
 recursive-include src/reader *.pyi
 recursive-include src/reader py.typed

{reader-3.16/src/reader.egg-info → reader-3.17}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: reader
-Version: 3.16
+Version: 3.17
 Summary: A Python feed reader library.
 Author: lemon24
 License: BSD-3-Clause
@@ -50,6 +50,8 @@ Provides-Extra: app
 Requires-Dist: flask>=0.10; extra == "app"
 Requires-Dist: humanize!=4.7.*,>=4; extra == "app"
 Requires-Dist: PyYAML; extra == "app"
+Requires-Dist: WTForms; extra == "app"
+Requires-Dist: jinja2-fragments; extra == "app"
 Provides-Extra: unstable-plugins
 Requires-Dist: requests; extra == "unstable-plugins"
 Requires-Dist: mutagen; extra == "unstable-plugins"

{reader-3.16 → reader-3.17}/docs/app.rst

@@ -67,9 +67,34 @@ If running on a personal computer, you can use cron to run ``serve`` at boot::
 .. _Werkzeug's development server: http://werkzeug.pocoo.org/docs/0.14/serving/#werkzeug.serving.run_simple
 
 
+.. _app screenshots:
+
 Screenshots
 -----------
 
+Following are screenshots of the web app re-design
+mentioned in the :ref:`roadmap <app roadmap>`.
+For the legacy web app, see `Screenshots (legacy)`_.
+
+Main page
+~~~~~~~~~
+
+.. figure:: screenshots/entries-v2-dark.png
+    :width: 240px
+
+    main page (dark mode)
+
+.. figure:: screenshots/entries-v2-filters-light.png
+    :width: 240px
+
+    main page – more filters (light mode)
+
+
+Screenshots (legacy)
+--------------------
+
+Following are screenshots of the original (legacy) web app.
+
 Main page
 ~~~~~~~~~
 

{reader-3.16 → reader-3.17}/docs/dev.rst

@@ -122,8 +122,14 @@ Long term, I'd like to:
 * switch to `htmx`_ instead of using a home-grown solution
 * spin it off into a separate package/project
 
-.. _htmx: https://htmx.org/
+**2025 update**:
+I've started working on a re-design based on `htmx`_ and `Bootstrap`_;
+some :ref:`screenshots <app screenshots>`.
+The new app will be available in parallel with the old one
+until it reaches feature parity.
 
+.. _htmx: https://htmx.org/
+.. _Bootstrap: https://getbootstrap.com/
 
 
 .. _compat:
@@ -362,6 +368,8 @@ Speeding up ``get_entry_counts(feed=...)``:
 * having an index on entries(feed) yielded a 4x improvement: :issue:`251`
 * even better, we should cache commonly-used counts: :issue:`306#issuecomment-1694655504`
 
+Official guidance: https://www.sqlite.org/queryplanner-ng.html#howtofix
+
 
 Parser
 ~~~~~~
@@ -663,6 +671,8 @@ Why I want to postpone batch update/set methods:
 tl:dr: Performance is likely a non-issue with SQLite,
 convenience can be added on top as a plugin.
 
+(2025) Why it may be worth adding batch interfaces anyway (even if underneath the storage implementation doesn't actually batch) – it allows for future optimization: https://blog.glyph.im/2022/12/potato-programming.html
+
 See the 2.12 reader._app.ResourceTags class for an idea of how to
 represent a bunch of tags in a reserved-name-scheme-agnostic way
 (useful e.g. for when get_entries() should return tags x, y, z of each entry).

{reader-3.16 → reader-3.17}/pyproject.toml

@@ -77,6 +77,9 @@ app = [
     "humanize>=4,!=4.7.*",
     # for config
     "PyYAML",
+    # for v2
+    "WTForms",
+    "jinja2-fragments",
 ]
 
 # UNSTABLE PLUGINS

{reader-3.16 → reader-3.17}/src/reader/__init__.py

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

{reader-3.16 → reader-3.17}/src/reader/_app/__init__.py

@@ -105,6 +105,7 @@ def get_reader():
 def stream_template(template_name_or_list, **kwargs):
     template = current_app.jinja_env.get_template(template_name_or_list)
     stream = template.stream(**kwargs)
+    # TODO: increase to at least 1-2k, like this we have 50% overhead
     stream.enable_buffering(50)
     return Response(stream_with_context(stream))
 
@@ -836,6 +837,10 @@ def create_app(config):
 
     app.register_blueprint(blueprint)
 
+    from . import v2
+
+    app.register_blueprint(v2.blueprint, url_prefix='/v2')
+
     # NOTE: this is part of the app extension API
     app.reader_additional_enclosure_links = []
     app.reader_additional_links = []

{reader-3.16 → reader-3.17}/src/reader/_app/templates/layout.html

@@ -21,6 +21,7 @@ window.onload = function () {
 <a href="{{ url_for('reader.feeds') }}">feeds</a>
 <a href="{{ url_for('reader.tags') }}">tags</a>
 <a href="{{ url_for('reader.metadata') }}">metadata</a>
+<a href="{{ url_for('v2.entries') }}">v2</a>
 
 {{ macros.text_input_button_get(
     'reader.preview', 'add feed', 'url', 'url',

reader-3.17/src/reader/_app/v2/__init__.py

@@ -0,0 +1,123 @@
+import itertools
+from functools import partial
+
+from flask import abort
+from flask import Blueprint
+from flask import current_app
+from flask import redirect
+from flask import request
+from flask import url_for
+from jinja2_fragments.flask import render_block
+
+from reader import InvalidSearchQueryError
+
+from .. import EntryProxy
+from .. import get_reader
+from .. import stream_template
+from .forms import EntryFilter
+from .forms import SearchEntryFilter
+
+
+blueprint = Blueprint(
+    'v2', __name__, template_folder='templates', static_folder='static'
+)
+
+
+@blueprint.route('/')
+def entries():
+    reader = get_reader()
+
+    # TODO: search improvements
+    # TODO: paqgination
+    # TODO: read time
+
+    if request.args.get('q', '').strip():
+        form = SearchEntryFilter(request.args)
+    else:
+        form = EntryFilter(request.args)
+
+    form_args = form.args
+    if q := form_args.pop('Q', ''):
+        form_args['q'] = q
+        return redirect(url_for('.entries', **form_args))
+    if form_args != request.args.to_dict():
+        return redirect(url_for('.entries', **form_args))
+
+    feed = None
+    if form.feed.data:
+        feed = reader.get_feed(form.feed.data, None)
+        if not feed:
+            abort(404)
+
+    kwargs = dict(form.data)
+    if query := kwargs.pop('search', None):
+
+        def get_entries(**kwargs):
+            for sr in reader.search_entries(query, **kwargs):
+                yield EntryProxy(sr, reader.get_entry(sr))
+
+    else:
+        get_entries = reader.get_entries
+
+    entries = []
+    if form.validate():
+        try:
+            entries = eager_iterator(get_entries(**kwargs, limit=64))
+        except StopIteration:
+            pass
+        except InvalidSearchQueryError as e:
+            form.search.errors.append(f"invalid query: {e}")
+
+    return stream_template(
+        'v2/entries.html',
+        form=form,
+        entries=entries,
+        feed=feed,
+    )
+
+
+def eager_iterator(it):
+    it = iter(it)
+    try:
+        return itertools.chain([next(it)], it)
+    except StopIteration:
+        return it
+
+
+@blueprint.route('/mark-as', methods=['POST'])
+def mark_as():
+    reader = get_reader()
+
+    entry = request.form['feed-url'], request.form['entry-id']
+
+    if 'read' in request.form:
+        match request.form['read']:
+            case 'true':
+                reader.set_entry_read(entry, True)
+            case 'false':
+                reader.set_entry_read(entry, False)
+            case _:
+                abort(422)
+
+    if 'important' in request.form:
+        match request.form['important']:
+            case 'true':
+                reader.set_entry_important(entry, True)
+            case 'false':
+                reader.set_entry_important(entry, False)
+            case 'none':
+                reader.set_entry_important(entry, None)
+            case _:
+                abort(422)
+
+    if request.headers.get('hx-request') == 'true':
+        return render_block(
+            'v2/entries.html',
+            'entry_form',
+            entry=reader.get_entry(entry),
+            next=request.form['next'],
+            # equivalent to {% import "v2/macros.html" as macros %}
+            macros=current_app.jinja_env.get_template('v2/macros.html').module,
+        )
+
+    return redirect(request.form['next'], code=303)

reader-3.17/src/reader/_app/v2/forms.py

@@ -0,0 +1,159 @@
+from dataclasses import dataclass
+
+import yaml
+from wtforms import Form
+from wtforms import HiddenField
+from wtforms import RadioField
+from wtforms import SearchField
+from wtforms import StringField
+
+from reader._types import tag_filter_argument
+
+
+class TagFilterField(StringField):
+
+    def process_formdata(self, valuelist):
+        if not valuelist:
+            return
+        value = valuelist[0]
+        if '[' not in value:
+            value = f'[{value}]'
+        try:
+            data = yaml.safe_load(value)
+        except yaml.error.MarkedYAMLError as e:
+            raise ValueError(f"invalid YAML: {e.problem or e.context}") from e
+        tag_filter_argument(data)
+        self.data = data
+
+    def _value(self):
+        if self.raw_data:
+            return self.raw_data[0]
+        if not self.data:
+            return ''
+        return yaml.safe_dump(self.data, default_flow_style=True).rstrip()
+
+
+class PresetsMixin:
+
+    @property
+    def presets(self):
+        form_args = {}
+        form_preset_args = {}
+        for field in self:
+            value = get_formdata(field)
+            form_args[field.name] = value
+            if field.name in self.PRESET_FIELDS:
+                form_preset_args[field.name] = value
+
+        for name, args_raw in self.PRESETS.items():
+            args = {}
+            preset_args = {}
+            for field in self:
+
+                if field.name in self.PRESET_FIELDS:
+                    value = args_raw.get(field.name, field.default)
+                    preset_args[field.name] = value
+                else:
+                    value = form_args[field.name]
+
+                if value and (not field.default or value != field.default):
+                    args[field.name] = value
+
+            yield Preset(name, args, preset_args == form_preset_args)
+
+    @property
+    def active_presets(self):
+        return [p for p in self.presets if p.active]
+
+    @property
+    def args(self):
+        rv = {}
+        for field in self:
+            value = get_formdata(field)
+            if value and (not field.default or value != field.default):
+                rv[field.name] = value
+        return rv
+
+
+@dataclass
+class Preset:
+    name: str
+    args: dict[str, str]
+    active: bool = False
+
+
+def get_formdata(field):
+    try:
+        return field._value()
+    except AttributeError:
+        values = [option._value() for option in field if option.checked]
+        if values:
+            value, *rest = values
+            if rest:
+                raise NotImplementedError("multiple choices not supported") from None
+            return value
+        return field.default
+
+
+def radio_field(*args, choices, **kwargs):
+    """Like RadioField, but choices is a list of (value, value_str),
+    (value, value_str, label), or (value, value_str, label, render_kw) tuples.
+
+    """
+    return RadioField(
+        *args,
+        choices=[c[1] if len(c) == 2 else c[1:] for c in choices],
+        coerce={c[1]: c[0] for c in choices}.get,
+        **kwargs,
+    )
+
+
+BOOL_CHOICES = [(True, 'yes'), (False, 'no'), (None, 'all')]
+TRISTATE_CHOICES = [('notfalse', 'maybe')] + BOOL_CHOICES
+ENTRY_SORT_CHOICES = ['recent', 'random']
+
+
+class EntryFilter(PresetsMixin, Form):
+    feed = HiddenField("feed")
+    search = SearchField("search", name='Q')
+    feed_tags = TagFilterField("tags", name='tags')
+    read = radio_field("read", choices=BOOL_CHOICES, default='no')
+    important = radio_field("important", choices=TRISTATE_CHOICES, default='maybe')
+    has_enclosures = radio_field(
+        "enclosures", name='enclosures', choices=BOOL_CHOICES, default='all'
+    )
+    sort = RadioField("sort", choices=ENTRY_SORT_CHOICES, default='recent')
+
+    PRESET_FIELDS = {'read', 'important', 'enclosures', 'sort'}
+    PRESETS = {
+        'unread': {},
+        'important': {'read': 'all', 'important': 'yes'},
+        'podcast': {'enclosures': 'yes'},
+        'random': {'sort': 'random'},
+    }
+
+
+class SearchEntryFilter(EntryFilter):
+    search = SearchField("search", name='q')
+    sort = RadioField(
+        "sort", choices=['relevant'] + ENTRY_SORT_CHOICES, default='relevant'
+    )
+
+
+if __name__ == '__main__':
+    from werkzeug.datastructures import MultiDict
+
+    args = MultiDict(dict(tags='1'))
+    for FormCls in EntryFilter, SearchEntryFilter:
+        form = FormCls(args)
+        for field in form:
+            print(field())
+            print()
+        print(form.data)
+        print(form.to_formdata())
+        print()
+
+    print(form.feed_tags.__dict__)
+    import IPython
+
+    IPython.embed()

reader-3.17/src/reader/_app/v2/static/style.css

@@ -0,0 +1,27 @@
+
+.navbar {
+  --bs-navbar-padding-y: 0.25rem;
+  --bs-navbar-toggler-padding-y: 0.25rem;
+  --bs-navbar-toggler-padding-x: 0.25rem;
+  --bs-navbar-toggler-font-size: 1rem;
+  --bs-navbar-toggler-border-color: rgba(0, 0, 0, 0);
+}
+
+.nav.controls {
+  --bs-nav-link-padding-x: 0;
+  --bs-nav-link-padding-y: 0;
+  gap: 1rem;
+}
+.nav.controls .nav-link.active {
+  color: var(--bs-navbar-active-color);
+}
+
+.htmx-indicator {
+  display: none;
+}
+.htmx-request .htmx-indicator, .htmx-request.htmx-indicator {
+  display: inline-block;
+}
+.htmx-request .label, .htmx-request.label {
+  display: none;
+}

reader-3.17/src/reader/_app/v2/static/theme.js

@@ -0,0 +1,91 @@
+/*!
+ * Color mode toggler for Bootstrap's docs (https://getbootstrap.com/)
+ * Copyright 2011-2024 The Bootstrap Authors
+ * Licensed under the Creative Commons Attribution 3.0 Unported License.
+ */
+
+/*
+ * Modified to use the Bootstrap Icons font, instead of SVG sprites.
+ */
+
+(() => {
+  'use strict'
+
+  const getStoredTheme = () => localStorage.getItem('theme')
+  const setStoredTheme = theme => localStorage.setItem('theme', theme)
+
+  const getPreferredTheme = () => {
+    const storedTheme = getStoredTheme()
+    if (storedTheme) {
+      return storedTheme
+    }
+
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+  }
+
+  const setTheme = theme => {
+    if (theme === 'auto') {
+      document.documentElement.setAttribute('data-bs-theme', (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'))
+    } else {
+      document.documentElement.setAttribute('data-bs-theme', theme)
+    }
+  }
+
+  const getIconCls = btn => {
+    return btn.querySelector('.bi').classList.values().find(x => x.startsWith('bi-'))
+  }
+
+  setTheme(getPreferredTheme())
+
+  const showActiveTheme = (theme, focus = false) => {
+    const themeSwitcher = document.querySelector('#theme')
+
+    if (!themeSwitcher) {
+      return
+    }
+
+    const themeSwitcherText = document.querySelector('#theme-text')
+    const activeThemeIcon = document.querySelector('.theme-icon-active')
+    const btnToActive = document.querySelector(`[data-bs-theme-value="${theme}"]`)
+    const clsOfActiveBtn = btnToActive.querySelector('.bi').classList.values().find(x => x.startsWith('bi-'))
+
+    document.querySelectorAll('[data-bs-theme-value]').forEach(element => {
+      element.classList.remove('active')
+      element.setAttribute('aria-pressed', 'false')
+    })
+
+    btnToActive.classList.add('active')
+    btnToActive.setAttribute('aria-pressed', 'true')
+    activeThemeIcon.classList.remove(
+      activeThemeIcon.classList.values().find(x => x.startsWith('bi-'))
+    )
+    activeThemeIcon.classList.add(clsOfActiveBtn)
+    const themeSwitcherLabel = `${themeSwitcherText.textContent} (${btnToActive.dataset.bsThemeValue})`
+    themeSwitcher.setAttribute('aria-label', themeSwitcherLabel)
+
+    if (focus) {
+      themeSwitcher.focus()
+    }
+  }
+
+  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
+    const storedTheme = getStoredTheme()
+    if (storedTheme !== 'light' && storedTheme !== 'dark') {
+      setTheme(getPreferredTheme())
+    }
+  })
+
+  window.addEventListener('DOMContentLoaded', () => {
+    showActiveTheme(getPreferredTheme())
+
+    document.querySelectorAll('[data-bs-theme-value]')
+    .forEach(toggle => {
+      toggle.addEventListener('click', () => {
+        const theme = toggle.getAttribute('data-bs-theme-value')
+        setStoredTheme(theme)
+        setTheme(theme)
+        showActiveTheme(theme, true)
+      })
+    })
+  })
+})()