From 942e5246accda3d953b4634a010402ef5786c2e0 Mon Sep 17 00:00:00 2001 From: Jacob Kaplan-Moss Date: Mon, 11 Aug 2008 22:22:26 +0000 Subject: Added a number of callbacks to SyndicationFeed for adding custom attributes and elements to feeds. Refs #6547. git-svn-id: http://code.djangoproject.com/svn/django/trunk@8311 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/syndication_feeds.txt | 173 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 134 insertions(+), 39 deletions(-) (limited to 'docs') diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt index 6a603c4e54..ceb56a4788 100644 --- a/docs/syndication_feeds.txt +++ b/docs/syndication_feeds.txt @@ -801,7 +801,12 @@ Behind the scenes, the high-level RSS framework uses a lower-level framework for generating feeds' XML. This framework lives in a single module: `django/utils/feedgenerator.py`_. -Feel free to use this framework on your own, for lower-level tasks. +You use this framework on your own, for lower-level feed generation. You can +also create custom feed generator subclasses for use with the ``feed_type`` +``Feed`` option. + +``SyndicationFeed`` classes +--------------------------- The ``feedgenerator`` module contains a base class ``SyndicationFeed`` and several subclasses: @@ -813,38 +818,71 @@ several subclasses: Each of these three classes knows how to render a certain type of feed as XML. They share this interface: -``__init__(title, link, description, language=None, author_email=None,`` -``author_name=None, author_link=None, subtitle=None, categories=None,`` -``feed_url=None)`` - -Initializes the feed with the given metadata, which applies to the entire feed -(i.e., not just to a specific item in the feed). - -All parameters, if given, should be Unicode objects, except ``categories``, -which should be a sequence of Unicode objects. - -``add_item(title, link, description, author_email=None, author_name=None,`` -``pubdate=None, comments=None, unique_id=None, enclosure=None, categories=())`` - -Add an item to the feed with the given parameters. All parameters, if given, -should be Unicode objects, except: - - * ``pubdate`` should be a `Python datetime object`_. - * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``. - * ``categories`` should be a sequence of Unicode objects. - -``write(outfile, encoding)`` - -Outputs the feed in the given encoding to outfile, which is a file-like object. - -``writeString(encoding)`` - -Returns the feed as a string in the given encoding. - -Example usage -------------- - -This example creates an Atom 1.0 feed and prints it to standard output:: +``SyndicationFeed.__init__(**kwargs)`` + Initialize the feed with the given dictionary of metadata, which applies to + the entire feed. Required keyword arguments are: + + * ``title`` + * ``link`` + * ``description`` + + There's also a bunch of other optional keywords: + + * ``language`` + * ``author_email`` + * ``author_name`` + * ``author_link`` + * ``subtitle`` + * ``categories`` + * ``feed_url`` + * ``feed_copyright`` + * ``feed_guid`` + * ``ttl`` + + Any extra keyword arguments you pass to ``__init__`` will be stored in + ``self.feed`` for use with `custom feed generators`_. + + All parameters should be Unicode objects, except ``categories``, which + should be a sequence of Unicode objects. + +``SyndicationFeed.add_item(**kwargs)`` + Add an item to the feed with the given parameters. + + Required keyword arguments are: + + * ``title`` + * ``link`` + * ``description`` + + Optional keyword arguments are: + + * ``author_email`` + * ``author_name`` + * ``author_link`` + * ``pubdate`` + * ``comments`` + * ``unique_id`` + * ``enclosure`` + * ``categories`` + * ``item_copyright`` + * ``ttl`` + + Extra keyword arguments will be stored for `custom feed generators`_. + + All parameters, if given, should be Unicode objects, except: + + * ``pubdate`` should be a `Python datetime object`_. + * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``. + * ``categories`` should be a sequence of Unicode objects. + +``SyndicationFeed.write(outfile, encoding)`` + Outputs the feed in the given ``encoding`` to ``outfile``, which must be a + file-like object. + +``SyndicationFeed.writeString(encoding)`` + Returns the feed as a string in the given ``encoding``. + +For example, to create an Atom 1.0 feed and print it to standard output:: >>> from django.utils import feedgenerator >>> f = feedgenerator.Atom1Feed( @@ -857,12 +895,69 @@ This example creates an Atom 1.0 feed and prints it to standard output:: ... description=u"

Today I had a Vienna Beef hot dog. It was pink, plump and perfect.

") >>> print f.writeString('utf8') - My Weblog - http://www.example.com/ - Sat, 12 Nov 2005 00:28:43 -0000Hot dog today - http://www.example.com/entries/1/tag:www.example.com/entries/1/ - <p>Today I had a Vienna Beef hot dog. It was pink, plump and perfect.</p> - + + ... + .. _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 \ No newline at end of file -- cgit v1.3