reader 3.17__tar.gz → 3.19__tar.gz

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

@@ -6,6 +6,47 @@ Changelog
   :no-index:
 
 
+Version 3.19
+------------
+
+Released 2025-10-01
+
+* Support Python 3.14.
+* Remove deprecated empty ``search`` and ``readtime`` extras.
+* Remove undocumented development ``tests``, ``docs``, and ``dev`` extras.
+
+* :mod:`~reader._plugins.enclosure_tags` plugin:
+  strip HTML tags from values used as MP3 tags
+  (for example, ``<b>`` tags used to highlight search result matches).
+
+* Project infrastructure improvements.
+
+  * Clean up :doc:`contributing` documentation and :gh:`run.sh <run.sh>` script.
+  * Use GitHub Actions to publish releases to PyPI.
+  * Split type checking and testing jobs in the ``build`` GHA workflow.
+  * Make tox runs slightly faster.
+  * Use dependency groups instead of extras for development dependencies.
+
+
+Version 3.18
+------------
+
+Released 2025-05-04
+
+* Drop Python 3.10 support. (:issue:`354`)
+
+* Add the ``overwrite`` argument to :meth:`~Reader.add_entry`.
+* Add :class:`FeedSort`, :class:`EntrySort`, and :class:`EntrySearchSort` enums.
+  (:issue:`354`)
+
+* Fix bug causing :meth:`.Reader.update_feeds`
+  to not honor ``updates_enabled=True`` when ``scheduled=True``.
+  (:issue:`365`)
+
+* In the :mod:`~reader._plugins.cli_status` plugin,
+  overwrite the entry so it doesn't appear briefly as unread.
+
+
 Version 3.17
 ------------
 

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

@@ -1,13 +1,13 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: reader
-Version: 3.17
+Version: 3.19
 Summary: A Python feed reader library.
 Author: lemon24
 License: BSD-3-Clause
 Project-URL: Documentation, https://reader.readthedocs.io/
-Project-URL: Changes, https://reader.readthedocs.io/en/latest/changelog.html
-Project-URL: Source Code, https://github.com/lemon24/reader
-Project-URL: Issue tracker, https://github.com/lemon24/reader/issues
+Project-URL: Repository, https://github.com/lemon24/reader
+Project-URL: Issues, https://github.com/lemon24/reader/issues
+Project-URL: Changelog, https://reader.readthedocs.io/en/latest/changelog.html
 Keywords: atom,cdf,feed,rdf,rss,json feed,web feed,podcast,feed reader,feed aggregator
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
@@ -19,10 +19,10 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Internet
@@ -32,7 +32,7 @@ Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: typing-extensions>=4
@@ -41,14 +41,14 @@ Requires-Dist: requests>=2.18
 Requires-Dist: werkzeug>2
 Requires-Dist: iso8601>=1
 Requires-Dist: beautifulsoup4>=4.5
-Provides-Extra: search
-Provides-Extra: readtime
+Provides-Extra: all
+Requires-Dist: reader[app,cli,unstable-plugins]; extra == "all"
 Provides-Extra: cli
 Requires-Dist: click>=7; extra == "cli"
 Requires-Dist: PyYAML; extra == "cli"
 Provides-Extra: app
 Requires-Dist: flask>=0.10; extra == "app"
-Requires-Dist: humanize!=4.7.*,>=4; extra == "app"
+Requires-Dist: humanize>=4; extra == "app"
 Requires-Dist: PyYAML; extra == "app"
 Requires-Dist: WTForms; extra == "app"
 Requires-Dist: jinja2-fragments; extra == "app"
@@ -60,36 +60,7 @@ Requires-Dist: beautifulsoup4; extra == "unstable-plugins"
 Requires-Dist: blinker>=1.4; extra == "unstable-plugins"
 Requires-Dist: beautifulsoup4; extra == "unstable-plugins"
 Requires-Dist: tabulate; extra == "unstable-plugins"
