podgen.Podcast¶

class podgen.Podcast(**kwargs)[source]¶

Class representing one podcast feed.

The following attributes are mandatory:

name
website
description
explicit

All attributes can be assigned None in addition to the types specified below. Types etc. are checked during assignment, to help you discover errors earlier. Duck typing is employed wherever a class in podgen is expected.

There is a shortcut you can use when creating new Podcast objects, that lets you populate the attributes using the constructor. Use keyword arguments with the attribute name as keyword and the desired value as value. As an example:

>>> import podgen
>>> # The following...
>>> p = Podcast()
>>> p.name = "The Test Podcast"
>>> p.website = "http://example.com"
>>> # ...is the same as this:
>>> p = Podcast(
...     name="The Test Podcast",
...     website="http://example.com",
... )

Of course, you can do this for as many (or few) attributes as you like, and you can still set the attributes afterwards, like always.

Raises:	TypeError if you use a keyword which isn’t recognized as an attribute. ValueError if you use a value which isn’t compatible with the attribute (just like when you assign it manually).

add_episode(new_episode=None)[source]¶

Shorthand method which adds a new episode to the feed, creating an object if it’s not provided, and returns it. This is the easiest way to add episodes to a podcast.

Parameters:	new_episode – `Episode` object to add. A new instance of `episode_class` is used if `new_episode` is omitted.
Returns:	Episode object created or passed to this function.

Example:

...
>>> episode1 = p.add_episode()
>>> episode1.title = 'First episode'
>>> # You may also provide an episode object yourself:
>>> another_episode = p.add_episode(podgen.Episode())
>>> another_episode.title = 'My second episode'

Internally, this method creates a new instance of episode_class, which means you can change what type of objects are created by changing episode_class.

apply_episode_order()[source]¶

Make sure that the episodes appear on iTunes in the exact order they have in episodes.

This will set each Episode.position so it matches the episode’s position in Podcast.episodes.

If you’re using some Episode objects in multiple podcast feeds and you don’t use this method with every feed, you might want to call Podcast.clear_episode_order() after generating this feed’s RSS so an episode’s position in this feed won’t affect its position in the other feeds.

authors¶

List of Person that are responsible for this podcast’s editorial content.

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
>>> p.authors = Person("John Doe", "johndoe@example.org")
TypeError: Only iterable types can be assigned to authors, ...
>>> # This is the correct way:
>>> p.authors = [Person("John Doe", "johndoe@example.org")]

The authors don’t need to have both name and email set. The names are shown under the podcast’s title on iTunes.

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:
>>> p.authors.append(Person("John Doe", "johndoe@example.org"))
>>> # Or they can be given as new list (overriding earlier authors)
>>> p.authors = [Person("John Doe", "johndoe@example.org"),
...               Person("Mary Sue", "marysue@example.org")]

Type:	`list` of `podgen.Person`
RSS:	managingEditor or dc:creator, and itunes:author

category¶

The iTunes category, which appears in the category column and in iTunes Store listings.

Type:	`podgen.Category`
RSS:	itunes:category

clear_episode_order()[source]¶

Reset Episode.position for every single episode.

Use this if you want to reuse an Episode object in another feed, and don’t want its position in this feed to affect where it appears in the other feed. This is not needed if you’ll call Podcast.apply_episode_order() on the other feed, though.

cloud¶

The cloud data of the feed, as a 5-tuple. It specifies a web service that supports the (somewhat dated) rssCloud interface, which can be implemented in HTTP-POST, XML-RPC or SOAP 1.1.

The tuple should look like this: (domain, port, path, registerProcedure, protocol).

RegisterProcedure:
Domain:	The domain where the webservice can be found.
Port:	The port the webservice listens to.
Path:	The path of the webservice.
	The procedure to call.
Protocol:	Can be either “HTTP-POST”, “xml-rpc” or “soap”.

Example:

p.cloud = ("podcast.example.org", 80, "/rpc", "cloud.notify",
        "xml-rpc")

Type:	`tuple` with (`str`, `int`, `str`, `str`, `str`)
RSS:	cloud

Tip

PubSubHubbub is a competitor to rssCloud, and is the preferred choice if you’re looking to set up a new service of this kind.

complete¶

Whether this podcast is completed or not.

If you set this to True, you are indicating that no more episodes will be added to the podcast. If you let this be None or False, you are indicating that new episodes may be posted.

Type:	`bool`
RSS:	itunes:complete

Warning

Setting this to True is the same as promising you’ll never ever release a new episode. Do NOT set this to True as long as there’s any chance AT ALL that a new episode will be released someday.

copyright = None¶

The copyright notice for content in this podcast.

