Using PubSubHubbub — PodGen Documentation

# 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 PodGen 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

  - Step 2: Decide on a hub

  - Step 3: Set pubsubhubbub

  - Step 4: Set HTTP Link Header

  - Step 5: Notify the hub of new episodes

## 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 podgen 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 PodGen.

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