.\" Man page generated from reStructuredText.
.
.TH "PODCASTPARSER" "1" "Apr 22, 2018" "0.6.3" "podcastparser"
.SH NAME
podcastparser \- podcastparser Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
\fIpodcastparser\fP is a simple and fast podcast feed parser library in Python.
The two primary users of the library are the \fI\%gPodder Podcast Client\fP and
the \fI\%gpodder.net web service\fP\&.
.sp
The following feed types are supported:
.INDENT 0.0
.IP \(bu 2
Really Simple Syndication (\fI\%RSS 2.0\fP)
.IP \(bu 2
Atom Syndication Format (\fI\%RFC 4287\fP)
.UNINDENT
.sp
The following specifications are supported:
.INDENT 0.0
.IP \(bu 2
\fI\%Paged Feeds\fP (\fI\%RFC 5005\fP)
.IP \(bu 2
\fI\%Podlove Simple Chapters\fP
.UNINDENT
.sp
These formats only specify the possible markup elements and attributes. We
recommend that you also read the \fI\%Podcast Feed Best Practice\fP guide if you
want to optimize your feeds for best display in podcast clients.
.sp
Where times and durations are used, the values are expected to be formatted
either as seconds or as \fI\%RFC 2326\fP Normal Play Time (NPT).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
import podcastparser
import urllib

feedurl = \(aqhttp://example.com/feed.xml\(aq

parsed = podcastparser.parse(feedurl, urllib.urlopen(feedurl))

# parsed is a dict
import pprint
pprint.pprint(parsed)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For both RSS and Atom feeds, only a subset of elements (those that are relevant
to podcast client applications) is parsed. This section describes which elements
and attributes are parsed and how the contents are interpreted/used.
.SH RSS
.INDENT 0.0
.TP
\fBrss@xml:base\fP
Base URL for all relative links in the RSS file.
.TP
\fBrss/channel\fP
Podcast.
.TP
\fBrss/channel/title\fP
Podcast title (whitespace is squashed).
.TP
\fBrss/channel/link\fP
Podcast website.
.TP
\fBrss/channel/description\fP
Podcast description (whitespace is squashed).
.TP
\fBrss/channel/image/url\fP
Podcast cover art.
.TP
\fBrss/channel/itunes:image\fP
Podcast cover art (alternative).
.TP
\fBrss/channel/atom:link@rel=payment\fP
Podcast payment URL (e.g. Flattr).
.TP
\fBrss/channel/item\fP
Episode.
.TP
\fBrss/channel/item/guid\fP
Episode unique identifier (GUID), mandatory.
.TP
\fBrss/channel/item/title\fP
Episode title (whitespace is squashed).
.TP
\fBrss/channel/item/link\fP
Episode website.
.TP
\fBrss/channel/item/description\fP
Episode description (whitespace is squashed).
.TP
\fBrss/channel/item/itunes:subtitle\fP
Episode subtitled / one\-line description (whitespace is squashed).
.TP
\fBrss/channel/item/content:encoded\fP
Episode description in HTML.
.TP
\fBrss/channel/item/itunes:duration\fP
Episode duration.
.TP
\fBrss/channel/item/pubDate\fP
Episode publication date.
.TP
\fBrss/channel/item/atom:link@rel=payment\fP
Episode payment URL (e.g. Flattr).
.TP
\fBrss/channel/item/atom:link@rel=enclosure\fP
File download URL (@href), size (@length) and mime type (@type).
.TP
\fBrss/channel/item/media:content\fP
File download URL (@url), size (@fileSize) and mime type (@type).
.TP
\fBrss/channel/item/enclosure\fP
File download URL (@url), size (@length) and mime type (@type).
.TP
\fBrss/channel/item/psc:chapters\fP
Podlove Simple Chapters, version 1.1 and 1.2.
.TP
\fBrss/channel/item/psc:chapters/psc:chapter\fP
Chapter entry (@start, @title, @href and @image).
.UNINDENT
.SH ATOM
.sp
For Atom feeds, \fIpodcastparser\fP will handle the following elements and
attributes:
.INDENT 0.0
.TP
\fBatom:feed\fP
Podcast.
.TP
\fBatom:feed/atom:title\fP
Podcast title (whitespace is squashed).
.TP
\fBatom:feed/atom:subtitle\fP
Podcast description (whitespace is squashed).
.TP
\fBatom:feed/atom:icon\fP
Podcast cover art.
.TP
\fBatom:feed/atom:link@href\fP
Podcast website.
.TP
\fBatom:feed/atom:entry\fP
Episode.
.TP
\fBatom:feed/atom:entry/atom:id\fP
Episode unique identifier (GUID), mandatory.
.TP
\fBatom:feed/atom:entry/atom:title\fP
Episode title (whitespace is squashed).
.TP
\fBatom:feed/atom:entry/atom:link@rel=enclosure\fP
File download URL (@href), size (@length) and mime type (@type).
.TP
\fBatom:feed/atom:entry/atom:link@rel=(self|alternate)\fP
Episode website.
.TP
\fBatom:feed/atom:entry/atom:link@rel=payment\fP
Episode payment URL (e.g. Flattr).
.TP
\fBatom:feed/atom:entry/atom:content\fP
Episode description (in HTML or plaintext).
.TP
\fBatom:feed/atom:entry/atom:published\fP
Episode publication date.
.TP
\fBatom:feed/atom:entry/psc:chapters\fP
Podlove Simple Chapters, version 1.1 and 1.2.
.TP
\fBatom:feed/atom:entry/psc:chapters/psc:chapter\fP
Chapter entry (@start, @title, @href and @image).
.UNINDENT
.sp
Simplified, fast RSS parser
.INDENT 0.0
.TP
.B exception podcastparser.FeedParseError(msg, exception, locator)
Exception raised when asked to parse an invalid feed
.sp
This exception allows users of this library to catch exceptions
without having to import the XML parsing library themselves.
.UNINDENT
.INDENT 0.0
.TP
.B class podcastparser.PodcastHandler(url, max_episodes)
.INDENT 7.0
.TP
.B characters(chars)
Receive notification of character data.
.sp
The Parser will call this method to report each chunk of
character data. SAX parsers may return all contiguous
character data in a single chunk, or they may split it into
several chunks; however, all of the characters in any single
event must come from the same external entity so that the
Locator provides useful information.
.UNINDENT
.INDENT 7.0
.TP
.B endElement(name)
Signals the end of an element in non\-namespace mode.
.sp
The name parameter contains the name of the element type, just
as with the startElement event.
.UNINDENT
.INDENT 7.0
.TP
.B startElement(name, attrs)
Signals the start of an element in non\-namespace mode.
.sp
The name parameter contains the raw XML 1.0 name of the
element type as a string and the attrs parameter holds an
instance of the Attributes class containing the attributes of
the element.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.file_basename_no_extension(filename)
Returns filename without extension
.sp
.nf
.ft C
>>> file_basename_no_extension(\(aq/home/me/file.txt\(aq)
\(aqfile\(aq
.ft P
.fi
.sp
.nf
.ft C
>>> file_basename_no_extension(\(aqfile\(aq)
\(aqfile\(aq
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.is_html(text)
Tests whether the given string contains HTML encoded data
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.normalize_feed_url(url)
Normalize and convert a URL. If the URL cannot be converted
(invalid or unknown scheme), None is returned.
.sp
This will also normalize \fI\%feed://\fP and itpc:// to http://.
.sp
.nf
.ft C
>>> normalize_feed_url(\(aqitpc://example.org/podcast.rss\(aq)
\(aqhttp://example.org/podcast.rss\(aq
.ft P
.fi
.sp
If no URL scheme is defined (e.g. “curry.com”), we will
simply assume the user intends to add a \fI\%http://\fP feed.
.sp
.nf
.ft C
>>> normalize_feed_url(\(aqcurry.com\(aq)
\(aqhttp://curry.com/\(aq
.ft P
.fi
.sp
It will also take care of converting the domain name to
all\-lowercase (because domains are not case sensitive):
.sp
.nf
.ft C
>>> normalize_feed_url(\(aqhttp://Example.COM/\(aq)
\(aqhttp://example.com/\(aq
.ft P
.fi
.sp
Some other minimalistic changes are also taken care of,
e.g. a ? with an empty query is removed:
.sp
.nf
.ft C
>>> normalize_feed_url(\(aqhttp://example.org/test?\(aq)
\(aqhttp://example.org/test\(aq
.ft P
.fi
.sp
Leading and trailing whitespace is removed
.sp
.nf
.ft C
>>> normalize_feed_url(\(aq http://example.com/podcast.rss \(aq)
\(aqhttp://example.com/podcast.rss\(aq
.ft P
.fi
.sp
Incomplete (too short) URLs are not accepted
.sp
.nf
.ft C
>>> normalize_feed_url(\(aqhttp://\(aq) is None
True
.ft P
.fi
.sp
Unknown protocols are not accepted
.sp
.nf
.ft C
>>> normalize_feed_url(\(aqgopher://gopher.hprc.utoronto.ca/file.txt\(aq) is None
True
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.parse(url, stream, max_episodes=0)
Parse a podcast feed from the given URL and stream
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBurl\fP – the URL of the feed. Will be used to resolve relative links
.IP \(bu 2
\fBstream\fP – file\-like object containing the feed content
.IP \(bu 2
\fBmax_episodes\fP – maximum number of episodes to return. 0 (default)
means no limit
.UNINDENT
.TP
.B Returns
a dict with the parsed contents of the feed
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.parse_length(text)
Parses a file length
.sp
.nf
.ft C
>>> parse_length(None)
\-1
.ft P
.fi
.sp
.nf
.ft C
>>> parse_length(\(aq0\(aq)
\-1
.ft P
.fi
.sp
.nf
.ft C
>>> parse_length(\(aqunknown\(aq)
\-1
.ft P
.fi
.sp
.nf
.ft C
>>> parse_length(\(aq100\(aq)
100
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.parse_pubdate(text)
Parse a date string into a Unix timestamp
.sp
.nf
.ft C
>>> parse_pubdate(\(aqFri, 21 Nov 1997 09:55:06 \-0600\(aq)
880127706
.ft P
.fi
.sp
.nf
.ft C
>>> parse_pubdate(\(aq2003\-12\-13T00:00:00+02:00\(aq)
1071266400
.ft P
.fi
.sp
.nf
.ft C
>>> parse_pubdate(\(aq2003\-12\-13T18:30:02Z\(aq)
1071340202
.ft P
.fi
.sp
.nf
.ft C
>>> parse_pubdate(\(aqMon, 02 May 1960 09:05:01 +0100\(aq)
\-305049299
.ft P
.fi
.sp
.nf
.ft C
>>> parse_pubdate(\(aq\(aq)
0
.ft P
.fi
.sp
.nf
.ft C
>>> parse_pubdate(\(aqunknown\(aq)
0
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.parse_time(value)
Parse a time string into seconds
.sp
See RFC2326, 3.6 “Normal Play Time” (HH:MM:SS.FRACT)
.sp
.nf
.ft C
>>> parse_time(\(aq0\(aq)
0
>>> parse_time(\(aq128\(aq)
128
>>> parse_time(\(aq00:00\(aq)
0
>>> parse_time(\(aq00:00:00\(aq)
0
>>> parse_time(\(aq00:20\(aq)
20
>>> parse_time(\(aq00:00:20\(aq)
20
>>> parse_time(\(aq01:00:00\(aq)
3600
>>> parse_time(\(aq 03:02:01\(aq)
10921
>>> parse_time(\(aq61:08\(aq)
3668
>>> parse_time(\(aq25:03:30 \(aq)
90210
>>> parse_time(\(aq25:3:30\(aq)
90210
>>> parse_time(\(aq61.08\(aq)
61
>>> parse_time(\(aq01:02:03.500\(aq)
3723
>>> parse_time(\(aq \(aq)
0
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.parse_type(text)
“normalize” a mime type
.sp
.nf
.ft C
>>> parse_type(\(aqtext/plain\(aq)
\(aqtext/plain\(aq
.ft P
.fi
.sp
.nf
.ft C
>>> parse_type(\(aqtext\(aq)
\(aqapplication/octet\-stream\(aq
.ft P
.fi
.sp
.nf
.ft C
>>> parse_type(\(aq\(aq)
\(aqapplication/octet\-stream\(aq
.ft P
.fi
.sp
.nf
.ft C
>>> parse_type(None)
\(aqapplication/octet\-stream\(aq
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.remove_html_tags(html)
Remove HTML tags from a string and replace numeric and
named entities with the corresponding character, so the
HTML text can be displayed in a simple text view.
.UNINDENT
.INDENT 0.0
.TP
.B podcastparser.squash_whitespace(text)
Combine multiple whitespaces into one, trim trailing/leading spaces
.sp
.nf
.ft C
>>> squash_whitespace(\(aq some           text  with a    lot of   spaces \(aq)
\(aqsome text with a lot of spaces\(aq
.ft P
.fi
.UNINDENT
.sp
This is a list of podcast\-related XML namespaces that are not yet
supported by podcastparser, but might be in the future.
.SH CHAPTER MARKS
.INDENT 0.0
.IP \(bu 2
\fI\%rawvoice RSS\fP: Rating, Frequency, Poster, WebM, MP4, Metamark (kind of chapter\-like markers)
.IP \(bu 2
\fI\%IGOR\fP: Chapter Marks
.UNINDENT
.SH OTHERS
.INDENT 0.0
.IP \(bu 2
\fI\%libSYN RSS Extensions\fP: contactPhone, contactEmail, contactTwitter, contactWebsite, wallpaper, pdf, background
.IP \(bu 2
\fI\%Comment API\fP: Comments to a given item (readable via RSS)
.IP \(bu 2
\fI\%MVCB\fP: Error Reports To Field (usually a mailto: link)
.IP \(bu 2
\fI\%Syndication Module\fP: Update period, frequency and base (for skipping updates)
.IP \(bu 2
\fI\%Creative Commons RSS\fP: Creative commons license for the content
.IP \(bu 2
\fI\%Pheedo\fP: Original link to website and original link to enclosure (without going through pheedo redirect)
.IP \(bu 2
\fI\%WGS84\fP: Geo\-Coordinates per item
.IP \(bu 2
\fI\%Conversations Network\fP: Intro duration in milliseconds (for skipping the intro), ratings
.IP \(bu 2
\fI\%purl DC Elements\fP: dc:creator (author / creator of the podcast, possibly with e\-mail address)
.IP \(bu 2
\fI\%Tristana\fP: tristana:self (canonical URL to feed)
.IP \(bu 2
\fI\%Blip\fP: Show name, show page, picture, username, language, rating, thumbnail_src, license
.UNINDENT
.INDENT 0.0
.IP \(bu 2
genindex
.IP \(bu 2
modindex
.IP \(bu 2
search
.UNINDENT
.SH AUTHOR
gPodder Team
.SH COPYRIGHT
2018, gPodder Team
.\" Generated by docutils manpage writer.
.