API reference

This part of the documentation covers all the public interfaces of reader.

Reader object

Most of reader’s functionality can be accessed through a Reader instance.

reader.make_reader(url, *, feed_root=None, read_only=False, plugins=['reader.ua_fallback'], session_timeout=(3.05, 60), reserved_name_scheme={'plugin_prefix': '.plugin.', 'reader_prefix': '.reader.', 'separator': '.'}, search_enabled='auto', _storage=None)

Create a new Reader.

reader can optionally parse local files, with the feed URL either a bare path or a file URI.

The interpretation of local feed URLs depends on the value of the feed feed_root argument. It can be one of the following:

None

No local file parsing. Updating local feeds will fail.

'' (the empty string)

Full filesystem access. This should be used only if the source of feed URLs is trusted.

Both absolute and relative feed paths are supported. The current working directory is used normally (as if the path was passed to open()).

Example: Assuming the current working directory is /feeds, all of the following feed URLs correspond to /feeds/feed.xml: feed.xml, /feeds/feed.xml, file:feed.xml, and file:/feeds/feed.xml.

'/path/to/feed/root' (any non-empty string)

An absolute path; all feed URLs are interpreted as relative to it. This can be used if the source of feed URLs is untrusted.

Feed paths must be relative. The current working directory is ignored.

Example: Assuming the feed root is /feeds, feed URLs feed.xml and file:feed.xml correspond to /feeds/feed.xml. /feed.xml and file:/feed.xml are both errors.

Relative paths pointing outside the feed root are errors, to prevent directory traversal attacks. Note that symbolic links inside the feed root can point outside it.

The root and feed paths are joined and normalized with no regard for symbolic links; see os.path.normpath() for details.

Accessing device files on Windows is an error.

Parameters:

  • url (str) – Path to the reader database.

  • feed_root (str or None) – Directory where to look for local feeds. One of None (don’t open local feeds; default), '' (full filesystem access), or '/path/to/feed/root' (an absolute path that feed paths are relative to).

  • read_only (bool) – Only allow read-only storage operations.

  • plugins (iterable(str or callable(Reader)) or None) – An iterable of built-in plugin names or plugin(reader) –> None callables. The callables are called with the reader object before it is returned. Exceptions from plugin code will propagate to the caller. Defaults to DEFAULT_PLUGINS.

  • session_timeout (float or tuple(float, float) or None) – When retrieving HTTP(S) feeds, how many seconds to wait for the server to send data, as a float, or a (connect timeout, read timeout) tuple. Passed to the underlying Requests session.

  • reserved_name_scheme (dict(str, str)) – Value for reserved_name_scheme. Defaults to DEFAULT_RESERVED_NAME_SCHEME.

  • search_enabled (bool or None or 'auto') – Whether to enable search. One of 'auto' (enable on the first update_search() call; default), True (enable), False (disable), None (do nothing).

Returns:

The reader.

Return type:

Reader

Raises:
Changelog

Added in version 3.20: The read_only keyword argument.

Changed in version 3.0: Wrap exceptions raised during plugin initialization in PluginInitError instead of letting them bubble up.

Added in version 2.4: The search_enabled keyword argument.

Changed in version 2.4: Enable search on the first update_search() call. To get the previous behavior (leave search as-is), use search_enabled=None.

Changed in version 2.0: feed_root now defaults to None (don’t open local feeds) instead of '' (full filesystem access).

Added in version 1.17: The reserved_name_scheme keyword argument.

Added in version 1.16: The plugins keyword argument. Using an invalid plugin name raises InvalidPluginError, a ValueError subclass.

Added in version 1.14: The session_timeout keyword argument, with a default of (3.05, 60) seconds; the previous behavior was to never time out.

Added in version 1.6: The feed_root keyword argument.

class reader.Reader(...)

A feed reader.

Persists feed and entry state, provides operations on them, and stores configuration.

Currently, the following feed types are supported:

Additional sources can be added through plugins.

In order to perform maintenance tasks and release underlying resources in a predictable manner, the Reader object should be used as a context manager from each thread where it is used. For convenience, it is possible to use a Reader object directly; in this case, maintenance tasks may sometimes be performed before arbitrary method calls return.

Important

Reader objects should be created using make_reader(); the Reader constructor is not stable yet and may change without any notice.

Changelog

Changed in version 2.16: Allow using a Reader object from multiple threads directly (do not require it to be used as a context manager anymore).

Changed in version 2.16: Allow Reader objects to be reused after closing.

Changed in version 2.16: Allow using a Reader object from multiple asyncio tasks.

Changed in version 2.15: Allow using Reader objects as context managers.

Changed in version 2.15: Allow using Reader objects from threads other than the creating thread.

Changed in version 2.10: Allow passing a (feed URL,) 1-tuple anywhere a feed URL can be passed.

Added in version 1.13: JSON Feed support.

close()

Close this Reader.

Releases any underlying resources associated with the reader.

The reader can be reused after being closed (but you have to call close() again after that).

close() should be called from each thread where the reader is used. Prefer using the reader as a context manager instead.

Raises:

ReaderError –

Changelog

Changed in version 2.16: Allow calling close() from any thread.

add_feed(feed, /, exist_ok=False, *, allow_invalid_url=False)

Add a new feed.

Feed updates are enabled by default.

Parameters:

  • feed (str or tuple(str) or Feed) – The feed URL.

  • allow_invalid_url (bool) – Add feed even if the current Reader configuration does not know how to handle the feed URL (and updates for it would fail).

  • exist_ok (bool) – If true, don’t raise FeedExistsError if the feed already exists.

Raises:
Changelog

Changed in version 3.0: The feed argument is now positional-only.

Added in version 2.8: The exist_ok argument.

Added in version 2.5: The allow_invalid_url keyword argument.

Changed in version 2.5: Validate the new feed URL. To get the previous behavior (no validation), use allow_invalid_url=True.

delete_feed(feed, /, missing_ok=False)

Delete a feed and all of its entries and tags.

Parameters:
Raises:
Changelog

Changed in version 3.0: The feed argument is now positional-only.

Added in version 2.8: The missing_ok argument.

Added in version 1.18: Renamed from remove_feed().

change_feed_url(old, new, /, *, allow_invalid_url=False)

Change the URL of a feed.

User-defined feed attributes are preserved: added, user_title. Feed-defined feed attributes are also preserved, at least until the next update: title, link, author, subtitle (except updated and version, which get set to None). All other feed attributes are set to their default values.

The entries and tags are preserved.

Parameters:

  • old (str or tuple(str) or Feed) – The old feed; must exist.

  • new (str or tuple(str) or Feed) – The new feed; must not exist.

  • allow_invalid_url (bool) – Change feed URL even if the current Reader configuration does not know how to handle the new feed URL (and updates for it would fail).

Raises:
Changelog

Changed in version 3.0: The old and new arguments are now positional-only.

Added in version 2.5: The allow_invalid_url keyword argument.

Changed in version 2.5: Validate the new feed URL. To get the previous behavior (no validation), use allow_invalid_url=True.

Added in version 1.8.

get_feeds(*, feed=None, tags=None, broken=None, updates_enabled=None, new=None, scheduled=False, sort=FeedSort.TITLE, limit=None, starting_after=None)

Get all or some of the feeds.

