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