py_tasks_melange: comparison thirdparty/google_appengine/lib/django/docs/syndication

equal deleted inserted replaced

-:261778de26ff
+:620f9b141567
+==============================
+The syndication feed framework
+==============================
+Django comes with a high-level syndication-feed-generating framework that makes
+creating RSS_ and Atom_ feeds easy.
+To create any syndication feed, all you have to do is write a short Python
+class. You can create as many feeds as you want.
+Django also comes with a lower-level feed-generating API. Use this if you want
+to generate feeds outside of a Web context, or in some other lower-level way.
+.. _RSS: http://www.whatisrss.com/
+.. _Atom: http://www.atomenabled.org/
+The high-level framework
+========================
+Overview
+--------
+The high-level feed-generating framework is a view that's hooked to ``/feeds/``
+by default. Django uses the remainder of the URL (everything after ``/feeds/``)
+to determine which feed to output.
+To create a feed, just write a ``Feed`` class and point to it in your URLconf_.
+.. _URLconf: ../url_dispatch/
+Initialization
+--------------
+To activate syndication feeds on your Django site, add this line to your
+URLconf_::
+(r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed', {'feed_dict': feeds}),
+This tells Django to use the RSS framework to handle all URLs starting with
+``"feeds/"``. (You can change that ``"feeds/"`` prefix to fit your own needs.)
+This URLconf line has an extra argument: ``{'feed_dict': feeds}``. Use this
+extra argument to pass the syndication framework the feeds that should be
+published under that URL.
+Specifically, ``feed_dict`` should be a dictionary that maps a feed's slug
+(short URL label) to its ``Feed`` class.
+You can define the ``feed_dict`` in the URLconf itself. Here's a full example
+URLconf::
+from django.conf.urls.defaults import *
+from myproject.feeds import LatestEntries, LatestEntriesByCategory
+feeds = {
+'latest': LatestEntries,
+'categories': LatestEntriesByCategory,
+}
+urlpatterns = patterns('',
+# ...
+(r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
+{'feed_dict': feeds}),
+# ...
+)
+The above example registers two feeds:
+* The feed represented by ``LatestEntries`` will live at ``feeds/latest/``.
+* The feed represented by ``LatestEntriesByCategory`` will live at
+``feeds/categories/``.
+Once that's set up, you just need to define the ``Feed`` classes themselves.
+.. _URLconf: ../url_dispatch/
+.. _settings file: ../settings/
+Feed classes
+------------
+A ``Feed`` class is a simple Python class that represents a syndication feed.
+A feed can be simple (e.g., a "site news" feed, or a basic feed displaying
+the latest entries of a blog) or more complex (e.g., a feed displaying all the
+blog entries in a particular category, where the category is variable).
+``Feed`` classes must subclass ``django.contrib.syndication.feeds.Feed``. They
+can live anywhere in your codebase.
+A simple example
+----------------
+This simple example, taken from `chicagocrime.org`_, describes a feed of the
+latest five news items::
+from django.contrib.syndication.feeds import Feed
+from chicagocrime.models import NewsItem
+class LatestEntries(Feed):
+title = "Chicagocrime.org site news"
+link = "/sitenews/"
+description = "Updates on changes and additions to chicagocrime.org."
+def items(self):
+return NewsItem.objects.order_by('-pub_date')[:5]
+Note:
+* The class subclasses ``django.contrib.syndication.feeds.Feed``.
+* ``title``, ``link`` and ``description`` correspond to the standard
+RSS ``<title>``, ``<link>`` and ``<description>`` elements, respectively.
+* ``items()`` is, simply, a method that returns a list of objects that
+should be included in the feed as ``<item>`` elements. Although this
+example returns ``NewsItem`` objects using Django's
+`object-relational mapper`_, ``items()`` doesn't have to return model
+instances. Although you get a few bits of functionality "for free" by
+using Django models, ``items()`` can return any type of object you want.
+One thing's left to do. In an RSS feed, each ``<item>`` has a ``<title>``,
+``<link>`` and ``<description>``. We need to tell the framework what data to
+put into those elements.
+* To specify the contents of ``<title>`` and ``<description>``, create
+`Django templates`_ called ``feeds/latest_title.html`` and
+``feeds/latest_description.html``, where ``latest`` is the ``slug``
+specified in the URLconf for the given feed. Note the ``.html`` extension
+is required. The RSS system renders that template for each item, passing
+it two template context variables:
+* ``{{ obj }}`` -- The current object (one of whichever objects you
+returned in ``items()``).
+* ``{{ site }}`` -- A ``django.models.core.sites.Site`` object
+representing the current site. This is useful for
+``{{ site.domain }}`` or ``{{ site.name }}``.
+If you don't create a template for either the title or description, the
+framework will use the template ``"{{ obj }}"`` by default -- that is,
+the normal string representation of the object. You can also change the
+names of these two templates by specifying ``title_template`` and
+``description_template`` as attributes of your ``Feed`` class.
+* To specify the contents of ``<link>``, you have two options. For each
+item in ``items()``, Django first tries executing a
+``get_absolute_url()`` method on that object. If that method doesn't
+exist, it tries calling a method ``item_link()`` in the ``Feed`` class,
+passing it a single parameter, ``item``, which is the object itself.
+Both ``get_absolute_url()`` and ``item_link()`` should return the item's
+URL as a normal Python string.
+* For the LatestEntries example above, we could have very simple feed templates:
+* latest_title.html::
+{{ obj.title }}
+* latest_description.html::
+{{ obj.description }}
+.. _chicagocrime.org: http://www.chicagocrime.org/
+.. _object-relational mapper: ../db_api/
+.. _Django templates: ../templates/
+A complex example
+-----------------
+The framework also supports more complex feeds, via parameters.
+For example, `chicagocrime.org`_ offers an RSS feed of recent crimes for every
+police beat in Chicago. It'd be silly to create a separate ``Feed`` class for
+each police beat; that would violate the `DRY principle`_ and would couple data
+to programming logic. Instead, the syndication framework lets you make generic
+feeds that output items based on information in the feed's URL.
+On chicagocrime.org, the police-beat feeds are accessible via URLs like this:
+* ``/rss/beats/0613/`` -- Returns recent crimes for beat 0613.
+* ``/rss/beats/1424/`` -- Returns recent crimes for beat 1424.
+The slug here is ``"beats"``. The syndication framework sees the extra URL bits
+after the slug -- ``0613`` and ``1424`` -- and gives you a hook to tell it what
+those URL bits mean, and how they should influence which items get published in
+the feed.
+An example makes this clear. Here's the code for these beat-specific feeds::
+class BeatFeed(Feed):
+def get_object(self, bits):
+# In case of "/rss/beats/0613/foo/bar/baz/", or other such clutter,
+# check that bits has only one member.
+if len(bits) != 1:
+raise ObjectDoesNotExist
+return Beat.objects.get(beat__exact=bits[0])
+def title(self, obj):
+return "Chicagocrime.org: Crimes for beat %s" % obj.beat
+def link(self, obj):
+return obj.get_absolute_url()
+def description(self, obj):
+return "Crimes recently reported in police beat %s" % obj.beat
+def items(self, obj):
+return Crime.objects.filter(beat__id__exact=obj.id).order_by('-crime_date')[:30]
+Here's the basic algorithm the RSS framework follows, given this class and a
+request to the URL ``/rss/beats/0613/``:
+* The framework gets the URL ``/rss/beats/0613/`` and notices there's
+an extra bit of URL after the slug. It splits that remaining string by
+the slash character (``"/"``) and calls the ``Feed`` class'
+``get_object()`` method, passing it the bits. In this case, bits is
+``['0613']``. For a request to ``/rss/beats/0613/foo/bar/``, bits would
+be ``['0613', 'foo', 'bar']``.
+* ``get_object()`` is responsible for retrieving the given beat, from the
+given ``bits``. In this case, it uses the Django database API to retrieve
+the beat. Note that ``get_object()`` should raise
+``django.core.exceptions.ObjectDoesNotExist`` if given invalid
+parameters. There's no ``try``/``except`` around the
+``Beat.objects.get()`` call, because it's not necessary; that function
+raises ``Beat.DoesNotExist`` on failure, and ``Beat.DoesNotExist`` is a
+subclass of ``ObjectDoesNotExist``. Raising ``ObjectDoesNotExist`` in
+``get_object()`` tells Django to produce a 404 error for that request.
+* To generate the feed's ``<title>``, ``<link>`` and ``<description>``,
+Django uses the ``title()``, ``link()`` and ``description()`` methods. In
+the previous example, they were simple string class attributes, but this
+example illustrates that they can be either strings *or* methods. For
+each of ``title``, ``link`` and ``description``, Django follows this
+algorithm:
+* First, it tries to call a method, passing the ``obj`` argument, where
+``obj`` is the object returned by ``get_object()``.
+* Failing that, it tries to call a method with no arguments.
+* Failing that, it uses the class attribute.
+* Finally, note that ``items()`` in this example also takes the ``obj``
+argument. The algorithm for ``items`` is the same as described in the
+previous step -- first, it tries ``items(obj)``, then ``items()``, then
+finally an ``items`` class attribute (which should be a list).
+The ``ExampleFeed`` class below gives full documentation on methods and
+attributes of ``Feed`` classes.
+.. _DRY principle: http://c2.com/cgi/wiki?DontRepeatYourself
+Specifying the type of feed
+---------------------------
+By default, feeds produced in this framework use RSS 2.0.
+To change that, add a ``feed_type`` attribute to your ``Feed`` class, like so::
+from django.utils.feedgenerator import Atom1Feed
+class MyFeed(Feed):
+feed_type = Atom1Feed
+Note that you set ``feed_type`` to a class object, not an instance.
+Currently available feed types are:
+* ``django.utils.feedgenerator.Rss201rev2Feed`` (RSS 2.01. Default.)
+* ``django.utils.feedgenerator.RssUserland091Feed`` (RSS 0.91.)
+* ``django.utils.feedgenerator.Atom1Feed`` (Atom 1.0.)
+Enclosures
+----------
+To specify enclosures, such as those used in creating podcast feeds, use the
+``item_enclosure_url``, ``item_enclosure_length`` and
+``item_enclosure_mime_type`` hooks. See the ``ExampleFeed`` class below for
+usage examples.
+Language
+--------
+Feeds created by the syndication framework automatically include the
+appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). This
+comes directly from your `LANGUAGE_CODE setting`_.
+.. _LANGUAGE_CODE setting: ../settings/#language-code
+URLs
+----
+The ``link`` method/attribute can return either an absolute URL (e.g.
+``"/blog/"``) or a URL with the fully-qualified domain and protocol (e.g.
+``"http://www.example.com/blog/"``). If ``link`` doesn't return the domain,
+the syndication framework will insert the domain of the current site, according
+to your `SITE_ID setting`_.
+Atom feeds require a ``<link rel="self">`` that defines the feed's current
+location. The syndication framework populates this automatically, using the
+domain of the current site according to the SITE_ID setting.
+.. _SITE_ID setting: ../settings/#site-id
+Publishing Atom and RSS feeds in tandem
+---------------------------------------
+Some developers like to make available both Atom *and* RSS versions of their
+feeds. That's easy to do with Django: Just create a subclass of your ``feed``
+class and set the ``feed_type`` to something different. Then update your
+URLconf to add the extra versions.
+Here's a full example::
+from django.contrib.syndication.feeds import Feed
+from chicagocrime.models import NewsItem
+from django.utils.feedgenerator import Atom1Feed
+class RssSiteNewsFeed(Feed):
+title = "Chicagocrime.org site news"
+link = "/sitenews/"
+description = "Updates on changes and additions to chicagocrime.org."
+def items(self):
+return NewsItem.objects.order_by('-pub_date')[:5]
+class AtomSiteNewsFeed(RssSiteNewsFeed):
+feed_type = Atom1Feed
+And the accompanying URLconf::
+from django.conf.urls.defaults import *
+from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed
+feeds = {
+'rss': RssSiteNewsFeed,
+'atom': AtomSiteNewsFeed,
+}
+urlpatterns = patterns('',
+# ...
+(r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
+{'feed_dict': feeds}),
+# ...
+)
+Feed class reference
+--------------------
+This example illustrates all possible attributes and methods for a ``Feed`` class::
+from django.contrib.syndication.feeds import Feed
+from django.utils import feedgenerator
+class ExampleFeed(Feed):
+# FEED TYPE -- Optional. This should be a class that subclasses
+# django.utils.feedgenerator.SyndicationFeed. This designates which
+# type of feed this should be: RSS 2.0, Atom 1.0, etc.
+# If you don't specify feed_type, your feed will be RSS 2.0.
+# This should be a class, not an instance of the class.
+feed_type = feedgenerator.Rss201rev2Feed
+# TEMPLATE NAMES -- Optional. These should be strings representing
+# names of Django templates that the system should use in rendering the
+# title and description of your feed items. Both are optional.
+# If you don't specify one, or either, Django will use the template
+# 'feeds/SLUG_title.html' and 'feeds/SLUG_description.html', where SLUG
+# is the slug you specify in the URL.
+title_template = None
+description_template = None
+# TITLE -- One of the following three is required. The framework looks
+# for them in this order.
+def title(self, obj):
+"""
+Takes the object returned by get_object() and returns the feed's
+title as a normal Python string.
+"""
+def title(self):
+"""
+Returns the feed's title as a normal Python string.
+"""
+title = 'foo' # Hard-coded title.
+# LINK -- One of the following three is required. The framework looks
+# for them in this order.
+def link(self, obj):
+"""
+Takes the object returned by get_object() and returns the feed's
+link as a normal Python string.
+"""
+def link(self):
+"""
+Returns the feed's link as a normal Python string.
+"""
+link = '/foo/bar/' # Hard-coded link.
+# DESCRIPTION -- One of the following three is required. The framework
+# looks for them in this order.
+def description(self, obj):
+"""
+Takes the object returned by get_object() and returns the feed's
+description as a normal Python string.
+"""
+def description(self):
+"""
+Returns the feed's description as a normal Python string.
+"""
+description = 'Foo bar baz.' # Hard-coded description.
+# AUTHOR NAME --One of the following three is optional. The framework
+# looks for them in this order.
+def author_name(self, obj):
+"""
+Takes the object returned by get_object() and returns the feed's
+author's name as a normal Python string.
+"""
+def author_name(self):
+"""
+Returns the feed's author's name as a normal Python string.
+"""
+author_name = 'Sally Smith' # Hard-coded author name.
+# AUTHOR E-MAIL --One of the following three is optional. The framework
+# looks for them in this order.
+def author_email(self, obj):
+"""
+Takes the object returned by get_object() and returns the feed's
+author's e-mail as a normal Python string.
+"""
+def author_email(self):
+"""
+Returns the feed's author's e-mail as a normal Python string.
+"""
+author_email = 'test@example.com' # Hard-coded author e-mail.
+# AUTHOR LINK --One of the following three is optional. The framework
+# looks for them in this order. In each case, the URL should include
+# the "http://" and domain name.
+def author_link(self, obj):
+"""
+Takes the object returned by get_object() and returns the feed's
+author's URL as a normal Python string.
+"""
+def author_link(self):
+"""
+Returns the feed's author's URL as a normal Python string.
+"""
+author_link = 'http://www.example.com/' # Hard-coded author URL.
+# CATEGORIES -- One of the following three is optional. The framework
+# looks for them in this order. In each case, the method/attribute
+# should return an iterable object that returns strings.
+def categories(self, obj):
+"""
+Takes the object returned by get_object() and returns the feed's
+categories as iterable over strings.
+"""
+def categories(self):
+"""
+Returns the feed's categories as iterable over strings.
+"""
+categories = ("python", "django") # Hard-coded list of categories.
+# COPYRIGHT NOTICE -- One of the following three is optional. The
+# framework looks for them in this order.
+def copyright(self, obj):
+"""
+Takes the object returned by get_object() and returns the feed's
+copyright notice as a normal Python string.
+"""
+def copyright(self):
+"""
+Returns the feed's copyright notice as a normal Python string.
+"""
+copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
+# ITEMS -- One of the following three is required. The framework looks
+# for them in this order.
+def items(self, obj):
+"""
+Takes the object returned by get_object() and returns a list of
+items to publish in this feed.
+"""
+def items(self):
+"""
+Returns a list of items to publish in this feed.
+"""
+items = ('Item 1', 'Item 2') # Hard-coded items.
+# GET_OBJECT -- This is required for feeds that publish different data
+# for different URL parameters. (See "A complex example" above.)
+def get_object(self, bits):
+"""
+Takes a list of strings gleaned from the URL and returns an object
+represented by this feed. Raises
+django.core.exceptions.ObjectDoesNotExist on error.
+"""
+# ITEM LINK -- One of these three is required. The framework looks for
+# them in this order.
+# First, the framework tries the get_absolute_url() method on each item
+# returned by items(). Failing that, it tries these two methods:
+def item_link(self, item):
+"""
+Takes an item, as returned by items(), and returns the item's URL.
+"""
+def item_link(self):
+"""
+Returns the URL for every item in the feed.
+"""
+# ITEM AUTHOR NAME --One of the following three is optional. The
+# framework looks for them in this order.
+def item_author_name(self, item):
+"""
+Takes an item, as returned by items(), and returns the item's
+author's name as a normal Python string.
+"""
+def item_author_name(self):
+"""
+Returns the author name for every item in the feed.
+"""
+item_author_name = 'Sally Smith' # Hard-coded author name.
+# ITEM AUTHOR E-MAIL --One of the following three is optional. The
+# framework looks for them in this order.
+#
+# If you specify this, you must specify item_author_name.
+def item_author_email(self, obj):
+"""
+Takes an item, as returned by items(), and returns the item's
+author's e-mail as a normal Python string.
+"""
+def item_author_email(self):
+"""
+Returns the author e-mail for every item in the feed.
+"""
+item_author_email = 'test@example.com' # Hard-coded author e-mail.
+# ITEM AUTHOR LINK --One of the following three is optional. The
+# framework looks for them in this order. In each case, the URL should
+# include the "http://" and domain name.
+#
+# If you specify this, you must specify item_author_name.
+def item_author_link(self, obj):
+"""
+Takes an item, as returned by items(), and returns the item's
+author's URL as a normal Python string.
+"""
+def item_author_link(self):
+"""
+Returns the author URL for every item in the feed.
+"""
+item_author_link = 'http://www.example.com/' # Hard-coded author URL.
+# ITEM ENCLOSURE URL -- One of these three is required if you're
+# publishing enclosures. The framework looks for them in this order.
+def item_enclosure_url(self, item):
+"""
+Takes an item, as returned by items(), and returns the item's
+enclosure URL.
+"""
+def item_enclosure_url(self):
+"""
+Returns the enclosure URL for every item in the feed.
+"""
+item_enclosure_url = "/foo/bar.mp3" # Hard-coded enclosure link.
+# ITEM ENCLOSURE LENGTH -- One of these three is required if you're
+# publishing enclosures. The framework looks for them in this order.
+# In each case, the returned value should be either an integer, or a
+# string representation of the integer, in bytes.
+def item_enclosure_length(self, item):
+"""
+Takes an item, as returned by items(), and returns the item's
+enclosure length.
+"""
+def item_enclosure_length(self):
+"""
+Returns the enclosure length for every item in the feed.
+"""
+item_enclosure_length = 32000 # Hard-coded enclosure length.
+# ITEM ENCLOSURE MIME TYPE -- One of these three is required if you're
+# publishing enclosures. The framework looks for them in this order.
+def item_enclosure_mime_type(self, item):
+"""
+Takes an item, as returned by items(), and returns the item's
+enclosure mime type.
+"""
+def item_enclosure_mime_type(self):
+"""
+Returns the enclosure length, in bytes, for every item in the feed.
+"""
+item_enclosure_mime_type = "audio/mpeg" # Hard-coded enclosure mime-type.
+# ITEM PUBDATE -- It's optional to use one of these three. This is a
+# hook that specifies how to get the pubdate for a given item.
+# In each case, the method/attribute should return a Python
+# datetime.datetime object.
+def item_pubdate(self, item):
+"""
+Takes an item, as returned by items(), and returns the item's
+pubdate.
+"""
+def item_pubdate(self):
+"""
+Returns the pubdate for every item in the feed.
+"""
+item_pubdate = datetime.datetime(2005, 5, 3) # Hard-coded pubdate.
+# ITEM CATEGORIES -- It's optional to use one of these three. This is
+# a hook that specifies how to get the list of categories for a given
+# item. In each case, the method/attribute should return an iterable
+# object that returns strings.
+def item_categories(self, item):
+"""
+Takes an item, as returned by items(), and returns the item's
+categories.
+"""
+def item_categories(self):
+"""
+Returns the categories for every item in the feed.
+"""
+item_categories = ("python", "django") # Hard-coded categories.
+# ITEM COPYRIGHT NOTICE (only applicable to Atom feeds) -- One of the
+# following three is optional. The framework looks for them in this
+# order.
+def item_copyright(self, obj):
+"""
+Takes an item, as returned by items(), and returns the item's
+copyright notice as a normal Python string.
+"""
+def item_copyright(self):
+"""
+Returns the copyright notice for every item in the feed.
+"""
+item_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
+The low-level framework
+=======================
+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.
+The ``feedgenerator`` module contains a base class ``SyndicationFeed`` and
+several subclasses:
+* ``RssUserland091Feed``
+* ``Rss201rev2Feed``
+* ``Atom1Feed``
+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::
+>>> from django.utils import feedgenerator
+>>> f = feedgenerator.Atom1Feed(
+...     title=u"My Weblog",
+...     link=u"http://www.example.com/",
+...     description=u"In which I write about what I ate today.",
+...     language=u"en")
+>>> f.add_item(title=u"Hot dog today",
+...     link=u"http://www.example.com/entries/1/",
+...     description=u"<p>Today I had a Vienna Beef hot dog. It was pink, plump and perfect.</p>")
+>>> print f.writeString('utf8')
+<?xml version="1.0" encoding="utf8"?>
+<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en"><title>My Weblog</title>
+<link href="http://www.example.com/"></link><id>http://www.example.com/</id>
+<updated>Sat, 12 Nov 2005 00:28:43 -0000</updated><entry><title>Hot dog today</title>
+<link>http://www.example.com/entries/1/</link><id>tag:www.example.com/entries/1/</id>
+<summary type="html">&lt;p&gt;Today I had a Vienna Beef hot dog. It was pink, plump and perfect.&lt;/p&gt;</summary>
+</entry></feed>
+.. _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