Getting started

Use pip to install listparser.

To support retrieving and parsing of URL’s, add [http] to the command so the requests package will be installed as well.

To parse broken XML, add [lxml] to the command so the lxml package will be installed as well.

python -m pip install listparser[http,lxml]

You don’t have to install lxml or requests but it will reduce listparser’s functionality.

listparser has a single public function, parse().

>>> import listparser
>>> result = listparser.parse("")

parse() can be given a URL, an open file handle, or even an in-memory string.

The dictionary that parse() returns will contain several important keys.

The meta key

The meta key contains a dictionary of information about the subscription list, including its title, when it was created and last modified, and who maintains the subscription list.

>>> result.meta.title
'listparser project feeds'
dict_keys(['name', 'email', 'url'])

The feeds key

The feeds key is a list of dictionaries. The title and the URL are stored in keys of the same names.

>>> for feed in result.feeds:
...     print(f"{feed.title} <{feed.url}>")
listparser blog <>
listparser changelog <>

The lists key

OPML subscription lists can point to other subscription lists as easily as they can point to feeds. These subscription lists are placed in the lists key, and have the same title and URL information that feeds do.

The opportunities key

Several subscription list formats can contain not just a feed URL but the feed’s homepage URL as well. Some software butchers the OPML or RDF+FOAF file creation and outputs only the feed’s homepage URL.

When listparser encounters a homepage URL without a corresponding feed URL, it puts that information into the opportunities key. Opportunities contain the same title and URL information as feeds do, but remember that the URLs are expected to point to a homepage. It is therefore expected that feed readers using listparser will have to run feed and subscription list autodiscovery software against the list of opportunity URLs.