docs/syndication_feeds.txt

   1 ==============================
   2 The syndication feed framework
   3 ==============================
   4
   5 Django comes with a high-level syndication-feed-generating framework that makes
   6 creating RSS_ and Atom_ feeds easy.
   7
   8 To create any syndication feed, all you have to do is write a short Python
   9 class. You can create as many feeds as you want.
  10
  11 Django also comes with a lower-level feed-generating API. Use this if you want
  12 to generate feeds outside of a Web context, or in some other lower-level way.
  13
  14 .. _RSS: http://www.whatisrss.com/
  15 .. _Atom: http://www.atomenabled.org/
  16
  17 The high-level framework
  18 ========================
  19
  20 Overview
  21 --------
  22
  23 The high-level feed-generating framework is a view that's hooked to ``/feeds/``
  24 by default. Django uses the remainder of the URL (everything after ``/feeds/``)
  25 to determine which feed to output.
  26
  27 To create a feed, just write a ``Feed`` class and point to it in your URLconf_.
  28
  29 .. _URLconf: ../url_dispatch/
  30
  31 Initialization
  32 --------------
  33
  34 If you're not using the latest Django development version, you'll need to make
  35 sure Django's sites framework is installed -- including its database table.
  36 (See the `sites framework documentation`_ for more information.) This has
  37 changed in the Django development version; the syndication feed framework no
  38 longer requires the sites framework.
  39
  40 To activate syndication feeds on your Django site, add this line to your
  41 URLconf_::
  42
  43     (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed', {'feed_dict': feeds}),
  44
  45 This tells Django to use the RSS framework to handle all URLs starting with
  46 ``"feeds/"``. (You can change that ``"feeds/"`` prefix to fit your own needs.)
  47
  48 This URLconf line has an extra argument: ``{'feed_dict': feeds}``. Use this
  49 extra argument to pass the syndication framework the feeds that should be
  50 published under that URL.
  51
  52 Specifically, ``feed_dict`` should be a dictionary that maps a feed's slug
  53 (short URL label) to its ``Feed`` class.
  54
  55 You can define the ``feed_dict`` in the URLconf itself. Here's a full example
  56 URLconf::
  57
  58     from django.conf.urls.defaults import *
  59     from myproject.feeds import LatestEntries, LatestEntriesByCategory
  60
  61     feeds = {
  62         'latest': LatestEntries,
  63         'categories': LatestEntriesByCategory,
  64     }
  65
  66     urlpatterns = patterns('',
  67         # ...
  68         (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
  69             {'feed_dict': feeds}),
  70         # ...
  71     )
  72
  73 The above example registers two feeds:
  74
  75     * The feed represented by ``LatestEntries`` will live at ``feeds/latest/``.
  76     * The feed represented by ``LatestEntriesByCategory`` will live at
  77       ``feeds/categories/``.
  78
  79 Once that's set up, you just need to define the ``Feed`` classes themselves.
  80
  81 .. _sites framework documentation: ../sites/
  82 .. _URLconf: ../url_dispatch/
  83 .. _settings file: ../settings/
  84
  85 Feed classes
  86 ------------
  87
  88 A ``Feed`` class is a simple Python class that represents a syndication feed.
  89 A feed can be simple (e.g., a "site news" feed, or a basic feed displaying
  90 the latest entries of a blog) or more complex (e.g., a feed displaying all the
  91 blog entries in a particular category, where the category is variable).
  92
  93 ``Feed`` classes must subclass ``django.contrib.syndication.feeds.Feed``. They
  94 can live anywhere in your codebase.
  95
  96 A simple example
  97 ----------------
  98
  99 This simple example, taken from `chicagocrime.org`_, describes a feed of the
 100 latest five news items::
 101
 102     from django.contrib.syndication.feeds import Feed
 103     from chicagocrime.models import NewsItem
 104
 105     class LatestEntries(Feed):
 106         title = "Chicagocrime.org site news"
 107         link = "/sitenews/"
 108         description = "Updates on changes and additions to chicagocrime.org."
 109
 110         def items(self):
 111             return NewsItem.objects.order_by('-pub_date')[:5]
 112
 113 Note:
 114
 115     * The class subclasses ``django.contrib.syndication.feeds.Feed``.
 116     * ``title``, ``link`` and ``description`` correspond to the standard
 117       RSS ``<title>``, ``<link>`` and ``<description>`` elements, respectively.
 118     * ``items()`` is, simply, a method that returns a list of objects that
 119       should be included in the feed as ``<item>`` elements. Although this
 120       example returns ``NewsItem`` objects using Django's
 121       `object-relational mapper`_, ``items()`` doesn't have to return model
 122       instances. Although you get a few bits of functionality "for free" by
 123       using Django models, ``items()`` can return any type of object you want.
 124     * If you're creating an Atom feed, rather than an RSS feed, set the
 125       ``subtitle`` attribute instead of the ``description`` attribute. See
 126       `Publishing Atom and RSS feeds in tandem`_, later, for an example.
 127
 128 One thing's left to do. In an RSS feed, each ``<item>`` has a ``<title>``,
 129 ``<link>`` and ``<description>``. We need to tell the framework what data to
 130 put into those elements.
 131
 132     * To specify the contents of ``<title>`` and ``<description>``, create
 133       `Django templates`_ called ``feeds/latest_title.html`` and
 134       ``feeds/latest_description.html``, where ``latest`` is the ``slug``
 135       specified in the URLconf for the given feed. Note the ``.html`` extension
 136       is required. The RSS system renders that template for each item, passing
 137       it two template context variables:
 138
 139           * ``{{ obj }}`` -- The current object (one of whichever objects you
 140             returned in ``items()``).
 141           * ``{{ site }}`` -- A ``django.contrib.sites.models.Site`` object
 142             representing the current site. This is useful for
 143             ``{{ site.domain }}`` or ``{{ site.name }}``. Note that if you're
 144             using the latest Django development version and do *not* have the
 145             Django sites framework installed, this will be set to a
 146             ``django.contrib.sites.models.RequestSite`` object. See the
 147             `RequestSite section of the sites framework documentation`_ for
 148             more.
 149
 150       If you don't create a template for either the title or description, the
 151       framework will use the template ``"{{ obj }}"`` by default -- that is,
 152       the normal string representation of the object. You can also change the
 153       names of these two templates by specifying ``title_template`` and
 154       ``description_template`` as attributes of your ``Feed`` class.
 155     * To specify the contents of ``<link>``, you have two options. For each
 156       item in ``items()``, Django first tries executing a
 157       ``get_absolute_url()`` method on that object. If that method doesn't
 158       exist, it tries calling a method ``item_link()`` in the ``Feed`` class,
 159       passing it a single parameter, ``item``, which is the object itself.
 160       Both ``get_absolute_url()`` and ``item_link()`` should return the item's
 161       URL as a normal Python string. As with ``get_absolute_url()``, the
 162       result of ``item_link()`` will be included directly in the URL, so you
 163       are responsible for doing all necessary URL quoting and conversion to
 164       ASCII inside the method itself.
 165
 166     * For the LatestEntries example above, we could have very simple feed templates:
 167
 168           * latest_title.html::
 169
 170              {{ obj.title }}
 171
 172           * latest_description.html::
 173
 174              {{ obj.description }}
 175
 176 .. _chicagocrime.org: http://www.chicagocrime.org/
 177 .. _object-relational mapper: ../db-api/
 178 .. _Django templates: ../templates/
 179 .. _RequestSite section of the sites framework documentation: ../sites/#requestsite-objects
 180
 181 A complex example
 182 -----------------
 183
 184 The framework also supports more complex feeds, via parameters.
 185
 186 For example, `chicagocrime.org`_ offers an RSS feed of recent crimes for every
 187 police beat in Chicago. It'd be silly to create a separate ``Feed`` class for
 188 each police beat; that would violate the `DRY principle`_ and would couple data
 189 to programming logic. Instead, the syndication framework lets you make generic
 190 feeds that output items based on information in the feed's URL.
 191
 192 On chicagocrime.org, the police-beat feeds are accessible via URLs like this:
 193
 194     * ``/rss/beats/0613/`` -- Returns recent crimes for beat 0613.
 195     * ``/rss/beats/1424/`` -- Returns recent crimes for beat 1424.
 196
 197 The slug here is ``"beats"``. The syndication framework sees the extra URL bits
 198 after the slug -- ``0613`` and ``1424`` -- and gives you a hook to tell it what
 199 those URL bits mean, and how they should influence which items get published in
 200 the feed.
 201
 202 An example makes this clear. Here's the code for these beat-specific feeds::
 203
 204     class BeatFeed(Feed):
 205         def get_object(self, bits):
 206             # In case of "/rss/beats/0613/foo/bar/baz/", or other such clutter,
 207             # check that bits has only one member.
 208             if len(bits) != 1:
 209                 raise ObjectDoesNotExist
 210             return Beat.objects.get(beat__exact=bits[0])
 211
 212         def title(self, obj):
 213             return "Chicagocrime.org: Crimes for beat %s" % obj.beat
 214
 215         def link(self, obj):
 216             return obj.get_absolute_url()
 217
 218         def description(self, obj):
 219             return "Crimes recently reported in police beat %s" % obj.beat
 220
 221         def items(self, obj):
 222             return Crime.objects.filter(beat__id__exact=obj.id).order_by('-crime_date')[:30]
 223
 224 Here's the basic algorithm the RSS framework follows, given this class and a
 225 request to the URL ``/rss/beats/0613/``:
 226
 227     * The framework gets the URL ``/rss/beats/0613/`` and notices there's
 228       an extra bit of URL after the slug. It splits that remaining string by
 229       the slash character (``"/"``) and calls the ``Feed`` class'
 230       ``get_object()`` method, passing it the bits. In this case, bits is
 231       ``['0613']``. For a request to ``/rss/beats/0613/foo/bar/``, bits would
 232       be ``['0613', 'foo', 'bar']``.
 233     * ``get_object()`` is responsible for retrieving the given beat, from the
 234       given ``bits``. In this case, it uses the Django database API to retrieve
 235       the beat. Note that ``get_object()`` should raise
 236       ``django.core.exceptions.ObjectDoesNotExist`` if given invalid
 237       parameters. There's no ``try``/``except`` around the
 238       ``Beat.objects.get()`` call, because it's not necessary; that function
 239       raises ``Beat.DoesNotExist`` on failure, and ``Beat.DoesNotExist`` is a
 240       subclass of ``ObjectDoesNotExist``. Raising ``ObjectDoesNotExist`` in
 241       ``get_object()`` tells Django to produce a 404 error for that request.
 242     * To generate the feed's ``<title>``, ``<link>`` and ``<description>``,
 243       Django uses the ``title()``, ``link()`` and ``description()`` methods. In
 244       the previous example, they were simple string class attributes, but this
 245       example illustrates that they can be either strings *or* methods. For
 246       each of ``title``, ``link`` and ``description``, Django follows this
 247       algorithm:
 248
 249           * First, it tries to call a method, passing the ``obj`` argument, where
 250             ``obj`` is the object returned by ``get_object()``.
 251           * Failing that, it tries to call a method with no arguments.
 252           * Failing that, it uses the class attribute.
 253
 254     * Finally, note that ``items()`` in this example also takes the ``obj``
 255       argument. The algorithm for ``items`` is the same as described in the
 256       previous step -- first, it tries ``items(obj)``, then ``items()``, then
 257       finally an ``items`` class attribute (which should be a list).
 258
 259 The ``ExampleFeed`` class below gives full documentation on methods and
 260 attributes of ``Feed`` classes.
 261
 262 .. _DRY principle: http://c2.com/cgi/wiki?DontRepeatYourself
 263
 264 Specifying the type of feed
 265 ---------------------------
 266
 267 By default, feeds produced in this framework use RSS 2.0.
 268
 269 To change that, add a ``feed_type`` attribute to your ``Feed`` class, like so::
 270
 271     from django.utils.feedgenerator import Atom1Feed
 272
 273     class MyFeed(Feed):
 274         feed_type = Atom1Feed
 275
 276 Note that you set ``feed_type`` to a class object, not an instance.
 277
 278 Currently available feed types are:
 279
 280     * ``django.utils.feedgenerator.Rss201rev2Feed`` (RSS 2.01. Default.)
 281     * ``django.utils.feedgenerator.RssUserland091Feed`` (RSS 0.91.)
 282     * ``django.utils.feedgenerator.Atom1Feed`` (Atom 1.0.)
 283
 284 Enclosures
 285 ----------
 286
 287 To specify enclosures, such as those used in creating podcast feeds, use the
 288 ``item_enclosure_url``, ``item_enclosure_length`` and
 289 ``item_enclosure_mime_type`` hooks. See the ``ExampleFeed`` class below for
 290 usage examples.
 291
 292 Language
 293 --------
 294
 295 Feeds created by the syndication framework automatically include the
 296 appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). This
 297 comes directly from your `LANGUAGE_CODE setting`_.
 298
 299 .. _LANGUAGE_CODE setting: ../settings/#language-code
 300
 301 URLs
 302 ----
 303
 304 The ``link`` method/attribute can return either an absolute URL (e.g.
 305 ``"/blog/"``) or a URL with the fully-qualified domain and protocol (e.g.
 306 ``"http://www.example.com/blog/"``). If ``link`` doesn't return the domain,
 307 the syndication framework will insert the domain of the current site, according
 308 to your `SITE_ID setting`_.
 309
 310 Atom feeds require a ``<link rel="self">`` that defines the feed's current
 311 location. The syndication framework populates this automatically, using the
 312 domain of the current site according to the SITE_ID setting.
 313
 314 .. _SITE_ID setting: ../settings/#site-id
 315
 316 Publishing Atom and RSS feeds in tandem
 317 ---------------------------------------
 318
 319 Some developers like to make available both Atom *and* RSS versions of their
 320 feeds. That's easy to do with Django: Just create a subclass of your ``Feed``
 321 class and set the ``feed_type`` to something different. Then update your
 322 URLconf to add the extra versions.
 323
 324 Here's a full example::
 325
 326     from django.contrib.syndication.feeds import Feed
 327     from chicagocrime.models import NewsItem
 328     from django.utils.feedgenerator import Atom1Feed
 329
 330     class RssSiteNewsFeed(Feed):
 331         title = "Chicagocrime.org site news"
 332         link = "/sitenews/"
 333         description = "Updates on changes and additions to chicagocrime.org."
 334
 335         def items(self):
 336             return NewsItem.objects.order_by('-pub_date')[:5]
 337
 338     class AtomSiteNewsFeed(RssSiteNewsFeed):
 339         feed_type = Atom1Feed
 340         subtitle = RssSiteNewsFeed.description
 341
 342 .. Note::
 343     In this example, the RSS feed uses a ``description`` while the Atom feed
 344     uses a ``subtitle``. That's because Atom feeds don't provide for a
 345     feed-level "description," but they *do* provide for a "subtitle."
 346
 347     If you provide a ``description`` in your ``Feed`` class, Django will *not*
 348     automatically put that into the ``subtitle`` element, because a subtitle
 349     and description are not necessarily the same thing. Instead, you should
 350     define a ``subtitle`` attribute.
 351
 352     In the above example, we simply set the Atom feed's ``subtitle`` to the
 353     RSS feed's ``description``, because it's quite short already.
 354
 355 And the accompanying URLconf::
 356
 357     from django.conf.urls.defaults import *
 358     from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed
 359
 360     feeds = {
 361         'rss': RssSiteNewsFeed,
 362         'atom': AtomSiteNewsFeed,
 363     }
 364
 365     urlpatterns = patterns('',
 366         # ...
 367         (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
 368             {'feed_dict': feeds}),
 369         # ...
 370     )
 371
 372 Feed class reference
 373 --------------------
 374
 375 This example illustrates all possible attributes and methods for a ``Feed`` class::
 376
 377     from django.contrib.syndication.feeds import Feed
 378     from django.utils import feedgenerator
 379
 380     class ExampleFeed(Feed):
 381
 382         # FEED TYPE -- Optional. This should be a class that subclasses
 383         # django.utils.feedgenerator.SyndicationFeed. This designates which
 384         # type of feed this should be: RSS 2.0, Atom 1.0, etc.
 385         # If you don't specify feed_type, your feed will be RSS 2.0.
 386         # This should be a class, not an instance of the class.
 387
 388         feed_type = feedgenerator.Rss201rev2Feed
 389
 390         # TEMPLATE NAMES -- Optional. These should be strings representing
 391         # names of Django templates that the system should use in rendering the
 392         # title and description of your feed items. Both are optional.
 393         # If you don't specify one, or either, Django will use the template
 394         # 'feeds/SLUG_title.html' and 'feeds/SLUG_description.html', where SLUG
 395         # is the slug you specify in the URL.
 396
 397         title_template = None
 398         description_template = None
 399
 400         # TITLE -- One of the following three is required. The framework looks
 401         # for them in this order.
 402
 403         def title(self, obj):
 404             """
 405             Takes the object returned by get_object() and returns the feed's
 406             title as a normal Python string.
 407             """
 408
 409         def title(self):
 410             """
 411             Returns the feed's title as a normal Python string.
 412             """
 413
 414         title = 'foo' # Hard-coded title.
 415
 416         # LINK -- One of the following three is required. The framework looks
 417         # for them in this order.
 418
 419         def link(self, obj):
 420             """
 421             Takes the object returned by get_object() and returns the feed's
 422             link as a normal Python string.
 423             """
 424
 425         def link(self):
 426             """
 427             Returns the feed's link as a normal Python string.
 428             """
 429
 430         link = '/foo/bar/' # Hard-coded link.
 431
 432         # GUID -- One of the following three is optional. The framework looks
 433         # for them in this order. This property is only used for Atom feeds
 434         # (where it is the feed-level ID element). If not provided, the feed
 435         # link is used as the ID.
 436         #
 437         # (New in Django development version)
 438
 439         def feed_guid(self, obj):
 440             """
 441             Takes the object returned by get_object() and returns the globally
 442             unique ID for the feed as a normal Python string.
 443             """
 444
 445         def feed_guid(self):
 446             """
 447             Returns the feed's globally unique ID as a normal Python string.
 448             """
 449
 450         feed_guid = '/foo/bar/1234' # Hard-coded guid.
 451
 452         # DESCRIPTION -- One of the following three is required. The framework
 453         # looks for them in this order.
 454
 455         def description(self, obj):
 456             """
 457             Takes the object returned by get_object() and returns the feed's
 458             description as a normal Python string.
 459             """
 460
 461         def description(self):
 462             """
 463             Returns the feed's description as a normal Python string.
 464             """
 465
 466         description = 'Foo bar baz.' # Hard-coded description.
 467
 468         # AUTHOR NAME --One of the following three is optional. The framework
 469         # looks for them in this order.
 470
 471         def author_name(self, obj):
 472             """
 473             Takes the object returned by get_object() and returns the feed's
 474             author's name as a normal Python string.
 475             """
 476
 477         def author_name(self):
 478             """
 479             Returns the feed's author's name as a normal Python string.
 480             """
 481
 482         author_name = 'Sally Smith' # Hard-coded author name.
 483
 484         # AUTHOR E-MAIL --One of the following three is optional. The framework
 485         # looks for them in this order.
 486
 487         def author_email(self, obj):
 488             """
 489             Takes the object returned by get_object() and returns the feed's
 490             author's e-mail as a normal Python string.
 491             """
 492
 493         def author_email(self):
 494             """
 495             Returns the feed's author's e-mail as a normal Python string.
 496             """
 497
 498         author_email = 'test@example.com' # Hard-coded author e-mail.
 499
 500         # AUTHOR LINK --One of the following three is optional. The framework
 501         # looks for them in this order. In each case, the URL should include
 502         # the "http://" and domain name.
 503
 504         def author_link(self, obj):
 505             """
 506             Takes the object returned by get_object() and returns the feed's
 507             author's URL as a normal Python string.
 508             """
 509
 510         def author_link(self):
 511             """
 512             Returns the feed's author's URL as a normal Python string.
 513             """
 514
 515         author_link = 'http://www.example.com/' # Hard-coded author URL.
 516
 517         # CATEGORIES -- One of the following three is optional. The framework
 518         # looks for them in this order. In each case, the method/attribute
 519         # should return an iterable object that returns strings.
 520
 521         def categories(self, obj):
 522             """
 523             Takes the object returned by get_object() and returns the feed's
 524             categories as iterable over strings.
 525             """
 526
 527         def categories(self):
 528             """
 529             Returns the feed's categories as iterable over strings.
 530             """
 531
 532         categories = ("python", "django") # Hard-coded list of categories.
 533
 534         # COPYRIGHT NOTICE -- One of the following three is optional. The
 535         # framework looks for them in this order.
 536
 537         def copyright(self, obj):
 538             """
 539             Takes the object returned by get_object() and returns the feed's
 540             copyright notice as a normal Python string.
 541             """
 542
 543         def copyright(self):
 544             """
 545             Returns the feed's copyright notice as a normal Python string.
 546             """
 547
 548         copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
 549
 550         # ITEMS -- One of the following three is required. The framework looks
 551         # for them in this order.
 552
 553         def items(self, obj):
 554             """
 555             Takes the object returned by get_object() and returns a list of
 556             items to publish in this feed.
 557             """
 558
 559         def items(self):
 560             """
 561             Returns a list of items to publish in this feed.
 562             """
 563
 564         items = ('Item 1', 'Item 2') # Hard-coded items.
 565
 566         # GET_OBJECT -- This is required for feeds that publish different data
 567         # for different URL parameters. (See "A complex example" above.)
 568
 569         def get_object(self, bits):
 570             """
 571             Takes a list of strings gleaned from the URL and returns an object
 572             represented by this feed. Raises
 573             django.core.exceptions.ObjectDoesNotExist on error.
 574             """
 575
 576         # ITEM LINK -- One of these three is required. The framework looks for
 577         # them in this order.
 578
 579         # First, the framework tries the get_absolute_url() method on each item
 580         # returned by items(). Failing that, it tries these two methods:
 581
 582         def item_link(self, item):
 583             """
 584             Takes an item, as returned by items(), and returns the item's URL.
 585             """
 586
 587         def item_link(self):
 588             """
 589             Returns the URL for every item in the feed.
 590             """
 591
 592         # ITEM_GUID -- The following method is optional. This property is
 593         # only used for Atom feeds (it is the ID element for an item in an
 594         # Atom feed). If not provided, the item's link is used by default.
 595         #
 596         # (New in Django development version)
 597
 598         def item_guid(self, obj):
 599             """
 600             Takes an item, as return by items(), and returns the item's ID.
 601             """
 602
 603         # ITEM AUTHOR NAME -- One of the following three is optional. The
 604         # framework looks for them in this order.
 605
 606         def item_author_name(self, item):
 607             """
 608             Takes an item, as returned by items(), and returns the item's
 609             author's name as a normal Python string.
 610             """
 611
 612         def item_author_name(self):
 613             """
 614             Returns the author name for every item in the feed.
 615             """
 616
 617         item_author_name = 'Sally Smith' # Hard-coded author name.
 618
 619         # ITEM AUTHOR E-MAIL --One of the following three is optional. The
 620         # framework looks for them in this order.
 621         #
 622         # If you specify this, you must specify item_author_name.
 623
 624         def item_author_email(self, obj):
 625             """
 626             Takes an item, as returned by items(), and returns the item's
 627             author's e-mail as a normal Python string.
 628             """
 629
 630         def item_author_email(self):
 631             """
 632             Returns the author e-mail for every item in the feed.
 633             """
 634
 635         item_author_email = 'test@example.com' # Hard-coded author e-mail.
 636
 637         # ITEM AUTHOR LINK --One of the following three is optional. The
 638         # framework looks for them in this order. In each case, the URL should
 639         # include the "http://" and domain name.
 640         #
 641         # If you specify this, you must specify item_author_name.
 642
 643         def item_author_link(self, obj):
 644             """
 645             Takes an item, as returned by items(), and returns the item's
 646             author's URL as a normal Python string.
 647             """
 648
 649         def item_author_link(self):
 650             """
 651             Returns the author URL for every item in the feed.
 652             """
 653
 654         item_author_link = 'http://www.example.com/' # Hard-coded author URL.
 655
 656         # ITEM ENCLOSURE URL -- One of these three is required if you're
 657         # publishing enclosures. The framework looks for them in this order.
 658
 659         def item_enclosure_url(self, item):
 660             """
 661             Takes an item, as returned by items(), and returns the item's
 662             enclosure URL.
 663             """
 664
 665         def item_enclosure_url(self):
 666             """
 667             Returns the enclosure URL for every item in the feed.
 668             """
 669
 670         item_enclosure_url = "/foo/bar.mp3" # Hard-coded enclosure link.
 671
 672         # ITEM ENCLOSURE LENGTH -- One of these three is required if you're
 673         # publishing enclosures. The framework looks for them in this order.
 674         # In each case, the returned value should be either an integer, or a
 675         # string representation of the integer, in bytes.
 676
 677         def item_enclosure_length(self, item):
 678             """
 679             Takes an item, as returned by items(), and returns the item's
 680             enclosure length.
 681             """
 682
 683         def item_enclosure_length(self):
 684             """
 685             Returns the enclosure length for every item in the feed.
 686             """
 687
 688         item_enclosure_length = 32000 # Hard-coded enclosure length.
 689
 690         # ITEM ENCLOSURE MIME TYPE -- One of these three is required if you're
 691         # publishing enclosures. The framework looks for them in this order.
 692
 693         def item_enclosure_mime_type(self, item):
 694             """
 695             Takes an item, as returned by items(), and returns the item's
 696             enclosure MIME type.
 697             """
 698
 699         def item_enclosure_mime_type(self):
 700             """
 701             Returns the enclosure MIME type for every item in the feed.
 702             """
 703
 704         item_enclosure_mime_type = "audio/mpeg" # Hard-coded enclosure MIME type.
 705
 706         # ITEM PUBDATE -- It's optional to use one of these three. This is a
 707         # hook that specifies how to get the pubdate for a given item.
 708         # In each case, the method/attribute should return a Python
 709         # datetime.datetime object.
 710
 711         def item_pubdate(self, item):
 712             """
 713             Takes an item, as returned by items(), and returns the item's
 714             pubdate.
 715             """
 716
 717         def item_pubdate(self):
 718             """
 719             Returns the pubdate for every item in the feed.
 720             """
 721
 722         item_pubdate = datetime.datetime(2005, 5, 3) # Hard-coded pubdate.
 723
 724         # ITEM CATEGORIES -- It's optional to use one of these three. This is
 725         # a hook that specifies how to get the list of categories for a given
 726         # item. In each case, the method/attribute should return an iterable
 727         # object that returns strings.
 728
 729         def item_categories(self, item):
 730             """
 731             Takes an item, as returned by items(), and returns the item's
 732             categories.
 733             """
 734
 735         def item_categories(self):
 736             """
 737             Returns the categories for every item in the feed.
 738             """
 739
 740         item_categories = ("python", "django") # Hard-coded categories.
 741
 742         # ITEM COPYRIGHT NOTICE (only applicable to Atom feeds) -- One of the
 743         # following three is optional. The framework looks for them in this
 744         # order.
 745
 746         def item_copyright(self, obj):
 747             """
 748             Takes an item, as returned by items(), and returns the item's
 749             copyright notice as a normal Python string.
 750             """
 751
 752         def item_copyright(self):
 753             """
 754             Returns the copyright notice for every item in the feed.
 755             """
 756
 757         item_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
 758
 759
 760 The low-level framework
 761 =======================
 762
 763 Behind the scenes, the high-level RSS framework uses a lower-level framework
 764 for generating feeds' XML. This framework lives in a single module:
 765 `django/utils/feedgenerator.py`_.
 766
 767 Feel free to use this framework on your own, for lower-level tasks.
 768
 769 The ``feedgenerator`` module contains a base class ``SyndicationFeed`` and
 770 several subclasses:
 771
 772     * ``RssUserland091Feed``
 773     * ``Rss201rev2Feed``
 774     * ``Atom1Feed``
 775
 776 Each of these three classes knows how to render a certain type of feed as XML.
 777 They share this interface:
 778
 779 ``__init__(title, link, description, language=None, author_email=None,``
 780 ``author_name=None, author_link=None, subtitle=None, categories=None,``
 781 ``feed_url=None)``
 782
 783 Initializes the feed with the given metadata, which applies to the entire feed
 784 (i.e., not just to a specific item in the feed).
 785
 786 All parameters, if given, should be Unicode objects, except ``categories``,
 787 which should be a sequence of Unicode objects.
 788
 789 ``add_item(title, link, description, author_email=None, author_name=None,``
 790 ``pubdate=None, comments=None, unique_id=None, enclosure=None, categories=())``
 791
 792 Add an item to the feed with the given parameters. All parameters, if given,
 793 should be Unicode objects, except:
 794
 795     * ``pubdate`` should be a `Python datetime object`_.
 796     * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``.
 797     * ``categories`` should be a sequence of Unicode objects.
 798
 799 ``write(outfile, encoding)``
 800
 801 Outputs the feed in the given encoding to outfile, which is a file-like object.
 802
 803 ``writeString(encoding)``
 804
 805 Returns the feed as a string in the given encoding.
 806
 807 Example usage
 808 -------------
 809
 810 This example creates an Atom 1.0 feed and prints it to standard output::
 811
 812     >>> from django.utils import feedgenerator
 813     >>> f = feedgenerator.Atom1Feed(
 814     ...     title=u"My Weblog",
 815     ...     link=u"http://www.example.com/",
 816     ...     description=u"In which I write about what I ate today.",
 817     ...     language=u"en")
 818     >>> f.add_item(title=u"Hot dog today",
 819     ...     link=u"http://www.example.com/entries/1/",
 820     ...     description=u"<p>Today I had a Vienna Beef hot dog. It was pink, plump and perfect.</p>")
 821     >>> print f.writeString('utf8')
 822     <?xml version="1.0" encoding="utf8"?>
 823     <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en"><title>My Weblog</title>
 824     <link href="http://www.example.com/"></link><id>http://www.example.com/</id>
 825     <updated>Sat, 12 Nov 2005 00:28:43 -0000</updated><entry><title>Hot dog today</title>
 826     <link>http://www.example.com/entries/1/</link><id>tag:www.example.com/entries/1/</id>
 827     <summary type="html">&lt;p&gt;Today I had a Vienna Beef hot dog. It was pink, plump and perfect.&lt;/p&gt;</summary>
 828     </entry></feed>
 829
 830 .. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py
 831 .. _Python datetime object: http://www.python.org/doc/current/lib/module-datetime.html