1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
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.
.. code-block:: shell
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, :py:func:`~listparser.parse`.
.. code-block:: pycon
>>> import listparser
>>> result = listparser.parse("https://raw.githubusercontent.com/kurtmckee/listparser/main/feeds.opml")
:py:func:`~listparser.parse` can be given a URL, an open file handle,
or even an in-memory string.
The dictionary that :py:func:`~listparser.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.
.. code-block:: pycon
>>> 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.
.. code-block:: pycon
>>> 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.
.. seealso::
:doc:`reference/meta`,
:doc:`reference/feeds`,
:doc:`reference/lists`,
:doc:`reference/opportunities`
|