-Provides-Extra: tests
-Requires-Dist: pytest>=4; extra == "tests"
-Requires-Dist: pytest-randomly; extra == "tests"
-Requires-Dist: pytest-subtests; extra == "tests"
-Requires-Dist: pytest-rerunfailures; extra == "tests"
-Requires-Dist: coverage; extra == "tests"
-Requires-Dist: pytest-cov; extra == "tests"
-Requires-Dist: requests-mock; extra == "tests"
-Requires-Dist: mechanicalsoup; (implementation_name != "pypy" and python_version <= "3.12") and extra == "tests"
-Requires-Dist: requests-wsgi-adapter; extra == "tests"
-Requires-Dist: lxml; (implementation_name != "pypy" and python_version <= "3.12") and extra == "tests"
-Requires-Dist: html5lib; extra == "tests"
-Requires-Dist: numpy; (implementation_name != "pypy" and os_name == "posix" and python_version <= "3.12") and extra == "tests"
-Requires-Dist: mypy; implementation_name != "pypy" and extra == "tests"
-Requires-Dist: types-requests; extra == "tests"
-Requires-Dist: types-beautifulsoup4; extra == "tests"
-Provides-Extra: docs
-Requires-Dist: sphinx; extra == "docs"
-Requires-Dist: sphinx-rtd-theme>=1.3.0rc1; extra == "docs"
-Requires-Dist: click>=7; extra == "docs"
-Requires-Dist: sphinx-click; extra == "docs"
-Requires-Dist: sphinx-hoverxref; extra == "docs"
-Requires-Dist: sphinxcontrib-log-cabinet; extra == "docs"
-Requires-Dist: setuptools; extra == "docs"
-Provides-Extra: dev
-Requires-Dist: reader[app,cli,docs,tests,unstable-plugins]; extra == "dev"
-Requires-Dist: tox; extra == "dev"
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
 
 .. begin-intro
 

{reader-3.17 → reader-3.19}/docs/api.rst

@@ -171,6 +171,23 @@ The class hierarchy for :mod:`reader` exceptions is:
 
 
 
+Enumerations
+------------
+
+.. autoclass:: reader.FeedSort(value)
+    :show-inheritance:
+    :members:
+
+.. autoclass:: reader.EntrySort(value)
+    :show-inheritance:
+    :members:
+
+.. autoclass:: reader.EntrySearchSort(value)
+    :show-inheritance:
+    :members:
+
+
+
 .. _type aliases:
 
 Type aliases

{reader-3.17 → reader-3.19}/docs/conf.py

@@ -33,7 +33,6 @@ extensions = [
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
     'sphinx_click.ext',
-    'hoverxref.extension',
     'sphinxcontrib.log_cabinet',
 ]
 
@@ -112,19 +111,6 @@ extlinks = {
 }
 
 
-hoverxref_auto_ref = True
-hoverxref_domains = ["py"]
-hoverxref_role_types = {
-    'ref': 'tooltip',
-    'mod': 'tooltip',
-    'class': 'tooltip',
-    'meth': 'tooltip',
-    'attr': 'tooltip',
-    'exc': 'tooltip',
-    'func': 'tooltip',
-    'data': 'tooltip',
-}
-
 pygments_style = 'friendly'
 
 html_theme = 'sphinx_rtd_theme'

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

@@ -226,25 +226,31 @@ Making a release
 
 .. note::
 
-    :gh:`scripts/release.py <scripts/release.py>` already does most of these.
+    The :gh:`release.py <scripts/release.py>` script together with
+    the :gh:`publish <.github/workflows/publish.yaml>`  GitHub Actions workflow
+    already do most of these.
 
 Making a release (from ``x`` to ``y`` == ``x + 1``):
 
 * (release.py) bump version in ``src/reader/__init__.py`` to ``y``
 * (release.py) update changelog with release version and date
 * (release.py) make sure tests pass / docs build
-* (release.py) clean up dist/: ``rm -rf dist/``
-* (release.py) build tarball and wheel: ``python -m build``
 * (release.py) push to GitHub
