==============================

The syndication feed framework

==============================

.. module:: django.contrib.syndication

   :synopsis: A framework for generating syndication feeds, in RSS and Atom,

              quite easily.

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

========================

.. versionchanged:: 1.2

   The high-level feeds framework was refactored in Django 1.2. The

   pre-1.2 interface still exists, but it has been deprecated, and

   will be removed in Django 1.4. If you need to maintain an old-style

   Django feed, please consult the Django 1.1 documentation. For

   details on updating to use the new high-level feed framework, see

   the :ref:`Django 1.2 release notes <1.2-updating-feeds>`.

Overview

--------

The high-level feed-generating framework is supplied by the

:class:`~django.contrib.syndication.views.Feed` class. To create a

feed, write a :class:`~django.contrib.syndication.views.Feed` class

and point to an instance of it in your :doc:`URLconf

</topics/http/urls>`.

Feed classes

------------

A :class:`~django.contrib.syndication.views.Feed` class is a 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 subclass :class:`django.contrib.syndication.views.Feed`.

They can live anywhere in your codebase.

Instances of :class:`~django.contrib.syndication.views.Feed` classes

are views which can be used in your :doc:`URLconf </topics/http/urls>`.

A simple example

----------------

This simple example, taken from `chicagocrime.org`_, describes a feed of the

latest five news items::

    from django.contrib.syndication.views import Feed

    from chicagocrime.models import NewsItem

    class LatestEntriesFeed(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]

        def item_title(self, item):

            return item.title

        def item_description(self, item):

            return item.description

To connect a URL to this feed, put an instance of the Feed object in

your :doc:`URLconf </topics/http/urls>`. For example::

    from django.conf.urls.defaults import *

    from myproject.feeds import LatestEntriesFeed

    urlpatterns = patterns('',

        # ...

        (r'^latest/feed/$', LatestEntriesFeed()),

        # ...

    )

Note:

* The Feed class subclasses :class:`django.contrib.syndication.views.Feed`.

* :attr:`title`, :attr:`link` and :attr:`description` correspond to the

  standard RSS ``<title>``, ``<link>`` and ``<description>`` elements,

  respectively.

* :meth:`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

  :doc:`object-relational mapper </ref/models/querysets>`, :meth:`items()`

  doesn't have to return model instances. Although you get a few bits of

  functionality "for free" by using Django models, :meth:`items()` can

  return any type of object you want.

* If you're creating an Atom feed, rather than an RSS feed, set the

  :attr:`subtitle` attribute instead of the :attr:`description` attribute.

  See `Publishing Atom and RSS feeds in tandem`_, later, for an example.

One thing is 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.

    * For the contents of ``<title>`` and ``<description>``, Django tries

      calling the methods :meth:`item_title()` and :meth:`item_description()` on

      the :class:`~django.contrib.syndication.views.Feed` class. They are passed

      a single parameter, :attr:`item`, which is the object itself. These are

      optional; by default, the unicode representation of the object is used for

      both.

      If you want to do any special formatting for either the title or

      description, :doc:`Django templates </topics/templates>` can be used

      instead. Their paths can be specified with the ``title_template`` and

      ``description_template`` attributes on the

      :class:`~django.contrib.syndication.views.Feed` class. The templates are

      rendered for each item and are passed two template context variables:

         * ``{{ obj }}`` -- The current object (one of whichever objects you

           returned in :meth:`items()`).

         * ``{{ site }}`` -- A :class:`django.contrib.sites.models.Site` object

           representing the current site. This is useful for ``{{ site.domain

           }}`` or ``{{ site.name }}``. If you do *not* have the Django sites

           framework installed, this will be set to a

           :class:`django.contrib.sites.models.RequestSite` object. See the

           :ref:`RequestSite section of the sites framework documentation

           <requestsite-objects>` for more.

      See `a complex example`_ below that uses a description template.

    * To specify the contents of ``<link>``, you have two options. For each item

      in :meth:`items()`, Django first tries calling the

      :meth:`item_link()` method on the

      :class:`~django.contrib.syndication.views.Feed` class. In a similar way to

      the title and description, it is passed it a single parameter,

      :attr:`item`. If that method doesn't exist, Django tries executing a

      ``get_absolute_url()`` method on that object. Both

      :meth:`get_absolute_url()` and :meth:`item_link()` should return the

      item's URL as a normal Python string. As with ``get_absolute_url()``, the

      result of :meth:`item_link()` will be included directly in the URL, so you

      are responsible for doing all necessary URL quoting and conversion to

      ASCII inside the method itself.

.. _chicagocrime.org: http://www.chicagocrime.org/

A complex example

-----------------

The framework also supports more complex feeds, via arguments.

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

:class:`~django.contrib.syndication.views.Feed` class for each police beat; that

would violate the :ref:`DRY principle <dry>` and would couple data to

programming logic. Instead, the syndication framework lets you access the

arguments passed from your :doc:`URLconf </topics/http/urls>` so feeds can output

items based on information in the feed's URL.

On chicagocrime.org, the police-beat feeds are accessible via URLs like this:

    * :file:`/beats/613/rss/` -- Returns recent crimes for beat 613.

    * :file:`/beats/1424/rss/` -- Returns recent crimes for beat 1424.

These can be matched with a :doc:`URLconf </topics/http/urls>` line such as::

    (r'^beats/(?P<beat_id>\d+)/rss/$', BeatFeed()),

Like a view, the arguments in the URL are passed to the :meth:`get_object()`

method along with the request object.

.. versionchanged:: 1.2

   Prior to version 1.2, ``get_object()`` only accepted a ``bits`` argument.

Here's the code for these beat-specific feeds::

    from django.contrib.syndication.views import FeedDoesNotExist

    from django.shortcuts import get_object_or_404

    class BeatFeed(Feed):

        description_template = 'feeds/beat_description.html'

        def get_object(self, request, beat_id):

            return get_object_or_404(Beat, pk=beat_id)

        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=obj).order_by('-crime_date')[:30]

To generate the feed's ``<title>``, ``<link>`` and ``<description>``, Django

uses the :meth:`title()`, :meth:`link()` and :meth:`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

