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=...)

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), '' (full filesystem access; default), 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. The only plugin used by default is reader.ua_fallback.
  • 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) or None) – Value for reserved_name_scheme. The prefixes default to .reader./.plugin., and the separator to .
Returns:

The reader.

Return type:

Reader

Raises:

New in version 1.6: The feed_root keyword argument.

Changed in version 2.0: The default feed_root behavior will change from full filesystem access ('') to don’t open local feeds (None).

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.16: The plugins keyword argument. Using an invalid plugin name raises InvalidPluginError, a ValueError subclass.

New in version 1.17: The reserved_name_scheme 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:

Important

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

Important

The Reader object is not thread safe; its methods should be called only from the thread that created it.

To access the same database from multiple threads, create one instance in each thread. If you have a strong use case preventing you to do so, please +1 / comment in #206.

New in version 1.13: JSON Feed support.

close() → None

Close this Reader.

Releases any underlying resources associated with the reader.

The reader becomes unusable from this point forward; a ReaderError will be raised if any other method is called.

Raises:ReaderError
add_feed(feed: Union[str, reader.types.FeedLike]) → None

Add a new feed.

Feed updates are enabled by default.

Parameters:

feed (str or Feed) – The feed URL.

Raises:
remove_feed(feed: Union[str, reader.types.FeedLike]) → None

Remove a feed.

Also removes all of the feed’s entries, metadata, and tags.

Parameters:

feed (str or Feed) – The feed URL.

Raises:
change_feed_url(old: Union[str, reader.types.FeedLike], new: Union[str, reader.types.FeedLike]) → None

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 (except updated, which gets set to None). All other feed attributes are set to their default values.

The entries, tags and metadata are preserved.

Parameters:
  • old (str or Feed) – The old feed; must exist.
  • new (str or Feed) – The new feed; must not exist.
Raises:

New in version 1.8.

get_feeds(*, feed: Union[str, reader.types.FeedLike, None] = None, tags: Union[None, bool, Sequence[Union[str, bool, Sequence[Union[str, bool]]]]] = None, broken: Optional[bool] = None, updates_enabled: Optional[bool] = None, sort: typing_extensions.Literal['title', 'added'][title, added] = 'title', limit: Optional[int] = None, starting_after: Union[str, reader.types.FeedLike, None] = None) → Iterable[reader.types.Feed]

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 and False 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 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.
  • sort (str) – How to order feeds; one of 'title' (by user_title or title, 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 Feed or None) – Return feeds after this feed; a cursor for use in pagination.
Yields:

Feed – Sorted according to sort.

Raises:

New in version 1.7: The tags keyword argument.

New in version 1.7: The broken keyword argument.

New in version 1.11: The updates_enabled keyword argument.

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

get_feed(feed: Union[str, reader.types.FeedLike], default: Union[reader.types.MissingType, _T] = no value) → Union[reader.types.Feed, _T]

Get a feed.

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

Parameters:
  • feed (str or Feed) – The feed URL.
  • default – Returned if given and the feed does not exist.
Returns:

The feed.

Return type:

Feed

Raises:
get_feed_counts(*, feed: Union[str, reader.types.FeedLike, None] = None, tags: Union[None, bool, Sequence[Union[str, bool, Sequence[Union[str, bool]]]]] = None, broken: Optional[bool] = None, updates_enabled: Optional[bool] = None) → reader.types.FeedCounts

Count all or some of the feeds.

See get_feeds() for details on how filtering works.

