webhelpers.feedgenerator

This is a port of Django’s feeed generator for creating RSS and Atom feeds. The Geo classes for publishing geographical (GIS) data are also ported.

Syndication feed generation library – used for generating RSS, etc.

Sample usage:

>>> import webhelpers.feedgenerator as feedgenerator
>>> feed = feedgenerator.Rss201rev2Feed(
...     title=u"Poynter E-Media Tidbits",
...     link=u"http://www.poynter.org/column.asp?id=31",
...     description=u"A group weblog by the sharpest minds in online media/journalism/publishing.",
...     language=u"en",
... )
>>> feed.add_item(title="Hello", link=u"http://www.holovaty.com/test/", description="Testing.")
>>> fp = open('test.rss', 'w')
>>> feed.write(fp, 'utf-8')
>>> fp.close()

For definitions of the different versions of RSS, see: http://diveintomark.org/archives/2004/02/04/incompatible-rss

Classes

class webhelpers.feedgenerator.SyndicationFeed(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)

Base class for all syndication feeds. Subclasses should provide write()

add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, **kwargs)

Adds an item to the feed. All args are expected to be Python Unicode objects except pubdate, which is a datetime.datetime object, and enclosure, which is an instance of the Enclosure class.

add_item_elements(handler, item)

Add elements on each item (i.e. item/entry) element.

add_root_elements(handler)

Add elements in the root (i.e. feed/channel) element. Called from write().

item_attributes(item)

Return extra attributes to place on each item (i.e. item/entry) element.

latest_post_date()

Returns the latest item’s pubdate. If none of them have a pubdate, this returns the current date/time.

num_items()
root_attributes()

Return extra attributes to place on the root (i.e. feed/channel) element. Called from write().

write(outfile, encoding)

Outputs the feed in the given encoding to outfile, which is a file-like object. Subclasses should override this.

writeString(encoding)

Returns the feed in the given encoding as a string.

class webhelpers.feedgenerator.Enclosure(url, length, mime_type)

Represents an RSS enclosure

class webhelpers.feedgenerator.RssFeed(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)
add_root_elements(handler)
endChannelElement(handler)
mime_type = 'application/rss+xml'
rss_attributes()
write(outfile, encoding)
write_items(handler)
class webhelpers.feedgenerator.RssUserland091Feed(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)
add_item_elements(handler, item)
class webhelpers.feedgenerator.Rss201rev2Feed(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)
add_item_elements(handler, item)
class webhelpers.feedgenerator.Atom1Feed(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)
add_item_elements(handler, item)
add_root_elements(handler)
mime_type = 'application/atom+xml'
ns = u'http://www.w3.org/2005/Atom'
root_attributes()
write(outfile, encoding)
write_items(handler)

DefaultFeed is an alias for Rss201rev2Feed.

Functions

webhelpers.feedgenerator.rfc2822_date(date)
webhelpers.feedgenerator.rfc3339_date(date)
webhelpers.feedgenerator.get_tag_uri(url, date)

Creates a TagURI. See http://diveintomark.org/archives/2004/05/28/howto-atom-id

GIS subclasses

These classes allow you to include geometries (e.g., latitude/longitude) in your feed. The implementation is in a mixin class:

class webhelpers.feedgenerator.GeoFeedMixin

This mixin provides the necessary routines for SyndicationFeed subclasses to produce simple GeoRSS or W3C Geo elements.

Subclasses recognize a geometry keyword argument to .add_item(). The value may be any of several types:

  • a 2-element tuple or list of floats representing latitude/longitude: (X, Y). This is called a “point”.
  • a 4-element tuple or list of floats representing a box: (X0, Y0, X1, Y1).
  • a tuple or list of two points: ( (X0, Y0), (X1, Y1) ).
  • a Geometry instance. (Or any compatible class.) This provides limited support for points, lines, and polygons. Read the Geometry docstring and the source of GeoFeedMixin.add_georss_element() before using this.

The mixin provides one class attribute:

is_input_latitude_first

The default value False indicates that input data is in latitude/longitude order. Change to True if the input data is longitude/latitude. The output is always written latitude/longitude to conform to the GeoRSS spec.

The reason for this attribute is that the Django original stores data in longitude/latutude order and reverses the arguments before writing. WebHelpers does not do this by default, but if you’re using Django data or other data that has longitude first, you’ll have to set this.

Methods:

add_georss_element(handler, item, w3c_geo=False)

This routine adds a GeoRSS XML element using the given item and handler.

add_georss_point(handler, coords, w3c_geo=False)

Adds a GeoRSS point with the given coords using the given handler. Handles the differences between simple GeoRSS and the more popular W3C Geo specification.

georss_coords(coords)

In GeoRSS coordinate pairs are ordered by lat/lon and separated by a single white space. Given a tuple of coordinates, this will return a unicode GeoRSS representation.

Two concrete subclasses are provided:

class webhelpers.feedgenerator.GeoAtom1Feed(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)
class webhelpers.feedgenerator.W3CGeoFeed(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)

A minimal geometry class is included:

class webhelpers.feedgenerator.Geometry(geom_type, coords)

A basic geometry class for GeoFeedMixin.

Instances have two public attributes:

geom_type

“point”, “linestring”, “linearring”, “polygon”

coords

For point, a tuple or list of two floats: (X, Y).

For linestring or linearring, a string: "X0 Y0  X1 Y1 ...".

For polygon, a list of strings: ["X0 Y0  X1 Y1 ..."]. Only the first element is used because the Geo classes support only the exterior ring.

The constructor does not check its argument types.

This class was created for WebHelpers based on the interface expected by GeoFeedMixin.add_georss_element(). The class is untested. Please send us feedback on whether it works for you.