Parameters:

  • feed (str or tuple(str) or Feed or None) – Only return the feed with this URL.

  • tags (None or bool or list(str or bool or list(str or bool))) – Only return feeds matching these tags; see TagFilterInput for details.

  • broken (bool or None) – Only return broken / healthy feeds.

  • updates_enabled (bool or None) – Only return feeds that have updates enabled / disabled.

  • new (bool or None) – Only return feeds that have never been updated / have been updated before.

  • scheduled (bool) – Only return feeds scheduled to be updated.

  • sort (FeedSort) – How to order feeds; see FeedSort for details.

  • limit (int or None) – A limit on the number of feeds to be returned; by default, all feeds are returned.

  • starting_after (str or tuple(str) or Feed or None) – Return feeds after this feed; a cursor for use in pagination.

Yields:

Feed – Sorted according to sort.

Raises:
Changelog

Added in version 3.13: The scheduled keyword argument.

Changed in version 3.13: new uses last_retrieved instead of last_updated.

Added in version 2.6: The new keyword argument.

Added in version 1.12: The limit and starting_after keyword arguments.

Added in version 1.11: The updates_enabled keyword argument.

Added in version 1.7: The tags keyword argument.

Added in version 1.7: The broken keyword argument.

get_feed(feed: str | FeedLike, /) → Feed
get_feed(feed: str | FeedLike, default: _T, /) → Feed | _T

Get a feed.

Like next(iter(reader.get_feeds(feed=feed))), but raises a custom exception instead of StopIteration.

Parameters:

  • feed (str or tuple(str) or Feed) – The feed URL.

  • default – Returned if given and the feed does not exist.

Returns:

The feed.

Return type:

Feed

Raises:
Changelog

Changed in version 3.0: The feed and default arguments are now positional-only.

get_feed_counts(*, feed=None, tags=None, broken=None, updates_enabled=None, new=None, scheduled=False)

Count all or some of the feeds.

Parameters:

  • feed (str or tuple(str) or Feed or None) – Only count the feed with this URL.

  • tags (None or bool or list(str or bool or list(str or bool))) – Only count feeds matching these tags; see TagFilterInput for details.

  • broken (bool or None) – Only count broken / healthy feeds.

  • updates_enabled (bool or None) – Only count feeds that have updates enabled / disabled.

  • new (bool or None) – Only count feeds that have never been updated / have been updated before.

  • scheduled (bool) – Only count feeds scheduled to be updated.

Return type:

FeedCounts

Raises:

StorageError –

Changelog

Added in version 3.13: The scheduled keyword argument.

Changed in version 3.13: new uses last_retrieved instead of last_updated.

Added in version 2.6: The new keyword argument.

Added in version 1.11.

set_feed_user_title(feed, title, /)

Set a user-defined title for a feed.

Parameters:

  • feed (str or tuple(str) or Feed) – The feed URL.

  • title (str or None) – The title, or None to remove the current title.

Raises:
Changelog

Changed in version 3.0: The feed and title arguments are now positional-only.

enable_feed_updates(feed, /)

Enable updates for a feed.

See update_feeds() for details.

Parameters:

feed (str or tuple(str) or Feed) – The feed URL.

Raises:
Changelog

Changed in version 3.0: The feed argument is now positional-only.

Added in version 1.11.

disable_feed_updates(feed, /)

Disable updates for a feed.

See update_feeds() for details.

Parameters:

feed (str or tuple(str) or Feed) – The feed URL.

Raises:
Changelog

Changed in version 3.0: The feed argument is now positional-only.

Added in version 1.11.

update_feeds(*, feed=None, tags=None, broken=None, updates_enabled=True, new=None, scheduled=False, workers=1)

Update all or some of the feeds.

Silently skip feeds that raise ParseError.

Re-raise before_feeds_update_hooks failures immediately. Collect all other update hook failures and re-raise them as an UpdateHookErrorGroup; currently, only the exceptions for the first 5 feeds with hook failures are collected.

By default, update all the feeds that have updates enabled.

Roughly equivalent to for _ in reader.update_feeds_iter(...): pass.

Parameters:

  • feed (str or tuple(str) or Feed or None) – Only update the feed with this URL.

  • tags (None or bool or list(str or bool or list(str or bool))) – Only update feeds matching these tags; see TagFilterInput for details.

  • broken (bool or None) – Only update broken / healthy feeds.

  • updates_enabled (bool or None) – Only update feeds that have updates enabled / disabled. Defaults to true.

  • new (bool or None) – Only update feeds that have never been updated / have been updated before. Defaults to None.

  • scheduled (bool) – Only update feeds scheduled to be updated.

  • workers (int) – Number of threads to use when getting the feeds.

Raises:
Changelog

Added in version 3.13: The scheduled keyword argument.

Changed in version 3.13: new uses last_retrieved instead of last_updated.

Changed in version 3.8: Wrap unexpected update hook exceptions in UpdateHookError. Try to update all the feeds, don’t stop after a feed/entry hook fails.

Changed in version 3.8: Document this method can raise non-feed-related UpdateErrors (other than UpdateHookError).

Added in version 2.6: The feed, tags, broken, and updates_enabled keyword arguments.

Changed in version 2.0: Remove the deprecated new_only parameter.

Changed in version 2.0: All parameters are keyword-only.

Added in version 1.19: The new parameter. new_only is now deprecated.

Changed in version 1.15: Update entries whenever their content changes, regardless of their updated date.

Content-only updates (not due to an updated change) are limited to 24 consecutive updates, to prevent spurious updates for entries whose content changes excessively (for example, because it includes the current time).

Previously, entries would be updated only if the entry updated was newer than the stored one.

Changed in version 1.11: Only update the feeds that have updates enabled.

update_feeds_iter(*, feed=None, tags=None, broken=None, updates_enabled=True, new=None, scheduled=False, workers=1, _call_feeds_update_hooks=True)

Update all or some of the feeds.

Yield information about each updated feed.

Re-raise before_feeds_update_hooks failures immediately. Yield feed/entry update hook failures. Collect after_feeds_update_hooks failures and re-raise them as an UpdateHookErrorGroup after updating all the feeds.

By default, update all the feeds that have updates enabled.

Parameters:

  • feed (str or tuple(str) or Feed or None) – Only update the feed with this URL.

  • tags (None or bool or list(str or bool or list(str or bool))) – Only update feeds matching these tags; see TagFilterInput for details.

  • broken (bool or None) – Only update broken / healthy feeds.

  • updates_enabled (bool or None) – Only update feeds that have updates enabled / disabled. Defaults to true.

  • new (bool or None) – Only update feeds that have never been updated / have been updated before. Defaults to None.

  • scheduled (bool) – Only update feeds scheduled to be updated.

  • workers (int) – Number of threads to use when getting the feeds.

Yields:

UpdateResult – An (url, value) pair; the value is one of:

  • a summary of the updated feed, if the update was successful

  • None, if the server indicated the feed has not changed since the last update

  • an exception instance

Currently, the exception can be:

…but other UpdateError subclasses may be yielded in the future.

Raises:
Changelog

Added in version 3.13: The scheduled keyword argument.

Changed in version 3.13: new uses last_retrieved instead of last_updated.

Changed in version 3.8: Wrap unexpected update hook exceptions in UpdateHookError. Try to update all the feeds, don’t stop after a feed/entry hook fails.

Changed in version 3.8: Document this method can raise non-feed-related UpdateErrors (other than UpdateHookError).

Added in version 2.6: The feed, tags, broken, and updates_enabled keyword arguments.

Changed in version 2.0: Remove the deprecated new_only parameter.

Changed in version 2.0: All parameters are keyword-only.