Parameters:
  • feed (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.
Returns:

Return type:

FeedCounts

Raises:

StorageError

New in version 1.11.

set_feed_user_title(feed: Union[str, reader.types.FeedLike], title: Optional[str]) → None

Set a user-defined title for a feed.

Parameters:
  • feed (str or Feed) – The feed URL.
  • title (str or None) – The title, or None to remove the current title.
Raises:
enable_feed_updates(feed: Union[str, reader.types.FeedLike]) → None

Enable updates for a feed.

See update_feeds() for details.

Parameters:

feed (str or Feed) – The feed URL.

Raises:

New in version 1.11.

disable_feed_updates(feed: Union[str, reader.types.FeedLike]) → None

Disable updates for a feed.

See update_feeds() for details.

Parameters:

feed (str or Feed) – The feed URL.

Raises:

New in version 1.11.

update_feeds(new_only: bool = False, workers: int = 1) → None

Update all the feeds that have updates enabled.

Silently skip feeds that raise ParseError.

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

Parameters:
  • new_only (bool) – Only update feeds that have never been updated.
  • workers (int) – Number of threads to use when getting the feeds.
Raises:

StorageError

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

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.

update_feeds_iter(new_only: bool = False, workers: int = 1) → Iterable[reader.types.UpdateResult]

Update all the feeds that have updates enabled.

Parameters:
  • new_only (bool) – Only update feeds that have never been 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 is always a ParseError, but other ReaderError subclasses may be yielded in the future.

Raises:

StorageError

New in version 1.14.

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

update_feed(feed: Union[str, reader.types.FeedLike]) → Optional[reader.types.UpdatedFeed]

Update a single feed.

The feed will be updated even if updates are disabled for it.

Parameters:

feed (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:

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

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

get_entries(*, feed: Union[str, reader.types.FeedLike, None] = None, entry: Union[Tuple[str, str], reader.types.EntryLike, None] = None, read: Optional[bool] = None, important: Optional[bool] = None, has_enclosures: Optional[bool] = None, feed_tags: Union[None, bool, Sequence[Union[str, bool, Sequence[Union[str, bool]]]]] = None, sort: typing_extensions.Literal['recent', 'random'][recent, random] = 'recent', limit: Optional[int] = None, starting_after: Union[Tuple[str, str], reader.types.EntryLike, None] = None) → Iterable[reader.types.Entry]

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.

New in version 1.2.

Parameters:
  • feed (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 with sort='random' is not supported.
Yields:

Entry – Sorted according to sort.

Raises:

New in version 1.2: The sort keyword argument.

New in version 1.7: The feed_tags keyword argument.

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

get_entry(entry: Union[Tuple[str, str], reader.types.EntryLike], default: Union[reader.types.MissingType, _T] = no value) → Union[reader.types.Entry, _T]

Get an entry.

Like next(iter(reader.get_entries(entry=entry)), default), 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:
get_entry_counts(*, feed: Union[str, reader.types.FeedLike, None] = None, entry: Union[Tuple[str, str], reader.types.EntryLike, None] = None, read: Optional[bool] = None, important: Optional[bool] = None, has_enclosures: Optional[bool] = None, feed_tags: Union[None, bool, Sequence[Union[str, bool, Sequence[Union[str, bool]]]]] = None) → reader.types.EntryCounts

Count all or some of the entries.

See get_entries() for details on how filtering works.

Parameters:
  • feed (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.
Returns:

Return type:

EntryCounts

Raises:

StorageError

New in version 1.11.

mark_as_read(entry: Union[Tuple[str, str], reader.types.EntryLike]) → None

Mark an entry as read.

Parameters:

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

Raises:
mark_as_unread(entry: Union[Tuple[str, str], reader.types.EntryLike]) → None

Mark an entry as unread.

Parameters:

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

Raises:
mark_as_important(entry: Union[Tuple[str, str], reader.types.EntryLike]) → None

Mark an entry as important.

Parameters:

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

Raises:
mark_as_unimportant(entry: Union[Tuple[str, str], reader.types.EntryLike]) → None

Mark an entry as unimportant.

Parameters:

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

Raises:
iter_feed_metadata(feed: Union[str, reader.types.FeedLike], *, key: Optional[str] = None) → Iterable[Tuple[str, Union[Dict[str, Union[str, int, float, bool, None, Dict[str, Any], List[Any]]], List[Union[str, int, float, bool, None, Dict[str, Any], List[Any]]]]]]

Get all or some of the metadata values for a feed.

Parameters:
  • feed (str or Feed) – The feed URL.
  • key (str or None) – Only return the metadata for this key.
Yields:

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

Raises:

StorageError

get_feed_metadata(feed: Union[str, reader.types.FeedLike], key: str, default: Union[reader.types.MissingType, _T] = no value) → Union[Dict[str, Union[str, int, float, bool, None, Dict[str, Any], List[Any]]], List[Union[str, int, float, bool, None, Dict[str, Any], List[Any]]], _T]

Get metadata for a feed.

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

Parameters:
  • feed (str or Feed) – The feed URL.
  • key (str) – The key of the metadata to retrieve.
  • default – Returned if given and no metadata exists for key.
Returns:

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

Return type:

JSONType

Raises:
set_feed_metadata(feed: Union[str, reader.types.FeedLike], key: str, value: Union[Dict[str, Union[str, int, float, bool, None, Dict[str, Any], List[Any]]], List[Union[str, int, float, bool, None, Dict[str, Any], List[Any]]]]) → None

Set metadata for a feed.

Parameters:
  • feed (str or Feed) – The feed URL.
  • key (str) – The key of the metadata to set.
  • value (JSONType) – The value of the metadata to set. JSONType is whatever json.dumps() accepts.
Raises:
delete_feed_metadata(feed: Union[str, reader.types.FeedLike], key: str) → None

Delete metadata for a feed.

Parameters:
  • feed (str or Feed) – The feed URL.
  • key (str) – The key of the metadata to delete.
Raises:

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() → bool

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.

Raises:
search_entries(query: str, *, feed: Union[str, reader.types.FeedLike, None] = None, entry: Union[Tuple[str, str], reader.types.EntryLike, None] = None, read: Optional[bool] = None, important: Optional[bool] = None, has_enclosures: Optional[bool] = None, feed_tags: Union[None, bool, Sequence[Union[str, bool, Sequence[Union[str, bool]]]]] = None, sort: typing_extensions.Literal['relevant', 'recent', 'random'][relevant, recent, random] = 'relevant', limit: Optional[int] = None, starting_after: Union[Tuple[str, str], reader.types.EntryLike, None] = None) → Iterable[reader.types.EntrySearchResult]

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.

New in version 1.4.

'random'

Random order (shuffled). At at most 256 entries will be returned.

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 title
  • feed: the feed 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”

Search must be enabled to call this method.

Parameters:
  • query (str) – The search query.
  • feed (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 with sort='random' is not supported.
Yields:

EntrySearchResult – Sorted according to sort.

Raises:

New in version 1.4: The sort keyword argument.

New in version 1.7: The feed_tags keyword argument.

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

search_entry_counts(query: str, *, feed: Union[str, reader.types.FeedLike, None] = None, entry: Union[Tuple[str, str], reader.types.EntryLike, None] = None, read: Optional[bool] = None, important: Optional[bool] = None, has_enclosures: Optional[bool] = None, feed_tags: Union[None, bool, Sequence[Union[str, bool, Sequence[Union[str, bool]]]]] = None) → reader.types.EntrySearchCounts

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 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.
Returns:

Return type:

EntrySearchCounts

Raises:

New in version 1.11.

add_feed_tag(feed: Union[str, reader.types.FeedLike], tag: str) → None

Add a tag to a feed.

Adding a tag that the feed already has is a no-op.

Parameters:
  • feed (str or Feed) – The feed URL.
  • tag (str) – The tag to add.
Raises:

New in version 1.7.

remove_feed_tag(feed: Union[str, reader.types.FeedLike], tag: str) → None

Remove a tag from a feed.

Removing a tag that the feed does not have is a no-op.

Parameters:
  • feed (str or Feed) – The feed URL.
  • tag (str) – The tag to remove.
Raises:

StorageError

New in version 1.7.

get_feed_tags(feed: Union[str, reader.types.FeedLike, None] = None) → Iterable[str]

Get all or some of the feed tags.

Parameters:feed (str or Feed or None) – Only return the tags for this feed.
Yields:str – The tags, in alphabetical order.
Raises:StorageError

New in version 1.7.

make_reader_reserved_name(key: str) → str

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'
Parameters:key (str) – A key.
Returns:The name.
Return type:str

New in version 1.17.

make_plugin_reserved_name(plugin_name: str, key: Optional[str] = None) → str

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:
  • 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

New in version 1.17.

reserved_name_scheme

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 (these keys are required):

{'reader_prefix': '.reader.', 'plugin_prefix': '.plugin.', 'separator': '.'}

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

New in version 1.17.

Type:dict(str, str)

Data objects

class reader.Feed(url: str, updated: Optional[datetime.datetime] = None, title: Optional[str] = None, link: Optional[str] = None, author: Optional[str] = None, user_title: Optional[str] = None, added: datetime.datetime = None, last_updated: Optional[datetime.datetime] = None, last_exception: Optional[ExceptionInfo] = None, updates_enabled: bool = True)

Data type representing a feed.

All datetime attributes are timezone-naive, and always represent UTC.

url = None

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.

The URL of a page associated with the feed.

author = None

The author of the feed.

user_title = None

User-defined feed title.

added = None

The date when the feed was added.

New in version 1.3.

last_updated = None

The date when the feed was last retrieved by reader.

New in version 1.3.

last_exception = None

If a ParseError happend during the last update, its cause.

New in version 1.3.

updates_enabled = True

Whether updates are enabled for this feed.

New in version 1.11.

object_id

Alias for url.

New in version 1.12.

class reader.ExceptionInfo(type_name: str, value_str: str, traceback_str: str)

Data type representing information about an exception.

New in version 1.3.

type_name = None

The fully qualified name of the exception type.

value_str = None

String representation of the exception value.

traceback_str = None

String representation of the exception traceback.

class reader.Entry(id: str, updated: datetime.datetime, title: Optional[str] = None, link: Optional[str] = None, author: Optional[str] = None, published: Optional[datetime.datetime] = None, summary: Optional[str] = None, content: Sequence[Content] = (), enclosures: Sequence[Enclosure] = (), read: bool = False, important: bool = False, last_updated: datetime.datetime = None, original_feed_url: str = None, feed: reader.types.Feed = None)

Data type representing an entry.

All datetime attributes are timezone-naive, and always represent UTC.

feed_url

The feed URL.

id = None

The entry id.

updated = None

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

title = None

The title of the entry.

The URL of a page associated with the entry.

author = None

The author of the feed.

published = None

The date the entry was first published.

summary = None

A summary of the entry.

content = ()

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

enclosures = ()

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

read = False

Whether the entry was read or not.

important = False

Whether the entry is important or not.

last_updated = None

The date when the entry was last updated by reader.

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.

New in version 1.8.

feed = None

The entry’s feed.

object_id

Alias for (feed_url, id).

New in version 1.12.

class reader.Content(value: str, type: Optional[str] = None, language: Optional[str] = None)

Data type representing a piece of content.

value = None

The content value.

type = None

The content type.

language = None

The content language.

class reader.Enclosure(href: str, type: Optional[str] = None, length: Optional[int] = None)

Data type representing an external file.

href = None

The file URL.

type = None

The file content type.

length = None

The file length.

class reader.EntrySearchResult(feed_url: str, id: str, metadata: Mapping[str, reader.types.HighlightedString] = mappingproxy({}), content: Mapping[str, reader.types.HighlightedString] = mappingproxy({}))

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 = None

The feed URL.

id = None

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.

object_id

Alias for (feed_url, id).

New in version 1.12.

class reader.HighlightedString(value: str = '', highlights: Sequence[slice] = ())

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: str, before: str, after: str) → _HS

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() → Iterable[str]

Split the highlighted string into parts.

>>> list(HighlightedString('abcd', [slice(1, 3)]))
['a', 'bc', 'd']
Yields:str – The parts. Parts with even indexes are highlighted, parts with odd indexes are not.
apply(before: str, after: str, func: Optional[Callable[[str], str]] = None) → str

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: Optional[int] = None, broken: Optional[int] = None, updates_enabled: Optional[int] = None)

Count information about feeds.

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: Optional[int] = None, read: Optional[int] = None, important: Optional[int] = None, has_enclosures: Optional[int] = None)

Count information about entries.

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.

class reader.EntrySearchCounts(total: Optional[int] = None, read: Optional[int] = None, important: Optional[int] = None, has_enclosures: Optional[int] = None)

Count information about entry search results.

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.

class reader.UpdateResult

Named tuple representing the result of a feed update.

New in version 1.14.

url

The URL of the feed.

value

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.

ReaderError

If there was an error while updating the feed.
Type:One of
class reader.UpdatedFeed(url: str, new: int, updated: int)

The result of a successful feed update.

New in version 1.14.

url = None

The URL of the feed.

new = None

The number of new entries.

updated = None

The number of updated entries.

Exceptions

exception reader.ReaderError(message: str = '')

Base for all public exceptions.

exception reader.FeedError(url: str, message: str = '')

A feed error occured.

Subclass of ReaderError.

url = None

The feed URL.

object_id

Alias for url.

New in version 1.12.

exception reader.FeedExistsError(url: str, message: str = '')

Feed already exists.

Subclass of FeedError.

exception reader.FeedNotFoundError(url: str, message: str = '')

Feed not found.

Subclass of FeedError.

exception reader.ParseError(url: str, message: str = '')

An error occured while getting/parsing feed.

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

Subclass of FeedError.

exception reader.EntryError(url: str, id: str, message: str = '')

An entry error occured.

Subclass of ReaderError.

url = None

The feed URL.

id = None

The entry id.

object_id

Alias for (url, id).

New in version 1.12.

exception reader.EntryNotFoundError(url: str, id: str, message: str = '')

Entry not found.

Subclass of EntryError.

exception reader.MetadataError(url: str, key: str, message: str = '')

A feed metadata error occured.

Subclass of ReaderError.

url = None

The feed URL.

key = None

The metadata key.

exception reader.MetadataNotFoundError(url: str, key: str, message: str = '')

Feed metadata not found.

Subclass of MetadataError.

exception reader.StorageError(message: str = '')

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: str = '')

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: str = '')

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

Subclass of SearchError.

exception reader.InvalidSearchQueryError(message: str = '')

The search query provided was somehow invalid.

Subclass of SearchError and ValueError.

exception reader.PluginError(message: str = '')

A plugin-related exception.

Subclass of ReaderError.

exception reader.InvalidPluginError(message: str = '')

An invalid plugin was provided.

Subclass of PluginError and ValueError.