django/utils/feedgenerator.py

   1 """
   2 Syndication feed generation library -- used for generating RSS, etc.
   3
   4 Sample usage:
   5
   6 >>> from django.utils import feedgenerator
   7 >>> feed = feedgenerator.Rss201rev2Feed(
   8 ...     title=u"Poynter E-Media Tidbits",
   9 ...     link=u"http://www.poynter.org/column.asp?id=31",
  10 ...     description=u"A group weblog by the sharpest minds in online media/journalism/publishing.",
  11 ...     language=u"en",
  12 ... )
  13 >>> feed.add_item(title="Hello", link=u"http://www.holovaty.com/test/", description="Testing.")
  14 >>> fp = open('test.rss', 'w')
  15 >>> feed.write(fp, 'utf-8')
  16 >>> fp.close()
  17
  18 For definitions of the different versions of RSS, see:
  19 http://diveintomark.org/archives/2004/02/04/incompatible-rss
  20 """
  21
  22 import re
  23 import datetime
  24 from django.utils.xmlutils import SimplerXMLGenerator
  25 from django.utils.encoding import force_unicode, iri_to_uri
  26
  27 def rfc2822_date(date):
  28     # We do this ourselves to be timezone aware, email.Utils is not tz aware.
  29     if date.tzinfo:
  30         time_str = date.strftime('%a, %d %b %Y %H:%M:%S ')
  31         offset = date.tzinfo.utcoffset(date)
  32         timezone = (offset.days * 24 * 60) + (offset.seconds / 60)
  33         hour, minute = divmod(timezone, 60)
  34         return time_str + "%+03d%02d" % (hour, minute)
  35     else:
  36         return date.strftime('%a, %d %b %Y %H:%M:%S -0000')
  37
  38 def rfc3339_date(date):
  39     if date.tzinfo:
  40         time_str = date.strftime('%Y-%m-%dT%H:%M:%S')
  41         offset = date.tzinfo.utcoffset(date)
  42         timezone = (offset.days * 24 * 60) + (offset.seconds / 60)
  43         hour, minute = divmod(timezone, 60)
  44         return time_str + "%+03d:%02d" % (hour, minute)
  45     else:
  46         return date.strftime('%Y-%m-%dT%H:%M:%SZ')
  47
  48 def get_tag_uri(url, date):
  49     "Creates a TagURI. See http://diveintomark.org/archives/2004/05/28/howto-atom-id"
  50     tag = re.sub('^http://', '', url)
  51     if date is not None:
  52         tag = re.sub('/', ',%s:/' % date.strftime('%Y-%m-%d'), tag, 1)
  53     tag = re.sub('#', '/', tag)
  54     return u'tag:' + tag
  55
  56 class SyndicationFeed(object):
  57     "Base class for all syndication feeds. Subclasses should provide write()"
  58     def __init__(self, title, link, description, language=None, author_email=None,
  59             author_name=None, author_link=None, subtitle=None, categories=None,
  60             feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs):
  61         to_unicode = lambda s: force_unicode(s, strings_only=True)
  62         if categories:
  63             categories = [force_unicode(c) for c in categories]
  64         self.feed = {
  65             'title': to_unicode(title),
  66             'link': iri_to_uri(link),
  67             'description': to_unicode(description),
  68             'language': to_unicode(language),
  69             'author_email': to_unicode(author_email),
  70             'author_name': to_unicode(author_name),
  71             'author_link': iri_to_uri(author_link),
  72             'subtitle': to_unicode(subtitle),
  73             'categories': categories or (),
  74             'feed_url': iri_to_uri(feed_url),
  75             'feed_copyright': to_unicode(feed_copyright),
  76             'id': feed_guid or link,
  77             'ttl': ttl,
  78         }
  79         self.feed.update(kwargs)
  80         self.items = []
  81
  82     def add_item(self, title, link, description, author_email=None,
  83         author_name=None, author_link=None, pubdate=None, comments=None,
  84         unique_id=None, enclosure=None, categories=(), item_copyright=None,
  85         ttl=None, **kwargs):
  86         """
  87         Adds an item to the feed. All args are expected to be Python Unicode
  88         objects except pubdate, which is a datetime.datetime object, and
  89         enclosure, which is an instance of the Enclosure class.
  90         """
  91         to_unicode = lambda s: force_unicode(s, strings_only=True)
  92         if categories:
  93             categories = [to_unicode(c) for c in categories]
  94         item = {
  95             'title': to_unicode(title),
  96             'link': iri_to_uri(link),
  97             'description': to_unicode(description),
  98             'author_email': to_unicode(author_email),
  99             'author_name': to_unicode(author_name),
 100             'author_link': iri_to_uri(author_link),
 101             'pubdate': pubdate,
 102             'comments': to_unicode(comments),
 103             'unique_id': to_unicode(unique_id),
 104             'enclosure': enclosure,
 105             'categories': categories or (),
 106             'item_copyright': to_unicode(item_copyright),
 107             'ttl': ttl,
 108         }
 109         item.update(kwargs)
 110         self.items.append(item)
 111
 112     def num_items(self):
 113         return len(self.items)
 114
 115     def root_attributes(self):
 116         """
 117         Return extra attributes to place on the root (i.e. feed/channel) element.
 118         Called from write().
 119         """
 120         return {}
 121
 122     def add_root_elements(self, handler):
 123         """
 124         Add elements in the the root (i.e. feed/channel) element. Called
 125         from write().
 126         """
 127         pass
 128
 129     def item_attributes(self, item):
 130         """
 131         Return extra attributes to place on each item (i.e. item/entry) element.
 132         """
 133         return {}
 134
 135     def add_item_elements(self, handler, item):
 136         """
 137         Add elements on each item (i.e. item/entry) element.
 138         """
 139         pass
 140
 141     def write(self, outfile, encoding):
 142         """
 143         Outputs the feed in the given encoding to outfile, which is a file-like
 144         object. Subclasses should override this.
 145         """
 146         raise NotImplementedError
 147
 148     def writeString(self, encoding):
 149         """
 150         Returns the feed in the given encoding as a string.
 151         """
 152         from StringIO import StringIO
 153         s = StringIO()
 154         self.write(s, encoding)
 155         return s.getvalue()
 156
 157     def latest_post_date(self):
 158         """
 159         Returns the latest item's pubdate. If none of them have a pubdate,
 160         this returns the current date/time.
 161         """
 162         updates = [i['pubdate'] for i in self.items if i['pubdate'] is not None]
 163         if len(updates) > 0:
 164             updates.sort()
 165             return updates[-1]
 166         else:
 167             return datetime.datetime.now()
 168
 169 class Enclosure(object):
 170     "Represents an RSS enclosure"
 171     def __init__(self, url, length, mime_type):
 172         "All args are expected to be Python Unicode objects"
 173         self.length, self.mime_type = length, mime_type
 174         self.url = iri_to_uri(url)
 175
 176 class RssFeed(SyndicationFeed):
 177     mime_type = 'application/rss+xml'
 178     def write(self, outfile, encoding):
 179         handler = SimplerXMLGenerator(outfile, encoding)
 180         handler.startDocument()
 181         handler.startElement(u"rss", self.rss_attributes())
 182         handler.startElement(u"channel", self.root_attributes())
 183         self.add_root_elements(handler)
 184         self.write_items(handler)
 185         self.endChannelElement(handler)
 186         handler.endElement(u"rss")
 187
 188     def rss_attributes(self):
 189         return {u"version": self._version}
 190
 191     def write_items(self, handler):
 192         for item in self.items:
 193             handler.startElement(u'item', self.item_attributes(item))
 194             self.add_item_elements(handler, item)
 195             handler.endElement(u"item")
 196
 197     def add_root_elements(self, handler):
 198         handler.addQuickElement(u"title", self.feed['title'])
 199         handler.addQuickElement(u"link", self.feed['link'])
 200         handler.addQuickElement(u"description", self.feed['description'])
 201         if self.feed['language'] is not None:
 202             handler.addQuickElement(u"language", self.feed['language'])
 203         for cat in self.feed['categories']:
 204             handler.addQuickElement(u"category", cat)
 205         if self.feed['feed_copyright'] is not None:
 206             handler.addQuickElement(u"copyright", self.feed['feed_copyright'])
 207         handler.addQuickElement(u"lastBuildDate", rfc2822_date(self.latest_post_date()).decode('utf-8'))
 208         if self.feed['ttl'] is not None:
 209             handler.addQuickElement(u"ttl", self.feed['ttl'])
 210
 211     def endChannelElement(self, handler):
 212         handler.endElement(u"channel")
 213
 214 class RssUserland091Feed(RssFeed):
 215     _version = u"0.91"
 216     def add_item_elements(self, handler, item):
 217         handler.addQuickElement(u"title", item['title'])
 218         handler.addQuickElement(u"link", item['link'])
 219         if item['description'] is not None:
 220             handler.addQuickElement(u"description", item['description'])
 221
 222 class Rss201rev2Feed(RssFeed):
 223     # Spec: http://blogs.law.harvard.edu/tech/rss
 224     _version = u"2.0"
 225     def add_item_elements(self, handler, item):
 226         handler.addQuickElement(u"title", item['title'])
 227         handler.addQuickElement(u"link", item['link'])
 228         if item['description'] is not None:
 229             handler.addQuickElement(u"description", item['description'])
 230
 231         # Author information.
 232         if item["author_name"] and item["author_email"]:
 233             handler.addQuickElement(u"author", "%s (%s)" % \
 234                 (item['author_email'], item['author_name']))
 235         elif item["author_email"]:
 236             handler.addQuickElement(u"author", item["author_email"])
 237         elif item["author_name"]:
 238             handler.addQuickElement(u"dc:creator", item["author_name"], {"xmlns:dc": u"http://purl.org/dc/elements/1.1/"})
 239
 240         if item['pubdate'] is not None:
 241             handler.addQuickElement(u"pubDate", rfc2822_date(item['pubdate']).decode('utf-8'))
 242         if item['comments'] is not None:
 243             handler.addQuickElement(u"comments", item['comments'])
 244         if item['unique_id'] is not None:
 245             handler.addQuickElement(u"guid", item['unique_id'])
 246         if item['ttl'] is not None:
 247             handler.addQuickElement(u"ttl", item['ttl'])
 248
 249         # Enclosure.
 250         if item['enclosure'] is not None:
 251             handler.addQuickElement(u"enclosure", '',
 252                 {u"url": item['enclosure'].url, u"length": item['enclosure'].length,
 253                     u"type": item['enclosure'].mime_type})
 254
 255         # Categories.
 256         for cat in item['categories']:
 257             handler.addQuickElement(u"category", cat)
 258
 259 class Atom1Feed(SyndicationFeed):
 260     # Spec: http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html
 261     mime_type = 'application/atom+xml'
 262     ns = u"http://www.w3.org/2005/Atom"
 263
 264     def write(self, outfile, encoding):
 265         handler = SimplerXMLGenerator(outfile, encoding)
 266         handler.startDocument()
 267         handler.startElement(u'feed', self.root_attributes())
 268         self.add_root_elements(handler)
 269         self.write_items(handler)
 270         handler.endElement(u"feed")
 271
 272     def root_attributes(self):
 273         if self.feed['language'] is not None:
 274             return {u"xmlns": self.ns, u"xml:lang": self.feed['language']}
 275         else:
 276             return {u"xmlns": self.ns}
 277
 278     def add_root_elements(self, handler):
 279         handler.addQuickElement(u"title", self.feed['title'])
 280         handler.addQuickElement(u"link", "", {u"rel": u"alternate", u"href": self.feed['link']})
 281         if self.feed['feed_url'] is not None:
 282             handler.addQuickElement(u"link", "", {u"rel": u"self", u"href": self.feed['feed_url']})
 283         handler.addQuickElement(u"id", self.feed['id'])
 284         handler.addQuickElement(u"updated", rfc3339_date(self.latest_post_date()).decode('utf-8'))
 285         if self.feed['author_name'] is not None:
 286             handler.startElement(u"author", {})
 287             handler.addQuickElement(u"name", self.feed['author_name'])
 288             if self.feed['author_email'] is not None:
 289                 handler.addQuickElement(u"email", self.feed['author_email'])
 290             if self.feed['author_link'] is not None:
 291                 handler.addQuickElement(u"uri", self.feed['author_link'])
 292             handler.endElement(u"author")
 293         if self.feed['subtitle'] is not None:
 294             handler.addQuickElement(u"subtitle", self.feed['subtitle'])
 295         for cat in self.feed['categories']:
 296             handler.addQuickElement(u"category", "", {u"term": cat})
 297         if self.feed['feed_copyright'] is not None:
 298             handler.addQuickElement(u"rights", self.feed['feed_copyright'])
 299
 300     def write_items(self, handler):
 301         for item in self.items:
 302             handler.startElement(u"entry", self.item_attributes(item))
 303             self.add_item_elements(handler, item)
 304             handler.endElement(u"entry")
 305
 306     def add_item_elements(self, handler, item):
 307         handler.addQuickElement(u"title", item['title'])
 308         handler.addQuickElement(u"link", u"", {u"href": item['link'], u"rel": u"alternate"})
 309         if item['pubdate'] is not None:
 310             handler.addQuickElement(u"updated", rfc3339_date(item['pubdate']).decode('utf-8'))
 311
 312         # Author information.
 313         if item['author_name'] is not None:
 314             handler.startElement(u"author", {})
 315             handler.addQuickElement(u"name", item['author_name'])
 316             if item['author_email'] is not None:
 317                 handler.addQuickElement(u"email", item['author_email'])
 318             if item['author_link'] is not None:
 319                 handler.addQuickElement(u"uri", item['author_link'])
 320             handler.endElement(u"author")
 321
 322         # Unique ID.
 323         if item['unique_id'] is not None:
 324             unique_id = item['unique_id']
 325         else:
 326             unique_id = get_tag_uri(item['link'], item['pubdate'])
 327         handler.addQuickElement(u"id", unique_id)
 328
 329         # Summary.
 330         if item['description'] is not None:
 331             handler.addQuickElement(u"summary", item['description'], {u"type": u"html"})
 332
 333         # Enclosure.
 334         if item['enclosure'] is not None:
 335             handler.addQuickElement(u"link", '',
 336                 {u"rel": u"enclosure",
 337                  u"href": item['enclosure'].url,
 338                  u"length": item['enclosure'].length,
 339                  u"type": item['enclosure'].mime_type})
 340
 341         # Categories.
 342         for cat in item['categories']:
 343             handler.addQuickElement(u"category", u"", {u"term": cat})
 344
 345         # Rights.
 346         if item['item_copyright'] is not None:
 347             handler.addQuickElement(u"rights", item['item_copyright'])
 348
 349 # This isolates the decision of what the system default is, so calling code can
 350 # do "feedgenerator.DefaultFeed" instead of "feedgenerator.Rss201rev2Feed".
 351 DefaultFeed = Rss201rev2Feed