Note that even if you leave out the copyright notice, your content is still protected by copyright (unless anything else is indicated), since you do not need a copyright statement for something to be protected by copyright. If you intend to put the podcast in public domain or license it under a Creative Commons license, you should say so in the copyright notice.

Type:	`str`
RSS:	copyright

description = None¶

The description of the podcast, which is a phrase or sentence describing it to potential new subscribers. It is mandatory for RSS feeds, and is shown under the podcast’s name on the iTunes store page.

Type:	`str`
RSS:	description

episode_class¶

Class used to represent episodes.

This is used by add_episode() when creating new episode objects, and you, too, may use it when creating episodes.

By default, this property points to Episode.

When assigning a new class to episode_class, you must make sure that the new value (1) is a class and not an instance, and (2) that it is a subclass of Episode (or is Episode itself).

Example of use:

>>> # Create new podcast
>>> from podgen import Podcast, Episode
>>> p = Podcast()

>>> # Normal way of creating new episodes
>>> episode1 = Episode()
>>> p.episodes.append(episode1)

>>> # Or use add_episode (and thus episode_class indirectly)
>>> episode2 = p.add_episode()

>>> # Or use episode_class directly
>>> episode3 = p.episode_class()
>>> p.episodes.append(episode3)

>>> # Say you want to use AlternateEpisode class instead of Episode
>>> from mymodule import AlternateEpisode
>>> p.episode_class = AlternateEpisode

>>> episode4 = p.add_episode()
>>> episode4.title("This is an instance of AlternateEpisode!")

Type:	`class` which extends `podgen.Episode`

episodes¶

List of Episode objects that are part of this podcast.

See add_episode() for an easy way to create new episodes and assign them to this podcast in one call.

Type:	`list` of `podgen.Episode`
RSS:	item elements

explicit = None¶

Whether this podcast may be inappropriate for children or not.

This is one of the mandatory attributes, and can seen as the default for episodes. Individual episodes can be marked as explicit or clean independently from the podcast.

If you set this to True, an “explicit” parental advisory graphic will appear next to your podcast artwork on the iTunes Store and in the Name column in iTunes. If it is set to False, the parental advisory type is considered Clean, meaning that no explicit language or adult content is included anywhere in the episodes, and a “clean” graphic will appear.

Type:	`bool`
RSS:	itunes:explicit

feed_url¶

The URL which this feed is available at.

Identifying a feed’s URL within the feed makes it more portable, self-contained, and easier to cache. You should therefore set this attribute if you’re able to.

Type:	`str`
RSS:	atom:link with `rel="self"`

generator = None¶

A string identifying the software that generated this RSS feed. Defaults to a string identifying PodGen.

Type:	`str`
RSS:	generator

See also

The set_generator() method: A convenient way to set the generator value and include version and url.

image¶

The URL of the artwork for this podcast. iTunes prefers square images that are at least 1400x1400 pixels. Podcasts with an image smaller than this are not eligible to be featured on the iTunes Store.

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

Type:	`str`
RSS:	itunes:image

Note

If you change your podcast’s image, you must also change the file’s name; iTunes doesn’t check the image to see if it has changed.

Additionally, the server hosting your cover art image must allow HTTP HEAD requests (most servers support this).

language = None¶

The language of the podcast.

This allows aggregators to group all Italian language podcasts, for example, on a single page.

It must be a two-letter code, as found in ISO639-1, with the possibility of specifying subcodes (eg. en-US for American English). See http://www.rssboard.org/rss-language-codes and http://www.loc.gov/standards/iso639-2/php/code_list.php

Type:	`str`
RSS:	language

last_updated¶

The last time the feed was generated. It defaults to the time and date at which the RSS is generated, if set to None. The default should be sufficient for most, if not all, use cases.

The value can either be a string, which will automatically be parsed into a datetime.datetime object when assigned, or a datetime.datetime object. In any case, the time and date must be timezone aware.

Set this to False to leave out this element instead of using the default.

Type:	`datetime.datetime`, `str` (will be converted to and stored as `datetime.datetime`), `None` for default or `False` to leave out.
RSS:	lastBuildDate

name = None¶

The name of the podcast as a str. It should be a human readable title. Often the same as the title of the associated website. This is mandatory and must not be blank.

Type:	`str`
RSS:	title

new_feed_url = None¶

When set, tell iTunes that your feed has moved to this URL.

After adding this attribute, you should maintain the old feed for 48 hours before retiring it. At that point, iTunes will have updated the directory with the new feed URL.

Type:	`str`
RSS:	itunes:new-feed-url

Warning