-* (release.py prompts) wait for GitHub Actions / Codecov / Read the Docs builds to pass
-* upload to test PyPI and check: ``twine upload --repository-url https://test.pypi.org/legacy/ dist/*``
-* (release.py) upload to PyPI: ``twine upload dist/*``
+* (release.py prompts) wait for GitHub Actions / Read the Docs builds to pass
 * (release.py) tag current commit with `<major>.<minor>` and `<major>.x`
-  (e.g. when releasing `1.20`: `1.20` and `1.x`)
-* (release.py prompts) create release in GitHub
-* build docs from latest and enable ``y`` docs version (should happen automatically after the first time)
+  (e.g. when releasing `1.20`: `1.20` and `1.x`) and push tags to GitHub
+* (release.py prompts) approve publish workflow
+* (publish workflow) build and upload to PyPI
+* alternatively, to make a manual release (should not be needed)
+
+  * clean up dist/: ``rm -rf dist/``
+  * build tarball and wheel: ``python -m build``
+  * upload to test PyPI and check: ``twine upload --repository-url https://test.pypi.org/legacy/ dist/*``
+  * upload to PyPI: ``twine upload dist/*``
+
+* (publish workflow) create draft release in GitHub
+* (release.py prompts) publish release in GitHub
 * (release.py) bump versions from ``y`` to ``(y + 1).dev0``, add ``(y + 1)`` changelog section
-* (release.py prompts) trigger Read the Docs build for `<major>.x` (doesn't happen automatically)
 
 
 

{reader-3.17 → reader-3.19}/docs/install.rst

@@ -109,11 +109,13 @@ Use the following command to update *reader*
     pip install --upgrade reader
 
 
+.. _install-pre-release:
+
 Living on the edge
 ~~~~~~~~~~~~~~~~~~
 
 If you want to use the latest *reader* code before it’s released,
-install or update from the master branch:
+install or update from the ``master`` branch:
 
 .. code-block:: bash
 

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

@@ -1,7 +1,3 @@
-[build-system]
-requires = ["setuptools", "wheel"]
-build-backend = "setuptools.build_meta"
-
 [project]
 name = "reader"
 authors = [{name = "lemon24"}]
@@ -23,10 +19,10 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",
     "Topic :: Internet",
@@ -37,7 +33,7 @@ classifiers = [
     "Topic :: Utilities",
     "Typing :: Typed",
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dependencies = [
     "typing-extensions>=4",
     "feedparser>=6",
@@ -53,19 +49,16 @@ dynamic = ["version"]
 
 [project.urls]
 Documentation = "https://reader.readthedocs.io/"
-Changes = "https://reader.readthedocs.io/en/latest/changelog.html"
-"Source Code" = "https://github.com/lemon24/reader"
-"Issue tracker" = "https://github.com/lemon24/reader/issues"
+Repository = "https://github.com/lemon24/reader"
+Issues = "https://github.com/lemon24/reader/issues"
+Changelog = "https://reader.readthedocs.io/en/latest/changelog.html"
 
 [project.optional-dependencies]
 
-# STABLE
-
-search = []  # empty since 2.4, kept to avoid breaking dependents
-readtime = []  # empty since 3.1, kept to avoid breaking dependents
-
 # UNSTABLE
 
+all = ["reader[cli,app,unstable-plugins]"]
+
 cli = [
     "click>=7",
     # for config
@@ -73,8 +66,7 @@ cli = [
 ]
 app = [
     "flask>=0.10",
-    # https://github.com/python-humanize/humanize/issues/122
-    "humanize>=4,!=4.7.*",
+    "humanize>=4",
     # for config
     "PyYAML",
     # for v2
@@ -82,8 +74,6 @@ app = [
     "jinja2-fragments",
 ]
 
-# UNSTABLE PLUGINS
-
 # mushed together for convenience
 unstable-plugins = [
     # enclosure-tags
@@ -99,16 +89,14 @@ unstable-plugins = [
     "tabulate",
 ]
 
-# DEVELOPMENT
+[dependency-groups]
 
-# run tests under one interpreter
 tests = [
     "pytest>=4",
     "pytest-randomly",
     "pytest-subtests",
     "pytest-rerunfailures",
     "coverage",
-    "pytest-cov",
     "requests-mock",
     # mechanicalsoup hard-depends on lxml (see below)
     'mechanicalsoup; (implementation_name != "pypy" and python_version <= "3.12")',
@@ -120,35 +108,38 @@ tests = [
     "html5lib",
     # for bench.py
     'numpy; (implementation_name != "pypy" and os_name == "posix" and python_version <= "3.12")',
-    # mypy does not work on pypy (yet).
-    'mypy; implementation_name != "pypy"',
+]
+
+typing = [
+    'mypy',
     "types-requests",
     "types-beautifulsoup4",
 ]
 
-# build docs
 docs = [
     "sphinx",
-    # listing 1.3.0rc1 explicitly until 1.3 is released
-    # https://github.com/readthedocs/sphinx_rtd_theme/pull/1464#issuecomment-1664799982
-    "sphinx-rtd-theme>=1.3.0rc1",
+    "sphinx-rtd-theme",
     "click>=7",
     "sphinx-click",
-    "sphinx-hoverxref",
     "sphinxcontrib-log-cabinet",
     # for read_configuration used in conf.py
     "setuptools",
 ]
 
-# things needed to develop / test locally / make releases
 dev = [
-    "reader[cli,app,unstable-plugins,tests,docs]",
+    {include-group = "tests"},
+    {include-group = "typing"},
+    {include-group = "docs"},
     "tox",
     "pre-commit",
     "build",
     "twine",
 ]
 
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
 [tool.setuptools.dynamic]
 version = {attr = "reader.__version__"}
 
@@ -171,9 +162,16 @@ source = ["reader", "tests"]
 omit = [
     "src/reader/_vendor/*",
 ]
+# TODO: remove when https://github.com/nedbat/coveragepy/issues/1987 is solved
+core = "ctrace"
 [tool.coverage.paths]
 source = ["src", "*/site-packages"]
 