Added in version 1.19: The new parameter. new_only is now deprecated.

Changed in version 1.15: Update entries whenever their content changes. See update_feeds() for details.

Added in version 1.14.

update_feed(feed, /)

Update a single feed.

The feed will be updated even if updates are disabled for it, or if it is not scheduled to be updated.

Like next(iter(reader.update_feeds_iter(feed=feed, updates_enabled=None)))[1], but raises the UpdateError, if any.

Parameters:

feed (str or tuple(str) or Feed) – The feed URL.

Returns:

A summary of the updated feed or None, if the server indicated the feed has not changed since the last update.

Return type:

UpdatedFeed or None

Raises:
Changelog

Changed in version 3.8: Wrap unexpected update hook exceptions in UpdateHookError.

Changed in version 3.8: Document this method can raise UpdateErrors (other than ParseError and UpdateHookError).

Changed in version 3.0: The feed argument is now positional-only.

Changed in version 1.15: Update entries whenever their content changes. See update_feeds() for details.

Changed in version 1.14: The method now returns UpdatedFeed or None instead of None.

get_entries(*, feed=None, entry=None, read=None, important=None, has_enclosures=None, source=None, tags=None, feed_tags=None, sort=EntrySort.RECENT, limit=None, starting_after=None)

Get all or some of the entries.

Parameters:

  • feed (str or tuple(str) or Feed or None) – Only return the entries for this feed.

  • entry (tuple(str, str) or Entry or None) – Only return the entry with this (feed URL, entry id) tuple.

  • read (bool or None) – Only return (un)read entries.

  • important (bool or None or str) – Only return (un)important entries. For more precise filtering, use one of the TristateFilterInput string filters.

  • has_enclosures (bool or None) – Only return entries that (don’t) have enclosures.

  • source (str or tuple(str) or Feed or None) – Only return the entries for this source.

  • tags (None or bool or list(str or bool or list(str or bool))) – Only return entries matching these tags; see TagFilterInput for details.

  • feed_tags (None or bool or list(str or bool or list(str or bool))) – Only return entries from feeds matching these tags; see TagFilterInput for details.

  • sort (EntrySort) – How to order entries; see EntrySort for details.

  • limit (int or None) – A limit on the number of entries to be returned; by default, all entries are returned.

  • starting_after (tuple(str, str) or Entry or None) – Return entries after this entry; a cursor for use in pagination. Using starting_after with sort=RANDOM is not supported.

Yields:

Entry – Sorted according to sort.

Raises:
Changelog

Added in version 3.16: The source keyword argument.

Added in version 3.11: The tags keyword argument.

Changed in version 3.5: The important argument also accepts string values.

Added in version 1.12: The limit and starting_after keyword arguments.

Added in version 1.7: The feed_tags keyword argument.

Added in version 1.2: The sort keyword argument.

get_entry(entry: tuple[str, str] | EntryLike, /) → Entry
get_entry(entry: tuple[str, str] | EntryLike, default: _T, /) → Entry | _T

Get an entry.

Like next(iter(reader.get_entries(entry=entry))), but raises a custom exception instead of StopIteration.

Parameters:

  • entry (tuple(str, str) or Entry) – (feed URL, entry id) tuple.

  • default – Returned if given and the entry does not exist.

Returns:

The entry.

Return type:

Entry

Raises:
Changelog

Changed in version 3.0: The entry and default arguments are now positional-only.

get_entry_counts(*, feed=None, entry=None, read=None, important=None, has_enclosures=None, source=None, tags=None, feed_tags=None)

Count all or some of the entries.

Parameters:

  • feed (str or tuple(str) or Feed or None) – Only count the entries for this feed.

  • entry (tuple(str, str) or Entry or None) – Only count the entry with this (feed URL, entry id) tuple.

  • read (bool or None) – Only count (un)read entries.

  • important (bool or None or str) – Only count (un)important entries. For more precise filtering, use one of the TristateFilterInput string filters.

  • has_enclosures (bool or None) – Only count entries that (don’t) have enclosures.

  • source (str or tuple(str) or Feed or None) – Only count the entries for this source.

  • tags (None or bool or list(str or bool or list(str or bool))) – Only count entries matching these tags; see TagFilterInput for details.

  • feed_tags (None or bool or list(str or bool or list(str or bool))) – Only count entries from feeds matching these tags; see TagFilterInput for details.

Return type:

EntryCounts

Raises:

StorageError –

Changelog

Added in version 3.16: The source keyword argument.

Added in version 3.11: The tags keyword argument.

Changed in version 3.5: The important argument also accepts string values.

Added in version 1.11.

set_entry_read(entry, read, /, modified=no value)

Mark an entry as read or unread, possibly with a custom timestamp.

Parameters:

  • entry (tuple(str, str) or Entry) – (feed URL, entry id) tuple.

  • read (bool) – Mark the entry as read if true, and as unread otherwise.

  • modified (datetime or None) – Set read_modified to this. Naive datetimes are normalized by passing them to astimezone(). Defaults to the current time.

Raises:
Changelog

Changed in version 3.5: Do not coerce read to bool anymore, require it to be True or False.

Changed in version 3.0: The entry and read arguments are now positional-only.

Added in version 2.2.

mark_entry_as_read(entry, /)

Mark an entry as read.

Alias for set_entry_read(entry, True).

Parameters:

entry (tuple(str, str) or Entry) – (feed URL, entry id) tuple.

Raises:
Changelog

Changed in version 3.0: The entry argument is now positional-only.

Added in version 1.18: Renamed from mark_as_read().

mark_entry_as_unread(entry, /)

Mark an entry as unread.

Alias for set_entry_read(entry, False).

Parameters:

entry (tuple(str, str) or Entry) – (feed URL, entry id) tuple.

Raises:
Changelog

Changed in version 3.0: The entry argument is now positional-only.

Added in version 1.18: Renamed from mark_as_unread().

set_entry_important(entry, important, /, modified=no value)

Mark an entry as important or unimportant, possibly with a custom timestamp.

Parameters:

  • entry (tuple(str, str) or Entry) – (feed URL, entry id) tuple.

  • important (bool or None) – Mark the entry as important if true, as unimportant if false, or as not set if none.

  • modified (datetime or None) – Set important_modified to this. Naive datetimes are normalized by passing them to astimezone(). Defaults to the current time.

Raises:
Changelog

Changed in version 3.5: important can now be None.

Changed in version 3.5: Do not coerce important to bool anymore, require it to be True or False or None.

Changed in version 3.0: The entry and important arguments are now positional-only.

Added in version 2.2.

mark_entry_as_important(entry, /)

Mark an entry as important.

Alias for set_entry_important(entry, True).

Parameters:

entry (tuple(str, str) or Entry) – (feed URL, entry id) tuple.

Raises:
Changelog

Changed in version 3.0: The entry argument is now positional-only.

Added in version 1.18: Renamed from mark_as_important().

mark_entry_as_unimportant(entry, /)

Mark an entry as unimportant.

Alias for set_entry_important(entry, False).

Parameters:

entry (tuple(str, str) or Entry) – (feed URL, entry id) tuple.

Raises:
Changelog

Changed in version 3.0: The entry argument is now positional-only.

Added in version 1.18: Renamed from mark_as_unimportant().

add_entry(entry, /, *, overwrite=False)

Add a new entry to an existing feed.

entry can be any Entry-like object, or a mapping of the same shape:

>>> from types import SimpleNamespace
>>> reader.add_entry(SimpleNamespace(
...     feed_url='http://example.com',
...     id='one',
...     title='title',
...     enclosures=[SimpleNamespace(href='enclosure')],
... ))
>>> reader.add_entry({
...     'feed_url': 'http://example.com',
...     'id': 'two',
...     'updated': datetime.now(timezone.utc),
...     'content': [{'value': 'content'}],
... })

The following attributes are used (they must have the same types as on Entry):

Naive datetimes are normalized by passing them to astimezone().

The added entry will be added_by 'user'.

Parameters:

  • entry (Entry or dict) – An entry-like object or equivalent mapping.

  • overwrite (bool) – If true and the entry already exists, overwrite it instead of raising EntryExistsError.

Raises:
Changelog

Added in version 3.18: The overwrite argument.

Changed in version 3.16: Allow setting source.

Changed in version 3.0: The entry argument is now positional-only.

Added in version 2.5.

delete_entry(entry, /, missing_ok=False)

Delete an entry.

Currently, only entries added by add_entry() and copy_entry() (added_by 'user') can be deleted.

Parameters:
Raises:
Changelog

Changed in version 3.0: The entry argument is now positional-only.

Added in version 2.8: The missing_ok argument.

Added in version 2.5.

copy_entry(src, dst, /)

Copy an entry from one feed to another.

All Entry attributes that belong to the entry are copied, including timestamps like added, entry tags, and hidden attributes that affect behavior (e.g. sorting).

If the original does not already have a source, the copy’s source will be set to the original’s feed, with the feed’s user_title taking precedence over title as the source title.

The copy entry will be added_by 'user'.

Parameters:
Raises:
Changelog

Added in version 3.16.

Enable full-text search.

Calling this method if search is already enabled is a no-op.

Raises:

Disable full-text search.

Calling this method if search is already disabled is a no-op.

Raises:

SearchError –

is_search_enabled()

Check if full-text search is enabled.

Returns:

Whether search is enabled or not.

Return type:

bool

Raises:

SearchError –

Update the full-text search index.

Search must be enabled to call this method.

If make_reader() was called with search_enabled='auto' and search is disabled, it will be enabled automatically.

Raises:
search_entries(query, /, *, feed=None, entry=None, read=None, important=None, has_enclosures=None, source=None, tags=None, feed_tags=None, sort=EntrySearchSort.RELEVANT, limit=None, starting_after=None)

Get entries matching a full-text search query.

Note

The query syntax is dependent on the search provider.

The default (and for now, only) search provider is SQLite FTS5. You can find more details on its query syntax here: https://www.sqlite.org/fts5.html#full_text_query_syntax

The columns available in queries are:

  • title: the entry title

  • feed: the feed or source title (feed_resolved_title)

  • content: the entry main text content; this includes the summary and the value of contents that have text/(x)html, text/plain or missing content types

Query examples:

  • hello internet: entries that match “hello” and “internet”

  • hello NOT internet: entries that match “hello” but do not match “internet”

  • hello feed: cortex: entries that match “hello” anywhere, and their feed title matches “cortex”

  • hello NOT feed: internet: entries that match “hello” anywhere, and their feed title does not match “internet”

Changelog

Changed in version 3.16: The feed column now indexes feed_resolved_title, instead of feed user_title or title.

Search must be enabled to call this method.

Parameters:

  • query (str) – The search query.

  • feed (str or tuple(str) or Feed or None) – Only search the entries for this feed.

  • entry (tuple(str, str) or Entry or None) – Only search for the entry with this (feed URL, entry id) tuple.

  • read (bool or None) – Only search (un)read entries.

  • important (bool or None or str) – Only search (un)important entries. For more precise filtering, use one of the TristateFilterInput string filters.

  • has_enclosures (bool or None) – Only search entries that (don’t) have enclosures.

  • source (str or tuple(str) or Feed or None) – Only search the entries for this source.

  • tags (None or bool or list(str or bool or list(str or bool))) – Only search entries matching these tags; see TagFilterInput for details.

  • feed_tags (None or bool or list(str or bool or list(str or bool))) – Only search entries from feeds matching these tags; see TagFilterInput for details.

  • sort (EntrySearchSort) – How to order results; see EntrySearchSort for details.

  • limit (int or None) – A limit on the number of results to be returned; by default, all results are returned.

  • starting_after (tuple(str, str) or EntrySearchResult or None) – Return results after this result; a cursor for use in pagination. Using starting_after with sort=RANDOM is not supported.

Yields:

EntrySearchResult – Sorted according to sort.

Raises:
Changelog

Added in version 3.16: The source keyword argument.

Added in version 3.11: The tags keyword argument.

Changed in version 3.5: The important argument also accepts string values.

Changed in version 3.0: The query argument is now positional-only.

Added in version 1.12: The limit and starting_after keyword arguments.

Added in version 1.7: The feed_tags keyword argument.

Added in version 1.4: The sort keyword argument.

search_entry_counts(query, /, *, feed=None, entry=None, read=None, important=None, has_enclosures=None, source=None, tags=None, feed_tags=None)

Count entries matching a full-text search query.

See search_entries() for details on the query syntax.

Search must be enabled to call this method.

Parameters:

  • query (str) – The search query.

  • feed (str or tuple(str) or Feed or None) – Only count the entries for this feed.

  • entry (tuple(str, str) or Entry or None) – Only count the entry with this (feed URL, entry id) tuple.

  • read (bool or None or str) – Only count (un)read entries. For more precise filtering, use one of the TristateFilterInput string filters.

  • important (bool or None) – Only count (un)important entries.

  • has_enclosures (bool or None) – Only count entries that (don’t) have enclosures.

  • source (str or tuple(str) or Feed or None) – Only count the entries for this source.

  • tags (None or bool or list(str or bool or list(str or bool))) – Only count entries matching these tags; see TagFilterInput for details.

  • feed_tags (None or bool or list(str or bool or list(str or bool))) – Only count entries from feeds matching these tags; see TagFilterInput for details.

Return type:

EntrySearchCounts

Raises:
Changelog

Added in version 3.16: The source keyword argument.

Added in version 3.11: The tags keyword argument.

Changed in version 3.5: The important argument also accepts string values.

Changed in version 3.0: The query argument is now positional-only.

Added in version 1.11.

get_tags(resource, /, *, key=None)

Get all or some tags of a resource as (key, value) pairs.

resource can have one of the following types:

Feed or str or (str,)

A feed or feed URL (possibly enclosed in a tuple).

Entry or (str, str)

An entry or a (feed URL, entry id) pair representing an entry.

() (empty tuple)

Special value representing the global tag namespace.

Parameters:

  • resource (reader.types.ResourceInput) – The resource to get tags for.

  • key (str or None) – Only return the value for this key.

Yields:

tuple(str, JSONType) – (key, value) pairs, in undefined order. JSONType is whatever json.dumps() accepts.

Raises:

StorageError –

Changelog

Changed in version 3.0: The resource argument is now positional-only.

Changed in version 2.10: Support entry and global tags.

Changed in version 2.10: Removed support for the (None,) (any feed) and None (any resource) wildcard resource values.

Added in version 2.8.

get_tag_keys(resource=None, /)

Get the keys of all or some resource tags.

Equivalent to sorted(k for k, _ in reader.get_tags(resource)).

See get_tags() for possible resource values. In addition, resource can have one of the following wildcard values:

(None,)

Any feed.

(None, None)

Any entry.

None

Any resource (feed, entry, or the global namespace).

Parameters:

resource (reader.types.AnyResourceInput) – Only return tag keys for this resource.

Yields:

str – The tag keys, in alphabetical order.

Raises:

StorageError –

Changelog

Changed in version 3.0: The resource argument is now positional-only.

Changed in version 2.10: Support entry and global tags.

Added in version 2.8.

get_tag(resource: ResourceInput, key: str, /) → JSONType
get_tag(resource: ResourceInput, key: str, default: _T, /) → JSONType | _T

Get the value of this resource tag.

Like next(iter(reader.get_tags(resource, key=key)))[1], but raises a custom exception instead of StopIteration.

See get_tags() for possible resource values.

Parameters:

  • resource – The resource.

  • key (str) – The key of the tag to retrieve.

  • default – Returned if given and no tag exists for key.

Returns:

The tag value. JSONType is whatever json.dumps() accepts.

Return type:

JSONType

Raises:
Changelog

Changed in version 3.0: The resource, key, and default arguments are now positional-only.

Changed in version 2.10: Support entry and global tags.

Added in version 2.8.

set_tag(resource: ResourceInput, key: str, /) → None
set_tag(resource: ResourceInput, key: str, value: JSONType, /) → None

Set the value of this resource tag.

See get_tags() for possible resource values.

Parameters:

  • resource – The resource.

  • key (str) – The key of the tag to set.

  • value (JSONType) – The value of the tag to set. If not provided, and the tag already exists, the value remains unchanged; if the tag does not exist, it is set to None. JSONType is whatever json.dumps() accepts.

Raises:
Changelog

Changed in version 3.0: The resource, key, and value arguments are now positional-only.

Changed in version 2.10: Support entry and global tags.

Added in version 2.8.

delete_tag(resource, key, /, missing_ok=False)

Delete this resource tag.

See get_tags() for possible resource values.

Parameters:

  • resource (reader.types.ResourceInput) – The resource.

  • key (str) – The key of the tag to delete.

  • missing_ok (bool) – If true, don’t raise TagNotFoundError if the tag does not exist.

Raises:
Changelog

Changed in version 3.0: The resource and key arguments are now positional-only.

Changed in version 2.10: Support entry and global tags.

Added in version 2.8.

make_reader_reserved_name(key, /)

Create a reader-reserved tag name. See Reserved names for details.

Uses reserved_name_scheme to build names of the format:

{reader_prefix}{key}

Using the default scheme:

>>> reader.make_reader_reserved_name('key')
'.reader.key'
Parameters:

key (str) – A key.

Returns:

The name.

Return type:

str

Changelog

Changed in version 3.0: The key argument is now positional-only.

Added in version 1.17.

make_plugin_reserved_name(plugin_name, key=None, /)

Create a plugin-reserved tag name. See Reserved names for details.

Plugins should use this to generate names for plugin-specific tags.

Uses reserved_name_scheme to build names of the format:

{plugin_prefix}{plugin_name}
{plugin_prefix}{plugin_name}{separator}{key}

Using the default scheme:

>>> reader.make_plugin_reserved_name('myplugin')
'.plugin.myplugin'
>>> reader.make_plugin_reserved_name('myplugin', 'key')
'.plugin.myplugin.key'
Parameters:

  • plugin_name (str) – The plugin package/module name.

  • key (str or None) – A key; if more than one reserved name is needed.

Returns:

The name.

Return type:

str

Changelog

Changed in version 3.0: The plugin_name and key arguments are now positional-only.

Added in version 1.17.

property reserved_name_scheme: Mapping[str, str]

Mapping used to build Reserved names. See make_reader_reserved_name() and make_plugin_reserved_name() for details on how this is used.

The default scheme is DEFAULT_RESERVED_NAME_SCHEME.

The returned mapping is immutable; assign a new mapping to change the scheme.

Changelog

Added in version 1.17.

Type:

dict(str, str)

property before_feeds_update_hooks: MutableSequence[Callable[[Reader], None]]

List of functions called once before updating any feeds, at the beginning of update_feeds() / update_feeds_iter(), but not update_feed().

Each function is called with:

  • reader – the Reader instance

Each function should return None.

The hooks are run in order. Exceptions raised by hooks are wrapped in a SingleUpdateHookError and re-raised (hooks after the one that failed are not run).

Changelog

Changed in version 3.8: Wrap unexpected exceptions in UpdateHookError.

Added in version 2.12.

property before_feed_update_hooks: MutableSequence[Callable[[Reader, str], None]]

List of functions called for each updated feed before the feed is updated.

Each function is called with:

  • reader – the Reader instance

  • feed – the str feed URL

Each function should return None.

The hooks are run in order. Exceptions raised by hooks are wrapped in a SingleUpdateHookError and re-raised (hooks after the one that failed are not run).

Changelog

Changed in version 3.8: Wrap unexpected exceptions in UpdateHookError.

Added in version 2.7.

property after_entry_update_hooks: MutableSequence[Callable[[Reader, EntryData, EntryUpdateStatus], None]]

List of functions called for each updated entry after the feed is updated.

Each function is called with:

Each function should return None.

Warning

The only entry attributes guaranteed to be present are feed_url, id, and resource_id; all other attributes may be missing (accessing them may raise AttributeError).

The hooks are run in order. Exceptions raised by hooks are wrapped in a SingleUpdateHookError, collected, and re-raised as an UpdateHookErrorGroup after all the hooks are run; currently, only the exceptions for the first 5 entries with hook failures are collected.

Changelog

Changed in version 3.8: Wrap unexpected exceptions in UpdateHookError. Try to run all hooks, don’t stop after one fails.

Added in version 1.20.

property after_feed_update_hooks: MutableSequence[Callable[[Reader, str], None]]

List of functions called for each updated feed after the feed is updated.

Each function is called with:

  • reader – the Reader instance

  • feed – the str feed URL

Each function should return None.

The hooks are run in order. Exceptions raised by hooks are wrapped in a SingleUpdateHookError, collected, and re-raised as an UpdateHookErrorGroup after all the hooks are run.

Changelog

Changed in version 3.8: Wrap unexpected exceptions in UpdateHookError. Try to run all hooks, don’t stop after one fails.

Added in version 2.2.

property after_feeds_update_hooks: MutableSequence[Callable[[Reader], None]]

List of functions called once after updating all feeds, at the end of update_feeds() / update_feeds_iter(), but not update_feed().

Each function is called with:

  • reader – the Reader instance

Each function should return None.

The hooks are run in order. Exceptions raised by hooks are wrapped in a SingleUpdateHookError, collected, and re-raised as an UpdateHookErrorGroup after all the hooks are run.

Changelog

Changed in version 3.8: Wrap unexpected exceptions in UpdateHookError. Try to run all hooks, don’t stop after one fails.

Added in version 2.12.

Data objects

class reader.Feed(url, updated=None, title=None, link=None, author=None, subtitle=None, version=None, user_title=None, added=None, last_updated=None, last_exception=None, updates_enabled=True, update_after=None, last_retrieved=None)

Data type representing a feed.

All datetime attributes are timezone-aware, with the timezone set to utc.

Changelog

Changed in version 2.0: datetime attributes are now timezone-aware; prior to 2.0, they were naive datetimes representing UTC times.

url: str

The URL of the feed.

updated: datetime | None = None

The date the feed was last updated, according to the feed.

title: str | None = None

The title of the feed.

The URL of a page associated with the feed.

author: str | None = None

The author of the feed.

subtitle: str | None = None

A description or subtitle for the feed.

Changelog