:attr:`title`, :attr:`link` and :attr:`description`, Django follows this

algorithm:

    * First, it tries to call a method, passing the ``obj`` argument, where

      ``obj`` is the object returned by :meth:`get_object()`.

    * Failing that, it tries to call a method with no arguments.

    * Failing that, it uses the class attribute.

Also note that :meth:`items()` also follows the same algorithm -- first, it

tries :meth:`items(obj)`, then :meth:`items()`, then finally an :attr:`items`

class attribute (which should be a list).

We are using a template for the item descriptions. It can be very simple:

.. code-block:: html+django

    {{ obj.description }}

However, you are free to add formatting as desired.

The ``ExampleFeed`` class below gives full documentation on methods and

attributes of :class:`~django.contrib.syndication.views.Feed` classes.

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

:class:`~django.contrib.syndication.views.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:

    * :class:`django.utils.feedgenerator.Rss201rev2Feed` (RSS 2.01. Default.)

    * :class:`django.utils.feedgenerator.RssUserland091Feed` (RSS 0.91.)

    * :class:`django.utils.feedgenerator.Atom1Feed` (Atom 1.0.)

Enclosures

----------

To specify enclosures, such as those used in creating podcast feeds, use the

:attr:`item_enclosure_url`, :attr:`item_enclosure_length` and

:attr:`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 :setting:`LANGUAGE_CODE` setting.

URLs

----

The :attr:`link` method/attribute can return either an absolute path (e.g.

:file:`"/blog/"`) or a URL with the fully-qualified domain and protocol (e.g.

``"http://www.example.com/blog/"``). If :attr:`link` doesn't return the domain,

the syndication framework will insert the domain of the current site, according

to your :setting:`SITE_ID setting <SITE_ID>`.

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 :setting:`SITE_ID` setting.

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

:class:`~django.contrib.syndication.views.Feed`

class and set the :attr:`feed_type` to something different. Then update your

URLconf to add the extra versions.

Here's a full example::

    from django.contrib.syndication.views 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

        subtitle = RssSiteNewsFeed.description

.. Note::

    In this example, the RSS feed uses a :attr:`description` while the Atom

    feed uses a :attr:`subtitle`. That's because Atom feeds don't provide for

    a feed-level "description," but they *do* provide for a "subtitle."

    If you provide a :attr:`description` in your

    :class:`~django.contrib.syndication.views.Feed` class, Django will *not*

    automatically put that into the :attr:`subtitle` element, because a

    subtitle and description are not necessarily the same thing. Instead, you

    should define a :attr:`subtitle` attribute.

    In the above example, we simply set the Atom feed's :attr:`subtitle` to the

    RSS feed's :attr:`description`, because it's quite short already.

And the accompanying URLconf::

    from django.conf.urls.defaults import *

    from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed

    urlpatterns = patterns('',

        # ...

        (r'^sitenews/rss/$', RssSiteNewsFeed()),

        (r'^sitenews/atom/$', AtomSiteNewsFeed()),

        # ...

    )

Feed class reference

--------------------

.. class:: django.contrib.syndication.views.Feed

This example illustrates all possible attributes and methods for a

:class:`~django.contrib.syndication.views.Feed` class::

    from django.contrib.syndication.views 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 a template is not specified, the

        # item_title() or item_description() methods are used instead.

        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.

        # GUID -- One of the following three is optional. The framework looks

        # for them in this order. This property is only used for Atom feeds

        # (where it is the feed-level ID element). If not provided, the feed

        # link is used as the ID.

        def feed_guid(self, obj):

            """

            Takes the object returned by get_object() and returns the globally

            unique ID for the feed as a normal Python string.

            """

        def feed_guid(self):

            """

            Returns the feed's globally unique ID as a normal Python string.

            """

        feed_guid = '/foo/bar/1234' # Hard-coded guid.

        # 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 feed_copyright(self, obj):

            """

            Takes the object returned by get_object() and returns the feed's

            copyright notice as a normal Python string.

            """

        def feed_copyright(self):

            """

            Returns the feed's copyright notice as a normal Python string.

            """

        feed_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.

        # TTL -- One of the following three is optional. The framework looks

        # for them in this order. Ignored for Atom feeds.

        def ttl(self, obj):

            """

            Takes the object returned by get_object() and returns the feed's

            TTL (Time To Live) as a normal Python string.

            """

        def ttl(self):

            """

            Returns the feed's TTL as a normal Python string.