Using PubSubHubbub¶

PubSubHubbub is a free and open protocol for pushing updates to clients when there’s new content available in the feed, as opposed to the traditional polling clients do.

Read about what PubSubHubbub is before you continue.

Note

While the protocol supports having multiple PubSubHubbub hubs for a single Podcast, there is no support for this in pod2gen at the moment.

Warning

Read through the whole guide at least once before you start implementing this. Specifically, you must not set the pubsubhubbub attribute if you haven’t got a way to notify hubs of new episodes.

Contents

Using PubSubHubbub

Step 1: Set feed_url¶

First, you must ensure that the Podcast object has the feed_url attribute set to the URL at which the feed is accessible.

# Assume p is a Podcast object
p.feed_url = "https://example.com/feeds/examplefeed.rss"

Step 2: Decide on a hub¶

The Wikipedia article mentions a few options you can use (called Community Hosted hub providers). Alternatively, you can set up and host your own server using one of the open source alternatives, like for instance Switchboard.

Step 3: Set pubsubhubbub¶

The Podcast must contain information about which hub to use. You do this by setting pubsubhubbub to the URL which the hub is available at.

p.pubsubhubbub = "https://pubsubhubbub.example.com/"

Step 4: Set HTTP Link Header¶

In addition to embedding the PubSubHubbub hub URL and the feed’s URL in the RSS itself, you should 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"

How you can achieve this varies from framework to framework. Here is an example using Flask (assuming the code is inside a view function):

from flask import make_response
from pod2gen import Podcast
# ...
@app.route("/<feedname>")  # Just as an example
def show_feed(feedname):
    p = Podcast()
    # ...
    # This is the relevant part:
    response = make_response(str(p))
    response.headers.add("Link", "<%s>" % p.pubsubhubbub, rel="hub")
    response.headers.add("Link", "<%s>" % p.feed_url, rel="self")
    return response

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. If you’re unable to do this, you can try publishing the feed without; most clients and hubs should manage just fine.

Step 5: Notify the hub of new episodes¶

Warning

The hub won’t know that you’ve published new episodes unless you tell it about it. If you don’t do this, the hub will assume there is no new content, and clients which trust the hub to inform them of new episodes will think there is no new content either. Don’t set the pubsubhubbub field if you haven’t set this up yet.

Different hubs have different ways of notifying it of new episodes. That’s why you must notify the hubs yourself; supporting all hubs is out of scope for pod2gen.

If you use the Google PubSubHubbub or the Superfeedr hub, there is a pip package called PubSubHubbub_Publisher which provides this functionality for you. Example:

from pubsubhubbub_publish import publish, PublishError
from pod2gen import Podcast
# ...
try:
    publish(p.pubsubhubbub, p.feed_url)
except PublishError as e:
    # Handle error

In all other cases, you’re encouraged to use Requests to make the necessary POST request (if no publisher package is available).

Note

If you have changes in multiple feeds, you can usually send just one single notification to the hub with all the feeds’ URLs included. It is worth researching, as it can save both you and the hub a lot of time.