Added in version 2.4.

version: str | None = None

The feed type and version.

For Atom and RSS, provided by feedparser (e.g. atom10, rss20); full list.

For JSON Feed:

json10

JSON Feed 1.0

json11

JSON Feed 1.1

json

JSON Feed (unknown or unrecognized version)

Plugins may add other versions.

Changelog

Added in version 2.4.

user_title: str | None = None

User-defined feed title.

added: datetime = None

The date when the feed was added.

Changelog

Added in version 1.3.

last_updated: datetime | None = None

The date when the feed was last (successfully) updated by reader.

Changelog

Added in version 1.3.

last_exception: ExceptionInfo | None = None

If a UpdateError happened during the last update, its details.

Changelog

Changed in version 3.9: Store the details of any UpdateError (except hook errors), not just the __cause__ of ParseErrors.

Added in version 1.3.

updates_enabled: bool = True

Whether updates are enabled for this feed.

Changelog

Added in version 1.11.

update_after: datetime | None = None

The earliest time the feed will next be updated (when using scheduled updates).

Changelog

Added in version 3.13.

last_retrieved: datetime | None = None

The date when the feed was last retrieved by reader, regardless of the outcome.

Changelog

Added in version 3.13.

property resource_id: tuple[str]

Alias for (url,).

Changelog

Added in version 2.17.

property resolved_title: str | None

user_title or title.

Changelog

Added in version 3.16.

class reader.ExceptionInfo(type_name, value_str, traceback_str)

Data type representing information about an exception.

Changelog

Added in version 1.3.

type_name: str

The fully qualified name of the exception type.

value_str: str

String representation of the exception value.

traceback_str: str

String representation of the exception traceback.

class reader.Entry(id, updated=None, title=None, link=None, author=None, published=None, summary=None, content=(), enclosures=(), source=None, read=False, read_modified=None, important=None, important_modified=None, added=None, added_by=None, last_updated=None, original_feed_url=None, _sequence=None, feed=None)

Data type representing an entry.

All datetime attributes are timezone-aware, with the timezone set to utc.

Changelog

Changed in version 2.0: datetime attributes are now timezone-aware; prior to 2.0, they were naive datetimes representing UTC times.

property feed_url: str

The feed URL.

id: str

The entry id.

updated: datetime | None = None

The date the entry was last updated, according to the feed.

Changelog

Changed in version 2.5: Is now None if missing in the feed; use updated_not_none for the pre-2.5 behavior.

Changed in version 2.0: May be None in some cases. In a future version, will be None if missing in the feed; use updated_not_none for the pre-2.0 behavior.

title: str | None = None

The title of the entry.

The URL of a page associated with the entry.

author: str | None = None

The author of the feed.

published: datetime | None = None

The date the entry was published, according to the feed.

summary: str | None = None

A summary of the entry.

content: Sequence[Content] = ()

Full content of the entry. A sequence of Content objects.

enclosures: Sequence[Enclosure] = ()

External files associated with the entry. A sequence of Enclosure objects.

source: EntrySource | None = None

Metadata of the source feed if the entry is a copy.

Changelog

Added in version 3.16.

read: bool = False

Whether the entry was read or not.

read_modified: datetime | None = None

The date when read was last set by the user; None if that never happened, or the entry predates the date being recorded.

Changelog

Added in version 2.2.

important: bool | None = None

Whether the entry is important or not. None means not set. False means “explicitly unimportant”.

Changelog

Changed in version 3.5: important is now an optional bool, and defaults to None.

important_modified: datetime | None = None

The date when important was last set by the user; None if that never happened, or the entry predates the date being recorded.

Changelog

Added in version 2.2.

added: datetime = None

The date when the entry was added (first updated) to reader.

Changelog

Added in version 2.5.

added_by: Literal['feed', 'user'] = None

The source of the entry. One of 'feed', 'user'.

Other values may be added in the future.

Changelog

Added in version 2.5.

last_updated: datetime = None

The date when the entry was last updated by reader.

Changelog

Added in version 1.3.

original_feed_url: str = None

The URL of the original feed of the entry.

If the feed URL never changed, the same as feed_url.

Changelog

Added in version 1.8.

feed: Feed = None

The entry’s feed.

property resource_id: tuple[str, str]

Alias for (feed_url, id).

Changelog

Added in version 2.17.

property updated_not_none: datetime

Like updated, but guaranteed to be set (not None).

If the entry updated is missing in the feed, defaults to when the entry was first added.

Changelog

Added in version 2.0: Identical to the behavior of updated before 2.0.

get_content(*, prefer_summary=False)

Return a text content OR the summary.

Prefer HTML content, when available.

Parameters:

prefer_summary (bool) – Return summary, if available.

Returns:

The content, if found.

Return type:

Content or none

Changelog

Added in version 2.12.

property feed_resolved_title: str | None

Feed resolved_title, source title, or "{source} ({feed})" if both are present and different.

Changelog

Changed in version 3.17: Return both the source and feed titles only if they are different.

Added in version 3.16.

class reader.Content(value, type=None, language=None)

Data type representing a piece of content.

value: str

The content value.

type: str | None = None

The content type.

language: str | None = None

The content language.

property is_html: bool

Whether the content is (X)HTML.

True if the content does not have a type.

Changelog

Added in version 2.12.

class reader.Enclosure(href, type=None, length=None)

Data type representing an external file.

href: str

The file URL.

type: str | None = None

The file content type.

length: int | None = None

The file length.

class reader.EntrySource(url=None, updated=None, title=None, link=None, author=None, subtitle=None)

Metadata of a source feed (used with Entry.source).

Changelog

Added in version 3.16.

url: str | None = None

The URL of the feed.

updated: datetime | None = None

The date the feed was last updated, according to the feed.

title: str | None = None

The title of the feed.

The URL of a page associated with the feed.

author: str | None = None

The author of the feed.

subtitle: str | None = None

A description or subtitle for the feed.

class reader.EntrySearchResult(feed_url, id, metadata=<factory>, content=<factory>)

Data type representing the result of an entry search.

metadata and content are dicts where the key is the path of an entry attribute, and the value is a HighlightedString snippet corresponding to that attribute, with HTML stripped.

>>> result = next(reader.search_entries('hello internet'))
>>> result.metadata['.title'].value
'A Recent Hello Internet'
>>> reader.get_entry(result).title
'A Recent Hello Internet'
feed_url: str

The feed URL.

id: str

The entry id.

metadata: Mapping[str, HighlightedString]

Matching entry metadata, in arbitrary order. Currently entry.title and entry.feed.user_title/.title / entry.source.title / entry.feed_resolved_title.

content: Mapping[str, HighlightedString]

Matching entry content, sorted by relevance. Any of entry.summary and entry.content[].value.

property resource_id: tuple[str, str]

Alias for (feed_url, id).

Changelog

Added in version 2.17.

class reader.HighlightedString(value='', highlights=())

A string that has some of its parts highlighted.

value: str = ''

The underlying string.

highlights: Sequence[slice] = ()

The highlights; non-overlapping slices with positive start/stop and None step.

classmethod extract(text, before, after)

Extract highlights with before/after markers from text.

>>> HighlightedString.extract( '>one< two', '>', '<')
HighlightedString(value='one two', highlights=(slice(0, 3, None),))
Parameters:

  • text (str) – The original text, with highlights marked by before and after.

  • before (str) – Highlight start marker.

  • after (str) – Highlight stop marker.

Returns:

A highlighted string.

Return type:

