# 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("https://raw.githubusercontent.com/kurtmckee/listparser/main/feeds.opml")

`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'
    >>> result.meta.author.keys()
    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 <https://kurtmckee.org/tag/listparser/feed>
    listparser changelog <https://github.com/kurtmckee/listparser/commits/main.atom>

## 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.

See also

meta, feeds, lists, opportunities