+[tool.mypy]
+files = ["src"]
+show_error_codes = true
+pretty = true
+strict = true
 [[tool.mypy.overrides]]
 module = [
     "reader.__main__",
@@ -189,7 +187,7 @@ ignore_errors = true
 
 [tool.isort]
 profile = "black"
-py_version = 310
+py_version = 311
 src_paths = ["src", "tests"]
 extend_skip = ["examples", "src/reader/_vendor"]
 skip_gitignore = true

reader-3.19/run.sh

@@ -0,0 +1,125 @@
+#!/bin/bash
+#
+# usage: ./run.sh command [argument ...]
+#
+# Executable documentation for the development workflow.
+#
+# See https://death.andgravity.com/run-sh for how this works.
+
+
+# preamble
+
+set -o nounset
+set -o pipefail
+set -o errexit
+
+PROJECT_ROOT=${0%/*}
+if [[ $0 != $PROJECT_ROOT && $PROJECT_ROOT != "" ]]; then
+    cd "$PROJECT_ROOT"
+fi
+readonly PROJECT_ROOT=$( pwd )
+readonly SCRIPT="$PROJECT_ROOT/$( basename "$0" )"
+
+
+# main development workflow
+
+function install {
+    pip install -e '.[all]' --group dev --upgrade --upgrade-strategy eager
+    pre-commit install --install-hooks
+}
+
+function test {
+    pytest --runslow "$@"
+}
+
+function test-all {
+    tox run-parallel "$@"
+}
+
+function coverage {
+    unset -f coverage
+    coverage run -m pytest --runslow "$@"
+    coverage html
+    coverage-report
+}
+
+function typing {
+    mypy "$@"
+}
+
+function docs {
+    sphinx-build -E -W docs docs/_build/html "$@"
+}
+
+
+# "watch" versions of the main commands
+
+function test-dev {
+    watch pytest "$@"
+}
+
+function typing-dev {
+    watch typing "$@"
+}
+
+function docs-dev {
+    rm -r docs/_build/html
+    watch sphinx-build -W docs docs/_build/html "$@"
+}
+
+function serve-dev {
+    export READER_DB=db.sqlite
+    flask -A reader._app.wsgi --debug run "$@"
+}
+
+
+# low level commands
+
+function coverage-report {
+    # --fail-under only for the library, not the CLI or the web app
+    unset -f coverage
+    coverage report \
+        --omit "$(
+            echo "
+                */reader/_vendor/*
+                */reader/__main__.py
+                */reader/_cli*
+                */reader/_config*
+                */reader/_app/*
+                */reader/_plugins/*
+                tests/*
+            " | xargs echo | sed 's/ /,/g'
+        )" \
+        --skip-covered \
+        --show-missing \
+        --fail-under $( on-pypy && echo 99 || echo 100 )
+}
+
+
+# utilities
+
+function on-pypy {
+    [[ $( python -c 'import sys; print(sys.implementation.name)' ) == pypy ]]
+}
+
+function watch {
+    entr-project-files -cdr "$SCRIPT" "$@"
+}
+
+function entr-project-files {
+    set +o errexit
+    while true; do
+        ls-project-files | entr "$@"
+        if [[ $? -eq 0 ]]; then
+            break
+        fi
+    done
+}
+
+function ls-project-files {
+    git ls-files "$@"
+    git ls-files --exclude-standard --others "$@"
+}
+
+
+"$@"

{reader-3.17 → reader-3.19}/scripts/release.py

@@ -34,11 +34,6 @@ def run_tox():
     run_no_venv('tox -p all', shell=True)
 
 
-def build():
-    run('rm -rf dist/', shell=True)
-    run('python -m build', shell=True)
-
-
 def path_sub(pattern, repl, path):
     with open(path) as f:
         text = f.read()
@@ -112,10 +107,6 @@ def check_unpushed():
         abort("unpushed changes\n\n{}\n", p.stdout.strip('\n'))
 
 
-def upload_to_pypi():
-    run('twine upload dist/*', shell=True)
-
-
 def add_and_push_tags(tags):
     for tag in tags:
         run(['git', 'tag', '--force', tag])
@@ -150,10 +141,6 @@ def main(version, new_version, date, tox, changelog):
 
     confirm("Wait for GitHub Actions / Read the Docs builds to pass.")
 
-    confirm("Upload to PyPI?")
-    build()
-    upload_to_pypi()
-
     tags = [version]
     version_x = version.partition('.')[0] + '.x'
     if new_version_is_final:
@@ -162,7 +149,15 @@ def main(version, new_version, date, tox, changelog):
     confirm(f"Add and push tags ({', '.join(tags)})?")
     add_and_push_tags(tags)
 
-    confirm("Create release {} in GitHub (doesn't happen automatically).", version)
+    confirm(
+        "Approve publish workflow to upload to PyPI.\n  {}\nDone?",
+        "https://github.com/lemon24/reader/actions/workflows/publish.yaml",
+    )
+    confirm(
+        "Publish draft release {} in GitHub.\n  {}\nDone?",
+        version,
+        "https://github.com/lemon24/reader/releases",
+    )
 
     new_version_full = f"{new_version}.dev0"
     update_init_version(new_version_full)
@@ -173,11 +168,6 @@ def main(version, new_version, date, tox, changelog):
     confirm("Push version {}?", new_version_full)
     push()
 
-    # TODO: I just enabled branch or tag creation/deletion for the RtD webhook in GitHub, this might not be needed next time.
-    confirm(
-        f"Trigger Read the Docs build for {version_x} (doesn't happen automatically)."
-    )
-
 
 if __name__ == '__main__':
     main()

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

@@ -37,7 +37,7 @@ Print the titles of the unread entries::
 
 """
 
-__version__ = '3.17'
+__version__ = '3.19'
 
 # isort: off
 
@@ -58,6 +58,9 @@ from .types import (
     FeedCounts as FeedCounts,
     EntryCounts as EntryCounts,
     EntrySearchCounts as EntrySearchCounts,
+    FeedSort as FeedSort,
+    EntrySort as EntrySort,
+    EntrySearchSort as EntrySearchSort,
     UpdateResult as UpdateResult,
     UpdatedFeed as UpdatedFeed,
     EntryUpdateStatus as EntryUpdateStatus,

{reader-3.17 → reader-3.19}/src/reader/_parser/__init__.py

@@ -239,13 +239,9 @@ class NotModified(RetrieveError):
     _default_message = "not modified"
 
 
-@dataclass(frozen=True)
-class RetrieveResult(_namedtuple_compat, Generic[F, T, E]):
+class RetrieveResult(NamedTuple, Generic[F, T, E]):
     """The result of retrieving a feed, regardless of the outcome."""
 
-    # should be a NamedTuple, but the typing one became generic only in 3.11,
-    # and we don't want to depend on typing_extensions at runtime
-
     #: The feed (a :class:`FeedArgument`, usually a :class:`FeedForUpdate`).
     feed: F
 
@@ -339,8 +335,7 @@ class FeedForUpdateRetrieverType(RetrieverType[T_co], Protocol):  # pragma: no c
         """
 
 
-@dataclass(frozen=True)
-class ParseResult(_namedtuple_compat, Generic[F, E]):
+class ParseResult(NamedTuple, Generic[F, E]):
     """The result of retrieving and parsing a feed, regardless of the outcome."""
 
     #: The feed (a :class:`FeedArgument`, usually a :class:`.FeedForUpdate`).

{reader-3.17 → reader-3.19}/src/reader/_parser/_lazy.py

@@ -259,8 +259,7 @@ class Parser:
         Takes one argument and does not raise exceptions.
 
         """
-        feed = result.feed
-        context = result.value
+        feed, context = result
 
         http_info = None
         value: ParsedFeed | None | Exception

{reader-3.17 → reader-3.19}/src/reader/_parser/requests/_lazy.py

@@ -4,6 +4,7 @@ from collections.abc import Sequence
 from dataclasses import dataclass
 from dataclasses import field
 from typing import Any
+from typing import Self
 from typing import TYPE_CHECKING
 from typing import TypeVar
 
@@ -14,8 +15,6 @@ from . import TimeoutType
 
 
 if TYPE_CHECKING:  # pragma: no cover
-    from typing_extensions import Self
-
     from . import Headers
     from . import RequestHook
     from . import ResponseHook