Changeset 8311

Timestamp:

08/11/08 17:22:26 (11 months ago)

Author:

jacob

Message:

Added a number of callbacks to SyndicationFeed? for adding custom attributes and elements to feeds. Refs #6547.

Files:

• django/trunk/django/utils/feedgenerator.py (modified) (10 diffs)
• django/trunk/docs/syndication_feeds.txt (modified) (3 diffs)
• django/trunk/tests/regressiontests/syndication/feeds.py (modified) (1 diff)
• django/trunk/tests/regressiontests/syndication/tests.py (modified) (2 diffs)
• django/trunk/tests/regressiontests/syndication/urls.py (modified) (2 diffs)

django/trunk/django/utils/feedgenerator.py

@@ -20 +20 @@
-"""
-
+import re
+import datetime
-from django.utils.xmlutils import SimplerXMLGenerator
-from django.utils.encoding import force_unicode, iri_to_uri
-import datetime, re, time
-
-def rfc2822_date(date):
@@ -57 +58 @@
-    def __init__(self, title, link, description, language=None, author_email=None,
-            author_name=None, author_link=None, subtitle=None, categories=None,
-
+, **kwargs
-        to_unicode = lambda s: force_unicode(s, strings_only=True)
-        if categories:
@@ -76 +77 @@
-            'ttl': ttl,
-        }
+        self.feed.update(kwargs)
-        self.items = []
-
-    def add_item(self, title, link, description, author_email=None,
-        author_name=None, author_link=None, pubdate=None, comments=None,
-
+
+
-        """
-        Adds an item to the feed. All args are expected to be Python Unicode
@@ -89 +92 @@
-        if categories:
-            categories = [to_unicode(c) for c in categories]
-self.items.append(
+item = 
-            'title': to_unicode(title),
-            'link': iri_to_uri(link),
@@ -103 +106 @@
-            'item_copyright': to_unicode(item_copyright),
-            'ttl': ttl,
-
+
+
+
-
-    def num_items(self):
-        return len(self.items)
-
+    def root_attributes(self):
+        """
+        Return extra attributes to place on the root (i.e. feed/channel) element.
+        Called from write().
+        """
+        return {}
+        
+    def add_root_elements(self, handler):
+        """
+        Add elements in the the root (i.e. feed/channel) element. Called 
+        from write().
+        """
+        pass
+        
+    def item_attributes(self, item):
+        """
+        Return extra attributes to place on each item (i.e. item/entry) element.
+        """
+        return {}
+        
+    def add_item_elements(self, handler, item):
+        """
+        Add elements on each item (i.e. item/entry) element.
+        """
+        pass
+        
-    def write(self, outfile, encoding):
-        """
@@ -149 +180 @@
-        handler.startDocument()
-        handler.startElement(u"rss", {u"version": self._version})
-
+
+
+
+
+
+
+
+
+
+
+
+
+
-        handler.addQuickElement(u"title", self.feed['title'])
-        handler.addQuickElement(u"link", self.feed['link'])
@@ -162 +205 @@
-        if self.feed['ttl'] is not None:
-            handler.addQuickElement(u"ttl", self.feed['ttl'])
-        self.write_items(handler)
-        self.endChannelElement(handler)
-        handler.endElement(u"rss")
-
-    def endChannelElement(self, handler):
@@ -171 +211 @@
-class RssUserland091Feed(RssFeed):
-    _version = u"0.91"
-
-
-
-
-
-
-
-
+
+
+
+
+
-
-class Rss201rev2Feed(RssFeed):
-    # Spec: http://blogs.law.harvard.edu/tech/rss
-    _version = u"2.0"
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-class Atom1Feed(SyndicationFeed):
@@ -225 +258 @@
-    mime_type = 'application/atom+xml'
-    ns = u"http://www.w3.org/2005/Atom"
+
-    def write(self, outfile, encoding):
-        handler = SimplerXMLGenerator(outfile, encoding)
-        handler.startDocument()
+        handler.startElement(u'feed', self.root_attributes())
+        self.add_root_elements(handler)
+        self.write_items(handler)
+        handler.endElement(u"feed")
+
+    def root_element_attributes(self):
-        if self.feed['language'] is not None:
-handler.startElement(u"feed", {u"xmlns": self.ns, u"xml:lang": self.feed['language']})
+return {u"xmlns": self.ns, u"xml:lang": self.feed['language']}
-        else:
-
+
+
+
-        handler.addQuickElement(u"title", self.feed['title'])
-        handler.addQuickElement(u"link", "", {u"rel": u"alternate", u"href": self.feed['link']})
@@ -252 +294 @@
-        if self.feed['feed_copyright'] is not None:
-            handler.addQuickElement(u"rights", self.feed['feed_copyright'])
-
-
-
+
-    def write_items(self, handler):
-        for item in self.items:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
-            handler.endElement(u"entry")
+            
+    def add_item_elements(self, handler, item):
+        handler.addQuickElement(u"title", item['title'])
+        handler.addQuickElement(u"link", u"", {u"href": item['link'], u"rel": u"alternate"})
+        if item['pubdate'] is not None:
+            handler.addQuickElement(u"updated", rfc3339_date(item['pubdate']).decode('ascii'))
+
+        # Author information.
+        if item['author_name'] is not None:
+            handler.startElement(u"author", {})
+            handler.addQuickElement(u"name", item['author_name'])
+            if item['author_email'] is not None:
+                handler.addQuickElement(u"email", item['author_email'])
+            if item['author_link'] is not None:
+                handler.addQuickElement(u"uri", item['author_link'])
+            handler.endElement(u"author")
+
+        # Unique ID.
+        if item['unique_id'] is not None:
+            unique_id = item['unique_id']
+        else:
+            unique_id = get_tag_uri(item['link'], item['pubdate'])
+        handler.addQuickElement(u"id", unique_id)
+
+        # Summary.
+        if item['description'] is not None:
+            handler.addQuickElement(u"summary", item['description'], {u"type": u"html"})
+
+        # Enclosure.
+        if item['enclosure'] is not None:
+            handler.addQuickElement(u"link", '',
+                {u"rel": u"enclosure",
+                 u"href": item['enclosure'].url,
+                 u"length": item['enclosure'].length,
+                 u"type": item['enclosure'].mime_type})
+
+        # Categories.
+        for cat in item['categories']:
+            handler.addQuickElement(u"category", u"", {u"term": cat})
+
+        # Rights.
+        if item['item_copyright'] is not None:
+            handler.addQuickElement(u"rights", item['item_copyright'])
-
-# This isolates the decision of what the system default is, so calling code can

django/trunk/docs/syndication_feeds.txt

@@ -802 +802 @@
-`django/utils/feedgenerator.py`_.
-
-
+
+
+
+
+
+
-
-The ``feedgenerator`` module contains a base class ``SyndicationFeed`` and
@@ -814 +819 @@
-They share this interface:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-    >>> from django.utils import feedgenerator
@@ -858 +896 @@
-    >>> print f.writeString('utf8')
-    <?xml version="1.0" encoding="utf8"?>
-
-
-
-
-
-
+
+
+
-
-.. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py
-.. _Python datetime object: http://www.python.org/doc/current/lib/module-datetime.html
+
+Custom feed generators
+----------------------
+
+If you need to produce a custom feed format, you've got a couple of options.
+    
+If the feed format is totally custom, you'll want to subclass
+``SyndicationFeed`` and completely replace the ``write()`` and
+``writeString()`` methods.
+
+However, if the feed format is a spin-off of RSS or Atom (i.e. GeoRSS_, Apple's
+`iTunes podcast format`_, etc.), you've got a better choice. These types of
+feeds typically add extra elements and/or attributes to the underlying format,
+and there are a set of methods that ``SyndicationFeed`` calls to get these extra
+attributes. Thus, you can subclass the appropriate feed generator class
+(``Atom1Feed`` or ``Rss201rev2Feed``) and extend these callbacks. They are:
+      
+.. _georss: http://georss.org/
+.. _itunes podcast format: http://www.apple.com/itunes/store/podcaststechspecs.html
+
+``SyndicationFeed.root_attributes(self, )``
+    Return a ``dict`` of attributes to add to the root feed element
+    (``feed``/``channel``).
+    
+``SyndicationFeed.add_root_elements(self, handler)``
+    Callback to add elements inside the root feed element
+    (``feed``/``channel``). ``handler`` is an `XMLGenerator`_ from Python's
+    built-in SAX library; you'll call methods on it to add to the XML
+    document in process.
+    
+``SyndicationFeed.item_attributes(self, item)``
+    Return a ``dict`` of attributes to add to each item (``item``/``entry``)
+    element. The argument, ``item``, is a dictionary of all the data passed to
+    ``SyndicationFeed.add_item()``.
+    
+``SyndicationFeed.add_item_elements(self, handler, item)``
+    Callback to add elements to each item (``item``/``entry``) element.
+    ``handler`` and ``item`` are as above.
+
+.. warning::
+
+    If you override any of these methods, be sure to call the superclass methods
+    since they add the required elements for each feed format.
+
+For example, you might start implementing an iTunes RSS feed generator like so::
+
+    class iTunesFeed(Rss201rev2Feed):
+        def root_attibutes(self):
+            attrs = super(iTunesFeed, self).root_attibutes()
+            attrs['xmlns:itunes'] = 'http://www.itunes.com/dtds/podcast-1.0.dtd
+            return attrs
+            
+        def add_root_elements(self, handler):
+            super(iTunesFeed, self).add_root_elements(handler)
+            handler.addQuickElement('itunes:explicit', 'clean')
+
+Obviously there's a lot more work to be done for a complete custom feed class,
+but the above example should demonstrate the basic idea.
+
+.. _XMLGenerator: http://docs.python.org/dev/library/xml.sax.utils.html#xml.sax.saxutils.XMLGenerator

django/trunk/tests/regressiontests/syndication/feeds.py

@@ -22 +22 @@
-class TestAtomFeed(TestRssFeed):
-    feed_type = Atom1Feed
+
+class MyCustomAtom1Feed(Atom1Feed):
+    """
+    Test of a custom feed generator class.
+    """    
+    def root_attributes(self):
+        attrs = super(MyCustomAtom1Feed, self).root_attributes()
+        attrs[u'django'] = u'rocks'
+        return attrs
+        
+    def add_root_elements(self, handler):
+        super(MyCustomAtom1Feed, self).add_root_elements(handler)
+        handler.addQuickElement(u'spam', u'eggs')
+        
+    def item_attributes(self, item):
+        attrs = super(MyCustomAtom1Feed, self).item_attributes(item)
+        attrs[u'bacon'] = u'yum'
+        return attrs
+        
+    def add_item_elements(self, handler, item):
+        super(MyCustomAtom1Feed, self).add_item_elements(handler, item)
+        handler.addQuickElement(u'ministry', u'silly walks')
+    
+class TestCustomFeed(TestAtomFeed):
+    feed_type = MyCustomAtom1Feed

django/trunk/tests/regressiontests/syndication/tests.py

@@ -5 +5 @@
-from django.test.client import Client
-from models import Entry
+try:
+    set
+except NameError:
+    from sets import Set as set
-
-class SyndicationFeedTest(TestCase):
-    fixtures = ['feeddata.json']
+
+    def assertChildNodes(self, elem, expected):
+        actual = set([n.nodeName for n in elem.childNodes])
+        expected = set(expected)
+        self.assertEqual(actual, expected)
-
-    def test_rss_feed(self):
@@ -13 +22 @@
-        doc = minidom.parseString(response.content)
-        self.assertEqual(len(doc.getElementsByTagName('channel')), 1)
-
+
+
+
+
+
+
+
+
-    
-    def test_atom_feed(self):
-        response = self.client.get('/syndication/feeds/atom/')
-        doc = minidom.parseString(response.content)
-
-
+
+
+
+
+
+
+
+
+
+
+
-    
+    def test_custom_feed_generator(self):
+        response = self.client.get('/syndication/feeds/custom/')
+        doc = minidom.parseString(response.content)
+        
+        feed = doc.firstChild
+        self.assertEqual(feed.nodeName, 'feed')
+        self.assertEqual(feed.getAttribute('django'), 'rocks')
+        self.assertChildNodes(feed, ['title', 'link', 'id', 'updated', 'entry', 'spam'])        
+        
+        entries = feed.getElementsByTagName('entry')
+        self.assertEqual(len(entries), Entry.objects.count())
+        for entry in entries:
+            self.assertEqual(entry.getAttribute('bacon'), 'yum')
+            self.assertChildNodes(entry, ['title', 'link', 'id', 'summary', 'ministry'])
+            summary = entry.getElementsByTagName('summary')[0]
+            self.assertEqual(summary.getAttribute('type'), 'html')
+        
-    def test_complex_base_url(self):
-        """

django/trunk/tests/regressiontests/syndication/urls.py

@@ -1 @@
-
+TestCustomFeed, 
-from django.conf.urls.defaults import patterns
-
@@ -6 +6 @@
-    'rss': TestRssFeed,
-    'atom': TestAtomFeed,
+    'custom': TestCustomFeed,
-    
-}