iTunes supports this mechanic of changing your feed’s location. However, you cannot assume the same of everyone else who has subscribed to this podcast. Therefore, you should NEVER stop supporting an old location for your podcast. Instead, you should create HTTP redirects so those with the old address are redirected to your new address, and keep those redirects up for all eternity.

Warning

Make sure the new URL you set is correct, or else you’re making people switch to a URL that doesn’t work!

notify_hub(requests, timeout=5.0)[source]¶

Notify this podcast’s PubSubHubbub hub about new episode(s).

When using PubSubHubbub, you must notify it whenever there’s a new episode available. Use this method to do so, after the new episode is available – the hub will check the feed to figure out what’s new once you do so.

Parameters:	requests (requests or requests.Session) – The requests module, or a Session object. timeout (float) – Number of seconds to wait for the hub to respond. Defaults to five seconds.

Note

This method is blocking, and will return when the server responds.

Note

For this to work, this feed must have feed_url and pubsubhubbub set correctly.

See also

The class method notify_multiple(): For sending notifications about multiple feeds.
The guide on using PubSubHubbub: For a step-for-step guide with examples.

classmethod notify_multiple(requests, feeds, timeout=10.0)[source]¶

Notify the PubSubHubbub hubs of additions in multiple Podcasts.

When using PubSubHubbub, you must notify the hub whenever a feed has new entries. Using this method, you can give a list of feeds which all have new content. This saves time compared to notify_hub() since they can be made into one request per hub, instead of having one request per feed per hub.

The Podcast objects don’t need to use the same PubSubHubbub hub.

Parameters:	requests (requests or requests.Session) – The requests module, or a Session object. feeds (`list` of `Podcast`) – List of Podcast objects which have new or changed content published. timeout (float) – Number of seconds we can wait for the server to respond. Applies to each hub separately. Defaults to ten seconds.
Warnings:	UserWarning for each feed that has no value for `pubsubhubbub` and `feed_url`.

Note

This method is blocking, and will return when the servers respond.

Note

For this to work for a given feed, it must have feed_url and pubsubhubbub set correctly.

See also

The instance method notify_hub(): For notifying a single hub about a single feed
The guide on using PubSubHubbub: For a step-for-step guide with examples.

owner¶

The Person who owns this podcast. iTunes will use this person’s name and email address for all correspondence related to this podcast. It will not be publicly displayed, but it’s still publicly available in the RSS source.

Both the name and email are required.

Type:	`podgen.Person`
RSS:	itunes:owner

publication_date¶

The publication date for the content in this podcast. You probably want to use the default value.

Default value:	If this is `None` when the feed is generated, the publication date of the episode with the latest publication date (which may be in the future) is used. If there are no episodes, the publication date is omitted from the feed.

If you set this to a str, it will be parsed and made into a datetime.datetime object when assigned. You may also set it to a datetime.datetime object directly. In any case, the time and date must be timezone aware.

If you want to forcefully omit the publication date from the feed, set this to False.

Type:	`datetime.datetime`, `str` (will be converted to and stored as `datetime.datetime`), `None` for default or `False` to leave out.
RSS:	pubDate

pubsubhubbub = None¶

The URL at which the PubSubHubbub hub can be found.

Podcatchers can tell the hub that they want to be notified when a new episode is released. This way, they don’t need to check for new episodes every few hours; instead, the episodes arrive at their doorstep as soon as they’re published, through a notification sent by the hub.

Type:	`str`
RSS:	atom:link with `rel="hub"`

Note

You only need to worry about this attribute if you’ve set up PubSubHubbub for your podcast.

Note

In addition to setting this attribute, you must set the feed_url to the canonical URL of this feed. That way, there is no confusion about which URL should be given to the PubSubHubbub by the podcatcher when subscribing.

Note

On top of all this, you MUST make sure you also use the Link header in the HTTP response that is sent with this feed, duplicating the link to the PubSubHubbub and the feed. Example of what it might look like:

Link: <https://link.to.pubsubhubbub.example.org/>; rel="hub",
 <https://example.org/podcast.rss>; rel="self"

This is necessary for compatibility with the different versions of PubSubHubbub. The latest version of the standard specifically says that publishers MUST use the Link header.

rss_file(filename, minimize=False, encoding='UTF-8', xml_declaration=True)[source]¶

Generate an RSS feed and write the resulting XML to a file.

Note

If atomicity is needed, then you are expected to provide that yourself. That means that you should write the feed to a temporary file which you rename to the final name afterwards; renaming is an atomic operation on Unix(like) systems.

Note

File-like objects given to this method will not be closed.

Parameters:

