reader

reader is a Python feed reader library.

It is designed to allow writing feed reader applications without any business code, and without depending on a particular framework; in MVC terms, you’d probably call it a fat model.

Features

reader allows you to:

  • retrieve, store, and manage Atom, RSS, and JSON feeds

  • mark articles as read or important

  • add arbitrary tags/metadata to feeds and articles

  • filter feeds and articles

  • full-text search articles

  • get statistics on feed and user activity

  • import / export feeds as OPML

  • write plugins to extend its functionality

  • skip all the low level stuff and focus on what makes your feed reader different

…all these with:

  • a stable, clearly documented API

  • excellent test coverage

  • fully typed Python

What reader doesn’t do:

  • depend on a web framework

  • have an opinion of how or where you use it

In addition, reader provides:

  • an optional web application based on Flask, Bootstrap, and htmx

  • an optional command-line interface

Quickstart

What does it look like? Here is an example of reader in use:

$ pip install reader

>>> from reader import make_reader
>>>
>>> reader = make_reader('db.sqlite')
>>> reader.add_feed('http://www.hellointernet.fm/podcast?format=rss')
>>> reader.update_feeds()
>>>
>>> entries = list(reader.get_entries())
>>> [e.title for e in entries]
['H.I. #108: Project Cyclops', 'H.I. #107: One Year of Weird', ...]
>>>
>>> reader.mark_entry_as_read(entries[0])
>>>
>>> [e.title for e in reader.get_entries(read=False)]
['H.I. #107: One Year of Weird', 'H.I. #106: Water on Mars', ...]
>>> [e.title for e in reader.get_entries(read=True)]
['H.I. #108: Project Cyclops']
>>>
>>> reader.update_search()
>>>
>>> for e in reader.search_entries('year', limit=3):
...     title = e.metadata.get('.title')
...     print(title.value, title.highlights)
...
H.I. #107: One Year of Weird (slice(15, 19, None),)
H.I. #52: 20,000 Years of Torment (slice(17, 22, None),)
H.I. #83: The Best Kind of Prison ()

User guide

This part of the documentation guides you through all of the library’s usage patterns.

API reference

If you are looking for information on a specific function, class, or method, this part of the documentation is for you.

Unstable features

The following are optional features that are still being worked on. They may become their own packages, get merged into the main library, or be removed in the future.

Project information

reader is released under the BSD license, its documentation lives at Read the Docs, the code on GitHub, and the latest release on PyPI. It is rigorously tested on Python 3.11+ and PyPy.

Indices and tables