podgen.Episode¶
-
class
podgen.
Episode
(**kwargs)[source]¶ Class representing an episode in a podcast. Corresponds to an RSS Item.
When creating a new Episode, you can populate any attribute using keyword arguments. Use the attribute’s name on the left side of the equals sign and its value on the right side. Here’s an example:
>>> # This... >>> ep = Episode() >>> ep.title = "Exploring the RTS genre" >>> ep.summary = "Tory and I talk about a genre of games we've " + \ ... "never dared try out before now..." >>> # ...is equal to this: >>> ep = Episode( ... title="Exploring the RTS genre", ... summary="Tory and I talk about a genre of games we've " ... "never dared try out before now..." ... )
Raises: TypeError if you try to set an attribute which doesn’t exist, ValueError if you set an attribute to an invalid value. You must have filled in either
title
orsummary
before the RSS can be generated.To add an episode to a podcast:
>>> import podgen >>> p = podgen.Podcast() >>> episode = podgen.Episode() >>> p.episodes.append(episode)
You may also replace the last two lines with a shortcut:
>>> episode = p.add_episode(podgen.Episode())
See also
- Episodes
- A friendlier introduction to episodes.
List of
Person
that contributed to this episode.The authors don’t need to have both name and email set. They’re usually not displayed anywhere.
Note
You do not need to provide any authors for an episode if they’re identical to the podcast’s authors.
Any value you assign to authors will be automatically converted to a list, but only if it’s iterable (like tuple, set and so on). It is an error to assign a single
Person
object to this attribute:>>> # This results in an error >>> ep.authors = Person("John Doe", "johndoe@example.org") TypeError: Only iterable types can be assigned to authors, ... >>> # This is the correct way: >>> ep.authors = [Person("John Doe", "johndoe@example.org")]
The initial value is an empty list, so you can use the list methods right away.
Example:
>>> # This attribute is just a list - you can for example append: >>> ep.authors.append(Person("John Doe", "johndoe@example.org")) >>> # Or assign a new list (discarding earlier authors) >>> ep.authors = [Person("John Doe", "johndoe@example.org"), ... Person("Mary Sue", "marysue@example.org")]
Type: list
ofpodgen.Person
RSS: author or dc:creator, and itunes:author
-
explicit
¶ Whether this podcast episode contains material which may be inappropriate for children.
The value of the podcast’s explicit attribute is used by default, if this is kept as
None
.If you set this to
True
, an “explicit” parental advisory graphic will appear in the Name column in iTunes. If the value isFalse
, the parental advisory type is considered Clean, meaning that no explicit language or adult content is included anywhere in this episode, and a “clean” graphic will appear.Type: bool
RSS: itunes:explicit
-
id
= None¶ This episode’s globally unique identifier.
If not present, the URL of the enclosed media is used. This is usually the best way to go, as long as the media URL doesn’t change.
Set the id to boolean
False
if you don’t want to associate any id to this episode.It is important that an episode keeps the same ID until the end of time, since the ID is used by clients to identify which episodes have been listened to, which episodes are new, and so on. Changing the ID causes the same consequences as deleting the existing episode and adding a new, identical episode.
Note that this is a GLOBALLY unique identifier. Thus, not only must it be unique in this podcast, it must not be the same ID as any other episode for any podcast out there. To ensure this, you should use a domain which you own (for example, use something like http://example.org/podcast/episode1 if you own example.org).
Type: str
,None
to use default orFalse
to leave out.RSS: guid
-
image
¶ The podcast episode’s image, overriding the podcast’s
image
.This attribute specifies the absolute URL to the artwork for your podcast. iTunes prefers square images that are at least
1400x1400
pixels.iTunes supports images in JPEG and PNG formats with an RGB color space (CMYK is not supported). The URL must end in “.jpg” or “.png”; a
NotSupportedByItunesWarning
will be issued if it doesn’t.Type: str
RSS: itunes:image Note
If you change an episode’s image, you should also change the file’s name; iTunes doesn’t check the actual file to see if it’s changed.
Additionally, the server hosting your cover art image must allow HTTP HEAD requests.
Warning
Almost no podcatchers support this. iTunes supports it only if you embed the cover in the media file (the same way you would embed an album cover), and recommends that you use Garageband’s Enhanced Podcast feature.
The podcast’s image is used if this isn’t supported.
Whether this podcast includes a video episode with embedded closed captioning support. Defaults to
False
.Type: bool
RSS: itunes:isClosedCaptioned
-
link
= None¶ The link to the full version of this episode’s
summary
. Remember to start the link with the scheme, e.g. https://.Type: str
RSS: link
-
long_summary
= None¶ A long (read: full) summary, which supplements the shorter
summary
. Like summary, this must be compatible with XHTML parsers; usepodgen.htmlencode()
if this isn’t HTML.This attribute should be seen as a full, longer variation of summary if summary exists. Even then, the long_summary should be independent from summary, in that you only need to read one of them. This means you may have to repeat the first sentences.
Type: str
which can be parsed as XHTML.RSS: content:encoded or description
-
media
¶ Get or set the
Media
object that is attached to this episode.Note that if
id
is not set, the media’s URL is used as the id. If you rely on this, you should make sure the URL never changes, since changing the id messes up with clients (they will think this episode is new again, even if the user has listened to it already). Therefore, you should only rely on this behaviour if you own the domain which the episodes reside on. If you don’t, then you must setid
to an appropriate value manually.Type: podgen.Media
RSS: enclosure and itunes:duration
-
position
¶ A custom position for this episode on the iTunes store page.
If you would like this episode to appear first, set it to
1
. If you want it second, set it to2
, and so on. If multiple episodes share the same position, they will be sorted by theirpublication date
.To remove the order from the episode, set the position back to
None
.Type: int
RSS: itunes:order
-
publication_date
¶ The time and date this episode was first published.
The value can be a
str
, which will be parsed and made into adatetime.datetime
object when assigned. You may also assign adatetime.datetime
object directly. In both cases, you must ensure that the value includes timezone information.Type: str
(will be converted to and stored asdatetime.datetime
) ordatetime.datetime
.RSS: pubDate Note
Don’t use the media file’s modification date as the publication date, unless they’re the same. It looks very odd when an episode suddenly pops up in the feed, but it claims to be several hours old!
-
rss_entry
()[source]¶ Create an RSS item using lxml’s etree and return it.
This is primarily used by
podgen.Podcast
when generating the podcast’s RSS feed.Returns: etree.Element(‘item’)
-
subtitle
= None¶ A short subtitle.
This is shown in the Description column in iTunes. The subtitle displays best if it is only a few words long.
Type: str
RSS: itunes:subtitle
-
summary
= None¶ The summary of this episode, in a format that can be parsed by XHTML parsers.
If your summary isn’t fit to be parsed as XHTML, you can use
podgen.htmlencode()
to fix the text, like this:>>> ep.summary = podgen.htmlencode("We spread lots of love <3") >>> ep.summary We spread lots of love <3
In iTunes, the summary is shown in a separate window that appears when the “circled i” in the Description column is clicked. This field can be up to 4000 characters in length.
See also
Episode.subtitle
andEpisode.long_summary
.Type: str
which can be parsed as XHTML.RSS: description
-
title
= None¶ This episode’s human-readable title. Title is mandatory and should not be blank.
Type: str
RSS: title
-
withhold_from_itunes
¶ Prevent this episode from appearing in the iTunes podcast directory. Note that the episode can still be found by inspecting the XML, so it is still public.
One use case would be if you knew that this episode would get you kicked out from iTunes, should it make it there. In such cases, you can set withhold_from_itunes to
True
so this episode isn’t published on iTunes, allowing you to publish it to everyone else while keeping your podcast on iTunes.This attribute defaults to
False
, of course.Type: bool
RSS: itunes:block