filename (str or fd) – Name of file to write, or a file-like object, or a URL.
minimize (bool) – Set to True to disable splitting the feed into multiple lines and adding properly indentation, saving bytes at the cost of readability (default: False).
encoding (str) – Encoding used in the XML file (default: UTF-8).
xml_declaration (bool) – Whether an XML declaration should be added to the output (default: True).

Returns:

Nothing.

rss_str(minimize=False, encoding='UTF-8', xml_declaration=True)[source]¶

Generate an RSS feed and return the feed XML as string.

Parameters:	minimize (bool) – Set to True to disable splitting the feed into multiple lines and adding properly indentation, saving bytes at the cost of readability (default: False). encoding (str) – Encoding used in the XML declaration (default: UTF-8). xml_declaration (bool) – Whether an XML declaration should be added to the output (default: True).
Returns:	The generated RSS feed as a `str` (unicode in 2.7)

set_generator(generator=None, version=None, uri=None, exclude_podgen=False)[source]¶

Set the generator of the feed, formatted nicely, which identifies the software used to generate the feed.

Parameters:	generator (str) – Software used to create the feed. version (`tuple` of `int`) – (Optional) Version of the software, as a tuple. uri (str) – (Optional) The software’s website. exclude_podgen (bool) – (Optional) Set to True if you don’t want PodGen to be mentioned (e.g., “My Program (using PodGen 1.0.0)”)

See also

The attribute generator: Lets you access and set the generator string yourself, without any formatting help.

skip_days¶

Set of days in which podcatchers don’t need to refresh this feed.

This isn’t widely supported by podcatchers.

The days are represented using strings of their English names, like “Monday” or “wednesday”. The day names are automatically capitalized when the set is assigned to skip_days, but subsequent changes to the set “in place” are only checked and capitalized when the RSS feed is generated.

For example, to stop refreshing the feed in the weekend:

>>> from podgen import Podcast
>>> p = Podcast()
>>> p.skip_days = {"Friday", "Saturday", "sUnDaY"}
>>> p.skip_days
{"Saturday", "Friday", "Sunday"}

Type:	`set` of `str`
RSS:	skipDays

skip_hours¶

Set of hours of the day in which podcatchers don’t need to refresh this feed.

This isn’t widely supported by podcatchers.

The hours are represented as integer values from 0 to 23. Note that while the content of the set is checked when it is first assigned to skip_hours, further changes to the set “in place” will not be checked before you generate the RSS.

For example, to stop refreshing the feed between 18 and 7:

>>> from podgen import Podcast
>>> p = Podcast()
>>> p.skip_hours = set(range(18, 24))
>>> p.skip_hours
{18, 19, 20, 21, 22, 23}
>>> p.skip_hours |= set(range(8))
>>> p.skip_hours
{0, 1, 2, 3, 4, 5, 6, 7, 18, 19, 20, 21, 22, 23}

Type:	`set` of `int`
RSS:	skipHours

subtitle = None¶

The subtitle for your podcast, shown mainly as a very short description on iTunes. The subtitle displays best if it is only a few words long, like a short slogan.

Type:	`str`
RSS:	itunes:subtitle

web_master¶

The Person responsible for technical issues relating to the feed.

Type:	`podgen.Person`
RSS:	webMaster

website = None¶

The absolute URL of this podcast’s website.

This is one of the mandatory attributes.

Type:	`str`
RSS:	link

withhold_from_itunes = None¶

Prevent the entire podcast from appearing in the iTunes podcast directory.

Note that this will affect more than iTunes, since most podcatchers use the iTunes catalogue to implement the search feature. Listeners will still be able to subscribe by adding the feed’s address manually.

If you don’t intend to submit this podcast to iTunes, you can set this to True as a way of giving iTunes the middle finger, and perhaps more importantly, preventing others from submitting it as well.

Set it to True to withhold the entire podcast from iTunes. It is set to False by default, of course.

Type:	`bool`
RSS:	itunes:block

xslt = None¶

Absolute URL to the XSLT file which web browsers should use with this feed.

XSLT stands for Extensible Stylesheet Language Transformations and can be regarded as a template language made for transforming XML into XHTML (among other things). You can use it to avoid giving users an ugly XML listing when trying to subscribe to your podcast; this technique is in fact employed by most podcast publishers today. In a web browser, it looks like a web page, and to the podcatchers, it looks like a normal podcast feed. To put it another way, the very same URL can be used as an information web page about the podcast as well as the URL you subscribe to in podcatchers.

Type:	`str`
RSS:	Processor instruction right after the xml declaration called `xml-stylesheet`, with type set to `text/xsl` and href set to this attribute.

Note

Firefox will use its own stylesheet for RSS feeds, so you must test using another browser and possibly a simple web server (python -m http.server 8000 -b 127.0.0.1).