API reference
This part of the documentation covers all the interfaces of reader.
Reader object
Most of reader’s functionality can be accessed through a Reader
instance.
- reader.make_reader(url, *, feed_root='', plugins=..., session_timeout=(3.05, 60), reserved_name_scheme=..., search_enabled='auto')
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
, andfile:/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 URLsfeed.xml
andfile:feed.xml
correspond to/feeds/feed.xml
./feed.xml
andfile:/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).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
. The prefixes default to.reader.
/.plugin.
, and the separator to.
search_enabled (bool or None or
'auto'
) – Whether to enable search. One of'auto'
(enable on the firstupdate_search()
call; default),True
(enable),False
(disable),None
(do nothing).
- Returns
The reader.
- Return type
- Raises
StorageError – An error occurred while connecting to storage.
SearchError – An error occurred while enabling/disabling search.
InvalidPluginError – An invalid plugin name was passed to
plugins
.ReaderError – An ambiguous exception occurred while creating the reader.
Changelog
New 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), usesearch_enabled=None
.Changed in version 2.0:
feed_root
now defaults toNone
(don’t open local feeds) instead of''
(full filesystem access).New in version 1.17: The
reserved_name_scheme
keyword argument.New in version 1.16: The
plugins
keyword argument. Using an invalid plugin name raisesInvalidPluginError
, aValueError
subclass.New 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.New 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:
Atom (provided by feedparser)
RSS (provided by feedparser)
JSON Feed
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.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.
Changelog
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.
New in version 1.13: JSON Feed support.
- after_entry_update_hooks
List of functions called for each updated entry after the feed is updated.
Each function is called with:
reader – the
Reader
instanceentry – an
Entry
-like objectstatus – an
EntryUpdateStatus
value
Each function should return
None
.Warning
The only entry attributes guaranteed to be present are
feed_url
,id
, andobject_id
; all other attributes may be missing (accessing them may raiseAttributeError
).Changelog
New in version 1.20.
- before_feed_update_hooks
List of functions called for each updated feed before the feed is updated.
Each function is called with:
Each function should return
None
.Changelog
New in version 2.7.
- after_feed_update_hooks
List of functions called for each updated feed after the feed is updated.
Each function is called with:
Each function should return
None
.Changelog
New in version 2.2.
- before_feeds_update_hooks
List of functions called once before updating any feeds, at the beginning of
update_feeds()
/update_feeds_iter()
, but notupdate_feed()
.Each function is called with:
reader – the
Reader
instance
Each function should return
None
.Changelog
New in version 2.12.
- after_feeds_update_hooks
List of functions called once after updating all feeds, at the end of
update_feeds()
/update_feeds_iter()
, but notupdate_feed()
.Each function is called with:
reader – the
Reader
instance
Each function should return
None
.Changelog
New in version 2.12.
- 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
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
- Raises
FeedExistsError – If the feed already exists, and exist_ok is false.
InvalidFeedURLError – If
feed
is invalid andallow_invalid_url
is false.
Changelog
New in version 2.8: The
exist_ok
argument.New 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, metadata, and tags.
- Parameters
- Raises
FeedNotFoundError – If the feed does not exist, and missing_ok is false.
Changelog
New in version 2.8: The
missing_ok
argument.New 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
(exceptupdated
andversion
, which get set to None). All other feed attributes are set to their default values.The entries, tags and metadata are preserved.
- Parameters
- Raises
FeedNotFoundError – If
old
does not exist.FeedExistsError – If
new
already exists.InvalidFeedURLError – If
new
is invalid andallow_invalid_url
is false.
Changelog
New 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
.New in version 1.8.
- get_feeds(*, feed=None, tags=None, broken=None, updates_enabled=None, new=None, sort='title', limit=None, starting_after=None)
Get all or some of the feeds.
The
tags
argument can be a list of one or more feed 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
andFalse
match feeds 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
- 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.
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.
sort (str) – How to order feeds; one of
'title'
(byuser_title
ortitle
, case insensitive; default), or'added'
(last added first).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 tosort
.- Raises
FeedNotFoundError – If
starting_after
does not exist.
Changelog
New in version 2.6: The
new
keyword argument.New in version 1.12: The
limit
andstarting_after
keyword arguments.New in version 1.11: The
updates_enabled
keyword argument.New in version 1.7: The
tags
keyword argument.New in version 1.7: The
broken
keyword argument.
- get_feed(feed, default=no value)
Get a feed.
Like
next(iter(reader.get_feeds(feed=feed)))
, but raises a custom exception instead ofStopIteration
.- Parameters
- Returns
The feed.
- Return type
- Raises
- get_feed_counts(*, feed=None, tags=None, broken=None, updates_enabled=None, new=None)
Count all or some of the feeds.
See
get_feeds()
for details on how filtering works.- 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.
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.
- Return type
- Raises
Changelog
New in version 2.6: The
new
keyword argument.New in version 1.11.
- set_feed_user_title(feed, title)
Set a user-defined title for a feed.
- Parameters
- Raises
- enable_feed_updates(feed)
Enable updates for a feed.
See
update_feeds()
for details.- Parameters
- Raises
Changelog
New in version 1.11.
- disable_feed_updates(feed)
Disable updates for a feed.
See
update_feeds()
for details.- Parameters
- Raises
Changelog
New in version 1.11.
- update_feeds(*, feed=None, tags=None, broken=None, updates_enabled=True, new=None, workers=1)
Update all or some of the feeds.
Silently skip feeds that raise
ParseError
.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.
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.
workers (int) – Number of threads to use when getting the feeds.
- Raises
Changelog
New in version 2.6: The
feed
,tags
,broken
, andupdates_enabled
keyword arguments.Changed in version 2.0: Removed the
new_only
parameter.Changed in version 2.0: All parameters are keyword-only.
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, workers=1, _call_feeds_update_hooks=True)
Update all or some of the feeds.
Yield information about each updated feed.
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.
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.
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 is always a
ParseError
, but otherReaderError
subclasses may be yielded in the future.- Raises
Changelog
New in version 2.6: The
feed
,tags
,broken
, andupdates_enabled
keyword arguments.Changed in version 2.0: Removed the
new_only
parameter.Changed in version 2.0: All parameters are keyword-only.
Changed in version 1.15: Update entries whenever their content changes. See
update_feeds()
for details.New in version 1.14.
- update_feed(feed)
Update a single feed.
The feed will be updated even if updates are disabled for it.
Like
next(iter(reader.update_feeds_iter(feed=feed, updates_enabled=None)))[1]
, but raises theParseError
, if any.- Parameters
- 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 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, feed_tags=None, sort='recent', limit=None, starting_after=None)
Get all or some of the entries.
Entries are sorted according to
sort
. Possible values:'recent'
Most recent first. Currently, that means:
by import date for entries published less than 7 days ago
by published date otherwise (if an entry does not have
published
,updated
is used)
This is to make sure newly imported entries appear at the top regardless of when the feed says they were published (sometimes, it lies by a day or two).
Note
The algorithm for “recent” is a heuristic and may change over time.
'random'
Random order (shuffled). At at most 256 entries will be returned.
Changelog
New in version 1.2.
- 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) – Only return (un)important entries.
has_enclosures (bool or None) – Only return entries that (don’t) have enclosures.
feed_tags (None or bool or list(str or bool or list(str or bool))) – Only return the entries from feeds matching these tags; works like the
get_feeds()
tags
argument.sort (str) – How to order entries; one of
'recent'
(default) or'random'
.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
withsort='random'
is not supported.
- Yields
Entry
– Sorted according tosort
.- Raises
EntryNotFoundError – If
starting_after
does not exist.
Changelog
New in version 1.12: The
limit
andstarting_after
keyword arguments.New in version 1.7: The
feed_tags
keyword argument.New in version 1.2: The
sort
keyword argument.
- get_entry(entry, default=no value)
Get an entry.
Like
next(iter(reader.get_entries(entry=entry)))
, but raises a custom exception instead ofStopIteration
.- Parameters
- Returns
The entry.
- Return type
- Raises
- get_entry_counts(*, feed=None, entry=None, read=None, important=None, has_enclosures=None, feed_tags=None)
Count all or some of the entries.
See
get_entries()
for details on how filtering works.- 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) – Only count (un)important entries.
has_enclosures (bool or None) – Only count entries that (don’t) have enclosures.
feed_tags (None or bool or list(str or bool or list(str or bool))) – Only count the entries from feeds matching these tags.
- Return type
- Raises
Changelog
New 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 (default), and as unread otherwise.
modified (datetime or None) – Set
read_modified
to this. Naive datetimes are normalized by passing them toastimezone()
. Defaults to the current time.
- Raises
Changelog
New in version 2.2.
- mark_entry_as_read(entry)
Mark an entry as read.
Alias for
set_entry_read(entry, True)
.Changelog
New 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)
.Changelog
New 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) – Mark the entry as important if true (default), and as unimportant otherwise.
modified (datetime or None) – Set
important_modified
to this. Naive datetimes are normalized by passing them toastimezone()
. Defaults to the current time.
- Raises
Changelog
New in version 2.2.
- mark_entry_as_important(entry)
Mark an entry as important.
Alias for
set_entry_important(entry, True)
.Changelog
New 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)
.Changelog
New in version 1.18: Renamed from
mark_as_unimportant()
.
- add_entry(entry)
Add a new entry to an existing feed.
entry
can be anyEntry
-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.
- Raises
EntryExistsError – If an entry with the same id already exists.
Changelog
New in version 2.5.
- delete_entry(entry, missing_ok=False)
Delete an entry.
Currently, only entries added by
add_entry()
(added_by
'user'
) can be deleted.- Parameters
- Raises
EntryNotFoundError – If the entry does not exist, and missing_ok is false.
EntryError – If the entry was not added by the user.
Changelog
New in version 2.8: The
missing_ok
argument.New in version 2.5.
- get_feed_metadata(feed, key=None)
Deprecated alias for
get_tags()
.Get all or some of the metadata for a feed as
(key, value)
pairs.- Parameters
- Yields
tuple(str, JSONType) –
(key, value)
pairs, in undefined order. JSONType is whateverjson.dumps()
accepts.- Raises
Deprecated since version 2.8: This method will be removed in reader 3.0. Use
get_tags()
instead.Changelog
Changed in version 2.0: The
get_feed_metadata(feed, key, default=no value, /)
(positional arguments only)get_feed_metadata_item()
alias was removed.Changed in version 1.18:
get_feed_metadata()
was renamed toget_feed_metadata_item()
,iter_feed_metadata()
was renamed toget_feed_metadata()
.
- get_feed_metadata_item(feed, key, default=no value)
Deprecated alias for
get_tag()
.Get metadata for a feed.
Like
next(iter(reader.get_feed_metadata(feed, key=key)), (None, default))[1]
, but raises a custom exception instead ofStopIteration
.- Parameters
- Returns
The metadata value. JSONType is whatever
json.dumps()
accepts.- Return type
JSONType
- Raises
Deprecated since version 2.8: This method will be removed in reader 3.0. Use
get_tag()
instead.Changelog
New in version 1.18: Renamed from
get_feed_metadata()
.
- set_feed_metadata_item(feed, key, value)
Deprecated alias for
set_tag()
.Set metadata for a feed.
- Parameters
- Raises
Deprecated since version 2.8: This method will be removed in reader 3.0. Use
set_tag()
instead.Changelog
New in version 1.18: Renamed from
set_feed_metadata()
.
- delete_feed_metadata_item(feed, key)
Deprecated alias for
delete_tag()
.Delete metadata for a feed.
- Parameters
- Raises
Deprecated since version 2.8: This method will be removed in reader 3.0. Use
delete_tag()
instead.Changelog
New in version 1.18: Renamed from
delete_feed_metadata()
.
- enable_search()
Enable full-text search.
Calling this method if search is already enabled is a no-op.
- Raises
- disable_search()
Disable full-text search.
Calling this method if search is already disabled is a no-op.
- Raises
- is_search_enabled()
Check if full-text search is enabled.
- Returns
Whether search is enabled or not.
- Return type
- Raises
- update_search()
Update the full-text search index.
Search must be enabled to call this method.
If
make_reader()
was called withsearch_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, feed_tags=None, sort='relevant', limit=None, starting_after=None)
Get entries matching a full-text search query.
Entries are sorted according to
sort
. Possible values:'relevant'
Most relevant first.
'recent'
Most recent first. See
get_entries()
for details on what recent means.Changelog
New in version 1.4.
'random'
Random order (shuffled). At at most 256 entries will be returned.
Changelog
New in version 1.10.
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 titlefeed
: the feed titlecontent
: 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”
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) – Only search (un)important entries.
has_enclosures (bool or None) – Only search entries that (don’t) have enclosures.
feed_tags (None or bool or list(str or bool or list(str or bool))) – Only return the entries from feeds matching these tags; works like the
get_feeds()
tags
argument.sort (str) – How to order results; one of
'relevant'
(default),'recent'
, or'random'
.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
withsort='random'
is not supported.
- Yields
EntrySearchResult
– Sorted according tosort
.- Raises
EntryNotFoundError – If
starting_after
does not exist.
Changelog
New in version 1.12: The
limit
andstarting_after
keyword arguments.New in version 1.7: The
feed_tags
keyword argument.New in version 1.4: The
sort
keyword argument.
- search_entry_counts(query, *, feed=None, entry=None, read=None, important=None, has_enclosures=None, feed_tags=None)
Count entries matching a full-text search query.
See
search_entries()
for details on how the query syntax and filtering work.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) – Only count (un)read entries.
important (bool or None) – Only count (un)important entries.
has_enclosures (bool or None) – Only count entries that (don’t) have enclosures.
feed_tags (None or bool or list(str or bool or list(str or bool))) – Only count the entries from feeds matching these tags.
- Return type
- Raises
Changelog
New in version 1.11.
- add_feed_tag(feed, tag)
Deprecated alias for
set_tag()
.Add a tag to a feed.
Adding a tag that the feed already has is a no-op.
- Parameters
- Raises
Deprecated since version 2.8: This method will be removed in reader 3.0. Use
set_tag()
instead.Changelog
New in version 1.7.
- remove_feed_tag(feed, tag)
Deprecated alias for
delete_tag()
.Remove a tag from a feed.
Removing a tag that the feed does not have is a no-op.
- Parameters
- Raises
Deprecated since version 2.8: This method will be removed in reader 3.0. Use
delete_tag()
instead.Changelog
New in version 1.7.
- get_feed_tags(feed=None)
Deprecated alias for
get_tag_keys()
.Get all or some of the feed tags.
- Parameters
feed (str or tuple(str) or Feed or None) – Only return the tags for this feed.
- Yields
str – The tags, in alphabetical order.
- Raises
Deprecated since version 2.8: This method will be removed in reader 3.0. Use
get_tag_keys()
instead.Changelog
New in version 1.7.
- 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
orstr
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 – The resource to get tags for.
key (str or None) – Only return the metadata for this key.
- Yields
tuple(str, JSONType) –
(key, value)
pairs, in undefined order. JSONType is whateverjson.dumps()
accepts.- Raises
Changelog
Changed in version 2.10: Support entry and global tags.
Changed in version 2.10: Removed support for the
(None,)
(any feed) andNone
(any resource) wildcard resource values.New 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 – Only return tag keys for this resource.
- Yields
str – The tag keys, in alphabetical order.
- Raises
Changelog
Changed in version 2.10: Support entry and global tags.
New in version 2.8.
- get_tag(resource, key, default=no value)
Get the value of this resource tag.
Like
next(iter(reader.get_tags(resource, key=key)))[1]
, but raises a custom exception instead ofStopIteration
.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 2.10: Support entry and global tags.
New in version 2.8.
- set_tag(resource, key, value=no value)
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 whateverjson.dumps()
accepts.
- Raises
Changelog
Changed in version 2.10: Support entry and global tags.
New in version 2.8.
- delete_tag(resource, key, missing_ok=False)
Delete this resource tag.
See
get_tags()
for possible resource values.- Parameters
resource – 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
TagNotFoundError – If the tag does not exist, and missing_ok is false.
Changelog
Changed in version 2.10: Support entry and global tags.
New in version 2.8.
- make_reader_reserved_name(key)
Create a reader-reserved tag or metadata 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'
Changelog
New in version 1.17.
- make_plugin_reserved_name(plugin_name, key=None)
Create a plugin-reserved tag or metadata name. See Reserved names for details.
Plugins should use this to generate names for plugin-specific tags and metadata.
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
- Returns
The name.
- Return type
Changelog
New in version 1.17.
- property reserved_name_scheme
Mapping used to build reserved names. See
make_reader_reserved_name()
andmake_plugin_reserved_name()
for details on how this is used.The default scheme (these keys are required):
{'reader_prefix': '.reader.', 'plugin_prefix': '.plugin.', 'separator': '.'}
The returned mapping is immutable; assign a new mapping to change the scheme.
Changelog
New in version 1.17.
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)
Data type representing a feed.
All
datetime
attributes are timezone-aware, with the timezone set toutc
.Changelog
Changed in version 2.0:
datetime
attributes are now timezone-aware; prior to 2.0, they were naive datetimes representing UTC times.- url
The URL of the feed.
- updated = None
The date the feed was last updated, according to the feed.
- title = None
The title of the feed.
- link = None
The URL of a page associated with the feed.
- author = None
The author of the feed.
- subtitle = None
A description or subtitle for the feed.
Changelog
New in version 2.4.
- version = None
The feed type and version.
For Atom and RSS, provided by feedparser (e.g.
atom10
,rss20
); full list.For JSON Feed:
json10
json11
json
JSON Feed (unknown or unrecognized version)
Plugins may add other versions.
Changelog
New in version 2.4.
- user_title = None
User-defined feed title.
- added = None
The date when the feed was added.
Changelog
New in version 1.3.
- last_updated = None
The date when the feed was last retrieved by reader.
Changelog
New in version 1.3.
- last_exception = None
If a
ParseError
happend during the last update, its cause.Changelog
New in version 1.3.
- updates_enabled = True
Whether updates are enabled for this feed.
Changelog
New in version 1.11.
- class reader.ExceptionInfo(type_name, value_str, traceback_str)
Data type representing information about an exception.
Changelog
New in version 1.3.
- type_name
The fully qualified name of the exception type.
- value_str
String representation of the exception value.
- traceback_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=(), read=False, read_modified=None, important=False, important_modified=None, added=None, added_by=None, last_updated=None, original_feed_url=None, feed=None)
Data type representing an entry.
All
datetime
attributes are timezone-aware, with the timezone set toutc
.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
The feed URL.
- id
The entry id.
- updated = 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; useupdated_not_none
for the pre-2.5 behavior.Changed in version 2.0: May be
None
in some cases. In a future version, will beNone
if missing in the feed; useupdated_not_none
for the pre-2.0 behavior.
- title = None
The title of the entry.
- link = None
The URL of a page associated with the entry.
- author = None
The author of the feed.
- published = None
The date the entry was published, according to the feed.
- summary = None
A summary of the entry.
- read = False
Whether the entry was read or not.
- read_modified = 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
New in version 2.2.
- important = False
Whether the entry is important or not.
- important_modified = 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
New in version 2.2.
- added = None
The date when the entry was added (first updated) to reader.
Changelog
New in version 2.5.
- added_by = None
The source of the entry. One of
'feed'
,'user'
.Other values may be added in the future.
Changelog
New in version 2.5.
- last_updated = None
The date when the entry was last updated by reader.
Changelog
New in version 1.3.
- original_feed_url = None
The URL of the original feed of the entry.
If the feed URL never changed, the same as
feed_url
.Changelog
New in version 1.8.
- feed = None
The entry’s feed.
- class reader.Content(value, type=None, language=None)
Data type representing a piece of content.
- value
The content value.
- type = None
The content type.
- language = None
The content language.
- property is_html
Whether the content is (X)HTML.
True if the content does not have a type.
Changelog
New in version 2.12.
- class reader.Enclosure(href, type=None, length=None)
Data type representing an external file.
- href
The file URL.
- type = None
The file content type.
- length = None
The file length.
- class reader.EntrySearchResult(feed_url, id, metadata=mappingproxy({}), content=mappingproxy({}))
Data type representing the result of an entry search.
metadata
andcontent
are dicts where the key is the path of an entry attribute, and the value is aHighlightedString
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
The feed URL.
- id
The entry id.
- metadata = mappingproxy({})
Matching entry metadata, in arbitrary order. Currently entry.title and entry.feed.user_title/.title.
- content = mappingproxy({})
Matching entry content, sorted by relevance. Any of entry.summary and entry.content[].value.
- class reader.HighlightedString(value='', highlights=())
A string that has some of its parts highlighted.
- value = ''
The underlying string.
- highlights = ()
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
- Returns
A highlighted string.
- Return type
- 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.
- class reader.FeedCounts(total=None, broken=None, updates_enabled=None)
Count information about feeds.
Changelog
New in version 1.11.
- total = None
Total number of feeds.
- broken = None
Number of broken feeds.
- updates_enabled = None
Number of feeds that have updates enabled.
- class reader.EntryCounts(total=None, read=None, important=None, has_enclosures=None, averages=None)
Count information about entries.
Changelog
New in version 1.11.
- total = None
Total number of entries.
- read = None
Number of read entries.
- important = None
Number of important entries.
- has_enclosures = None
Number of entries that have enclosures.
- averages = None
Average entries per day during the last 1, 3, 12 months, as a 3-tuple.
Changelog
New in version 2.1.
- class reader.EntrySearchCounts(total=None, read=None, important=None, has_enclosures=None, averages=None)
Count information about entry search results.
Changelog
New in version 1.11.
- total = None
Total number of entries.
- read = None
Number of read entries.
- important = None
Number of important entries.
- has_enclosures = None
Number of entries that have enclosures.
- averages = None
Average entries per day during the last 1, 3, 12 months, as a 3-tuple.
Changelog
New in version 2.1.
- class reader.UpdateResult(url, value)
Named tuple representing the result of a feed update.
Changelog
New in version 1.14.
- url
The URL of the feed.
- value
One of:
If the update was successful; a summary of the updated feed.
If the server indicated the feed has not changed since the last update without returning any data.
If there was an error while updating the feed.
- property updated_feed
The updated feed, if the update was successful,
None
otherwise.Changelog
New in version 2.1.
- property error
The exception, if there was an error,
None
otherwise.Changelog
New in version 2.1.
- property not_modified
True if the feed has not changed (either because the server returned no data, or because the data didn’t change), false otherwise.
Changelog
New in version 2.1.
- class reader.UpdatedFeed(url, new, modified)
The result of a successful feed update.
Changelog
Changed in version 1.19: The
updated
argument/attribute was renamed tomodified
.New in version 1.14.
- url
The URL of the feed.
- new
The number of new entries (entries that did not previously exist in storage).
- modified
The number of modified entries (entries that existed in storage, but had different data than the corresponding feed file entry.)
Exceptions
- exception reader.ReaderError(message='')
Base for all public exceptions.
- exception reader.FeedError(url, message='')
A feed error occurred.
Subclass of
ReaderError
.- url
The feed URL.
- exception reader.FeedExistsError(url, message='')
Feed already exists.
Subclass of
FeedError
.- message = 'feed exists'
Message; overridable.
- exception reader.FeedNotFoundError(url, message='')
Feed not found.
Subclass of
FeedError
andResourceNotFoundError
.- message = 'no such feed'
Message; overridable.
- exception reader.ParseError(url, message='')
An error occurred while getting/parsing feed.
The original exception should be chained to this one (e.__cause__).
Subclass of
FeedError
andReaderWarning
.
- exception reader.InvalidFeedURLError(url, message='')
Invalid feed URL.
Changelog
New in version 2.5.
Subclass of
FeedError
andValueError
.
- exception reader.EntryError(feed_url, id, message='')
An entry error occurred.
Changelog
Changed in version 1.18: The
url
argument/attribute was renamed tofeed_url
.Subclass of
ReaderError
.- feed_url
The feed URL.
- id
The entry id.
- exception reader.EntryExistsError(feed_url, id, message='')
Entry already exists.
Changelog
New in version 2.5.
Subclass of
EntryError
.- message = 'entry exists'
Message; overridable.
- exception reader.EntryNotFoundError(feed_url, id, message='')
Entry not found.
Subclass of
EntryError
andResourceNotFoundError
.- message = 'no such entry'
Message; overridable.
- exception reader.MetadataError(*args, key, **kwargs)
A metadata error occurred.
Deprecated since version 2.8: Will be removed in reader 3.0.
Changelog
Changed in version 1.18: Signature changed from
MetadataError(message='')
toMetadataError(key, message='')
.Subclass of
ReaderError
.- key
The metadata key.
- exception reader.MetadataNotFoundError(*args, key, **kwargs)
Metadata not found.
Deprecated since version 2.8: Will be removed in reader 3.0.
Changelog
Changed in version 1.18: Signature changed from
MetadataNotFoundError(url, key, message='')
toMetadataNotFoundError(key, message='')
.Subclass of
MetadataError
.- message = 'no such metadata'
Message; overridable.
- exception reader.FeedMetadataNotFoundError(url, key, message='')
Feed metadata not found.
Deprecated since version 2.8: Will be removed in reader 3.0.
Changelog
New in version 1.18.
Subclass of
MetadataNotFoundError
andFeedError
.
- exception reader.StorageError(message='')
An exception was raised by the underlying storage.
The original exception should be chained to this one (e.__cause__).
Subclass of
ReaderError
.
- exception reader.SearchError(message='')
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__).
Subclass of
ReaderError
.
- exception reader.SearchNotEnabledError(message='')
A search-related method was called when search was not enabled.
Subclass of
SearchError
.
- exception reader.InvalidSearchQueryError(message='')
The search query provided was somehow invalid.
Subclass of
SearchError
andValueError
.
- exception reader.TagError(key, object_id, message='')
A tag error occurred.
Changelog
New in version 2.8.
Subclass of
ReaderError
.- key
The tag key.
- object_id
The object_id of the resource.
- exception reader.TagNotFoundError(key, object_id, message='')
Tag not found.
Changelog
New in version 2.8.
Subclass of
TagError
.- message = 'no such tag'
Message; overridable.
- exception reader.ResourceNotFoundError(message='')
Resource (feed, entry) not found.
Changelog
New in version 2.8.
Subclass of
ReaderError
.
- exception reader.PluginError(message='')
A plugin-related exception.
Subclass of
ReaderError
.
- exception reader.InvalidPluginError(message='')
An invalid plugin was provided.
Changelog
New in version 1.16.
Subclass of
PluginError
andValueError
.
- exception reader.ReaderWarning
Base for all warnings emitted by reader. that are not
DeprecationWarning
.Changelog
New in version 2.13.
Subclass of
UserWarning
.
Constants
- reader.plugins.DEFAULT_PLUGINS = ['reader.ua_fallback']
The list of plugins
make_reader()
uses by default.