HighlightedString

split()

Split the highlighted string into parts.

>>> list(HighlightedString('abcd', [slice(1, 3)]))
['a', 'bc', 'd']
Yields:

str – The parts (always an odd number); parts with odd indexes are highlighted, parts with even indexes are not.

apply(before, after, func=None)

Apply before/end markers on the highlighted string.

The opposite of extract().

>>> HighlightedString('abcd', [slice(1, 3)]).apply('>', '<')
'a>bc<d'
>>> HighlightedString('abcd', [slice(1, 3)]).apply('>', '<', str.upper)
'A>BC<D'
Parameters:

  • before (str) – Highlight start marker.

  • after (str) – Highlight stop marker.

  • func (callable((str), str) or none) – If given, a function to apply to the string parts before adding the markers.

Returns:

The string, with highlights marked by before and after.

Return type:

str

class reader.FeedCounts(total=None, broken=None, updates_enabled=None)

Count information about feeds.

Changelog

Added in version 1.11.

total: int | None = None

Total number of feeds.

broken: int | None = None

Number of broken feeds.

updates_enabled: int | None = None

Number of feeds that have updates enabled.

class reader.EntryCounts(total=None, read=None, important=None, unimportant=None, has_enclosures=None, averages=None)

Count information about entries.

Changelog

Added in version 1.11.

total: int | None = None

Total number of entries.

read: int | None = None

Number of read entries.

important: int | None = None

Number of important entries.

unimportant: int | None = None

Number of unimportant entries.

Changelog

Added in version 3.14.

has_enclosures: int | None = None

Number of entries that have enclosures.

averages: tuple[float, float, float] | None = None

Average entries per day during the last 1, 3, 12 months, as a 3-tuple.

Changelog

Added in version 2.1.

class reader.EntrySearchCounts(total=None, read=None, important=None, unimportant=None, has_enclosures=None, averages=None)

Count information about entry search results.

Changelog

Added in version 1.11.

total: int | None = None

Total number of entries.

read: int | None = None

Number of read entries.

important: int | None = None

Number of important entries.

unimportant: int | None = None

Number of unimportant entries.

Changelog

Added in version 3.14.

has_enclosures: int | None = None

Number of entries that have enclosures.

averages: tuple[float, float, float] | None = None

Average entries per day during the last 1, 3, 12 months, as a 3-tuple.

Changelog

Added in version 2.1.

class reader.UpdateResult(url, value)

Named tuple representing the result of a feed update.

Changelog

Added in version 1.14.

url: str

The URL of the feed.

value: UpdatedFeed | None | UpdateError

One of:

UpdatedFeed

If the update was successful; a summary of the updated feed.

None

If the server indicated the feed has not changed since the last update without returning any data.

UpdateError

If there was an error while updating the feed.

Changelog

Changed in version 3.8: Narrow down the error type from ReaderError to UpdateError.

property updated_feed: UpdatedFeed | None

The updated feed, if the update was successful, None otherwise.

Changelog

Added in version 2.1.

property error: UpdateError | None

The exception, if there was an error, None otherwise.

Changelog

Added in version 2.1.

property not_modified: bool

True if the feed has not changed (either because the server returned no data, or because the data didn’t change), false otherwise.

Changelog

Added in version 2.1.

class reader.UpdatedFeed(url, new=0, modified=0, unmodified=0)

The result of a successful feed update.

Changelog

Changed in version 1.19: The updated argument/attribute was renamed to modified.

Added in version 1.14.

url: str

The URL of the feed.

new: int = 0

The number of new entries (entries that did not previously exist in storage).

Changelog

Changed in version 3.2: This field is now optional, and defaults to 0.

modified: int = 0

The number of modified entries (entries that existed in storage, but had different data than the corresponding feed file entry.)

Changelog

Changed in version 3.2: This field is now optional, and defaults to 0.

unmodified: int = 0

The number of unmodified entries (entries that existed in storage, but had the same data in the corresponding feed file entry.)

Changelog

Added in version 3.2.

property total: int

The total number of entries in the retrieved feed.

Changelog

Added in version 3.2.

class reader.EntryUpdateStatus(*values)

Enum representing how an entry was updated.

Changelog

Added in version 1.20.

NEW = 'new'

The entry did not previously exist in storage.

MODIFIED = 'modified'

The entry existed in storage, but had different data from the one in the feed file.

Exceptions

exception reader.ReaderError(message='')

Base for all public exceptions.

exception reader.FeedError(url, /, message='')

Bases: ReaderError

A feed error occurred.

Changelog

Changed in version 3.0: The url argument is now positional-only.

property resource_id: tuple[str]

Alias for (url,).

Changelog

Added in version 2.17.

exception reader.FeedExistsError(url, /, message='')

Bases: FeedError

Feed already exists.

exception reader.FeedNotFoundError(url, /, message='')

Bases: FeedError, ResourceNotFoundError

Feed not found.

exception reader.InvalidFeedURLError(url, /, message='')

Bases: FeedError, ValueError

Invalid feed URL.

Changelog

Added in version 2.5.

exception reader.EntryError(feed_url, id, /, message='')

Bases: ReaderError

An entry error occurred.

Changelog

Changed in version 3.0: The feed_url and id arguments are now positional-only.

Changed in version 1.18: The url argument/attribute was renamed to feed_url.

property resource_id: tuple[str, str]

Alias for (feed_url, id).

Changelog

Added in version 2.17.

exception reader.EntryExistsError(feed_url, id, /, message='')

Bases: EntryError

Entry already exists.

Changelog

Added in version 2.5.

exception reader.EntryNotFoundError(feed_url, id, /, message='')

Bases: EntryError, ResourceNotFoundError

Entry not found.

exception reader.UpdateError(message='')

Bases: ReaderError

An error occurred while updating the feed.

Parent of all update-related exceptions.

Changelog

Added in version 3.8.

exception reader.ParseError(url, /, message='')

Bases: UpdateError, FeedError, ReaderWarning

An error occurred while retrieving/parsing the feed.

The original exception should be chained to this one (e.__cause__).

Changelog

Changed in version 3.8: Inherit from UpdateError.

exception reader.UpdateHookError(message='')

Bases: UpdateError

One or more update hooks (unexpectedly) failed.

Not raised directly; allows catching any hook errors with a single except clause.

To inspect individual hook failures, use except* with SingleUpdateHookError (or, on Python earlier than 3.11, check if the exception isinstance() UpdateHookErrorGroup and examine its exceptions).

Changelog

Added in version 3.8.

exception reader.SingleUpdateHookError(when, hook, resource_id=None)

Bases: UpdateHookError

An update hook (unexpectedly) failed.

The original exception should be chained to this one (e.__cause__).

Changelog

Added in version 3.8.

when

The update phase (the hook type). One of:

  • 'before_feeds_update'

  • 'before_feed_update'

  • 'after_entry_update'

  • 'after_feed_update'

  • 'after_feeds_update'

hook

The hook.

resource_id

The resource_id of the resource, if any.

exception reader.UpdateHookErrorGroup(msg, excs, /)

Bases: ExceptionGroup[_UpdateHookErrorT], UpdateHookError

A (possibly nested) ExceptionGroup of UpdateHookErrors.

Changelog

Added in version 3.8.

exception reader.StorageError(message='')

Bases: ReaderError

An exception was raised by the underlying storage.

The original exception should be chained to this one (e.__cause__).

exception reader.SearchError(message='')

Bases: ReaderError

A search-related exception.

If caused by an exception raised by the underlying search provider, the original exception should be chained to this one (e.__cause__).

exception reader.SearchNotEnabledError(message='')

Bases: SearchError

A search-related method was called when search was not enabled.

exception reader.InvalidSearchQueryError(message='')

Bases: SearchError, ValueError

The search query provided was somehow invalid.

exception reader.TagError(resource_id, key, /, message='')

Bases: ReaderError

A tag error occurred.

Changelog

Changed in version 3.0: Signature changed from TagError(key, resource_id, ...) to TagError(resource_id, key, ...).

Changed in version 3.0: The resource_id and key arguments are now positional-only.

Changed in version 2.17: Signature changed from TagError(key, object_id, ...) to TagError(key, resource_id, ...).

Added in version 2.8.

exception reader.TagNotFoundError(resource_id, key, /, message='')

Bases: TagError

Tag not found.

Changelog

Added in version 2.8.

exception reader.ResourceNotFoundError(message='')

Bases: ReaderError

Resource (feed, entry) not found.

Changelog

Added in version 2.8.

property resource_id: tuple[str, ...]

The resource_id of the resource.

exception reader.PluginError(message='')

Bases: ReaderError

A plugin-related exception.

exception reader.InvalidPluginError(message='')

Bases: PluginError, ValueError

An invalid plugin was provided.

Changelog

Added in version 1.16.

exception reader.PluginInitError(message='')

Bases: PluginError

A plugin failed to initialize.

The original exception should be chained to this one (e.__cause__).

Changelog

Added in version 3.0.

exception reader.ReaderWarning(message='')

Bases: ReaderError, UserWarning

Base for all warnings emitted by reader that are not DeprecationWarning.

Changelog

Changed in version 3.8: Inherit from ReaderError.

Added in version 2.13.

Exception hierarchy

The class hierarchy for reader exceptions is:

ReaderError
 ├── ReaderWarning [UserWarning]
 ├── ResourceNotFoundError
 ├── FeedError
 │    ├── FeedExistsError
 │    ├── FeedNotFoundError [ResourceNotFoundError]
 │    └── InvalidFeedURLError [ValueError]
 ├── EntryError
 │    ├── EntryExistsError
 │    └── EntryNotFoundError [ResourceNotFoundError]
 ├── UpdateError
 │    ├── ParseError [FeedError, ReaderWarning]
 │    └── UpdateHookError
 │         ├── SingleUpdateHookError
 │         └── UpdateHookErrorGroup [ExceptionGroup]
 ├── StorageError
 │    └── ChangeTrackingNotEnabledError
 ├── SearchError
 │    ├── SearchNotEnabledError
 │    └── InvalidSearchQueryError [ValueError]
 ├── PluginError
 │    ├── InvalidPluginError [ValueError]
 │    └── PluginInitError
 └── TagError
      └── TagNotFoundError

Enumerations

class reader.FeedSort(value)

Bases: StrEnum

How to order feeds.

Changelog

Added in version 3.18.

TITLE = 'title'

By resolved_title, case insensitive.

ADDED = 'added'

By added, last added first.

class reader.EntrySort(value)

Bases: StrEnum

How to order entries.

Changelog

Added in version 3.18.

RECENT = 'recent'

Most recent first. That is:

  • by published date for entries imported on the first update (if an entry does not have published, updated is used)

  • by added date for entries imported after that

This is to make sure newly imported entries appear at the top regardless of when the feed says they were published, while not having all the old entries at the top for new feeds.

Note

The algorithm for “recent” is a heuristic and may change over time.

Changelog

Changed in version 3.1: Sort entries by added date most of the time, with the exception of those imported on the first update. Previously, entries would be sorted by added only if they were published less than 7 days ago.

RANDOM = 'random'

Random (shuffle). Return at most 256 entries.

Changelog

Added in version 1.2.

class reader.EntrySearchSort(value)

Bases: StrEnum

How to order entry search results.

Changelog

Added in version 3.18.

RELEVANT = 'relevant'

Most relevant first.

RECENT = 'recent'

Most recent first. See EntrySort.RECENT for details.

Changelog

Added in version 1.4.

RANDOM = 'random'

Random (shuffle). See EntrySort.RANDOM for details.

Changelog

Added in version 1.10.

Type aliases

reader.types.TagFilterInput = None | bool | collections.abc.Sequence[str | bool | collections.abc.Sequence[str | bool]]

Possible values for filtering resources by their tags.

Tag filters consist of a list of one or more tags. Multiple tags are interpreted as a conjunction (AND). To use a disjunction (OR), use a nested list. To negate a tag, prefix the tag value with a minus sign (-). Examples:

['one']

one

['one', 'two'] [['one'], ['two']]

one AND two

[['one', 'two']]

one OR two

[['one', 'two'], 'three']

(one OR two) AND three

['one', '-two']

one AND NOT two

Special values True and False match resources with any tags and no tags, respectively.

True [True]

any tags

False [False]

no tags

[True, '-one']

any tags AND NOT one

[[False, 'one']]

no tags OR one

Changelog

Added in version 3.11.

reader.types.TristateFilterInput

Possible values for options that filter items by an optional boolean attribute (one that can be either true, false, or not set).

None selects all items. True and False select items based of the attribute’s truth value (a None attribute is treated as false).

For more precise filtering, use one of the following string filters:

attribute values

string filter

optional bool filter

True

istrue

True

False

isfalse

None

notset

False, None

nottrue

False

True, None

notfalse

True, False

isset

True, False, None

any

None
Changelog

Added in version 3.5.

alias of Literal[None, True, False, ‘istrue’, ‘isfalse’, ‘notset’, ‘nottrue’, ‘notfalse’, ‘isset’, ‘any’]

class reader.types.UpdateConfig

Schema for the .reader.update config tag that controls scheduled updates (see Reserved names for details on the key prefix).

Individual config keys may be missing; per-feed values override global values override default values. Invalid values are silently treated as missing. The default config is:

{'interval': 60, 'jitter': 0}

For example, given:

>>> reader.set_tag((), '.reader.update', {'interval': 120})
>>> reader.set_tag('http://example.com/feed', '.reader.update', {'jitter': 100})

…the config for http://example.com/feed ends up being:

{
    # no per-feed value; fall back to global value
    'interval' 120,
    # invalid feed value (100 not between 0.0 and 1.0);
    # no global value; fall back to default value
    'jitter': 0,
}
Changelog

Added in version 3.13.

interval: int

Update interval, in minutes.

jitter: float

Update jitter, as a ratio of interval, between 0.0 and 1.0.

Constants

reader.core.DEFAULT_RESERVED_NAME_SCHEME = {'plugin_prefix': '.plugin.', 'reader_prefix': '.reader.', 'separator': '.'}

The make_reader() default reserved name scheme.

reader.plugins.DEFAULT_PLUGINS = ['reader.ua_fallback']

The make_reader() default list of plugins.

Utilities

reader.utils.archive_entries(reader, entries, /, feed_url='reader:archived', feed_user_title='Archived')

Copy a list of entries to a special “archived” feed.

Entries that are already in the archived feed will be overwritten.

The original entries will remain unchanged.

Parameters:

  • reader (Reader) – A reader instance.

  • entries (list(tuple(str, str) or Entry)) – Entries to be archived.

  • feed_url (str) – The URL of the archived feed. If the feed does not exist, it will be created.

  • feed_user_title (str or None) – user_title for the archived feed.

Raises:
Changelog

Added in version 3.16.