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     from django.contrib.syndication import FeedDoesNotExist
 205
 206     class BeatFeed(Feed):
 207         def get_object(self, bits):
 208             # In case of "/rss/beats/0613/foo/bar/baz/", or other such clutter,
 209             # check that bits has only one member.
 210             if len(bits) != 1:
 211                 raise ObjectDoesNotExist
 212             return Beat.objects.get(beat__exact=bits[0])
 213
 214         def title(self, obj):
 215             return "Chicagocrime.org: Crimes for beat %s" % obj.beat
 216
 217         def link(self, obj):
 218             if not obj:
 219                 raise FeedDoesNotExist
 220             return obj.get_absolute_url()
 221
 222         def description(self, obj):
 223             return "Crimes recently reported in police beat %s" % obj.beat
 224
 225         def items(self, obj):
 226             return Crime.objects.filter(beat__id__exact=obj.id).order_by('-crime_date')[:30]
 227
 228 Here's the basic algorithm the RSS framework follows, given this class and a
 229 request to the URL ``/rss/beats/0613/``:
 230
 231     * The framework gets the URL ``/rss/beats/0613/`` and notices there's
 232       an extra bit of URL after the slug. It splits that remaining string by
 233       the slash character (``"/"``) and calls the ``Feed`` class'
 234       ``get_object()`` method, passing it the bits. In this case, bits is
 235       ``['0613']``. For a request to ``/rss/beats/0613/foo/bar/``, bits would
 236       be ``['0613', 'foo', 'bar']``.
 237     * ``get_object()`` is responsible for retrieving the given beat, from the
 238       given ``bits``. In this case, it uses the Django database API to retrieve
 239       the beat. Note that ``get_object()`` should raise
 240       ``django.core.exceptions.ObjectDoesNotExist`` if given invalid
 241       parameters. There's no ``try``/``except`` around the
 242       ``Beat.objects.get()`` call, because it's not necessary; that function
 243       raises ``Beat.DoesNotExist`` on failure, and ``Beat.DoesNotExist`` is a
 244       subclass of ``ObjectDoesNotExist``. Raising ``ObjectDoesNotExist`` in
 245       ``get_object()`` tells Django to produce a 404 error for that request.
 246     * To generate the feed's ``<title>``, ``<link>`` and ``<description>``,
 247       Django uses the ``title()``, ``link()`` and ``description()`` methods. In
 248       the previous example, they were simple string class attributes, but this
 249       example illustrates that they can be either strings *or* methods. For
 250       each of ``title``, ``link`` and ``description``, Django follows this
 251       algorithm:
 252
 253           * First, it tries to call a method, passing the ``obj`` argument,
 254             where ``obj`` is the object returned by ``get_object()``.
 255           * Failing that, it tries to call a method with no arguments.
 256           * Failing that, it uses the class attribute.
 257
 258       Inside the ``link()`` method, we handle the possibility that ``obj``
 259       might be ``None``, which can occur when the URL isn't fully specified. In
 260       some cases, you might want to do something else in this case, which would
 261       mean you'd need to check for ``obj`` existing in other methods as well
 262       (the ``link()`` method is called very early in the feed generation
 263       process, so is a good place to bail out early).
 264
 265     * Finally, note that ``items()`` in this example also takes the ``obj``
 266       argument. The algorithm for ``items`` is the same as described in the
 267       previous step -- first, it tries ``items(obj)``, then ``items()``, then
 268       finally an ``items`` class attribute (which should be a list).
 269
 270 The ``ExampleFeed`` class below gives full documentation on methods and
 271 attributes of ``Feed`` classes.
 272
 273 .. _DRY principle: http://c2.com/cgi/wiki?DontRepeatYourself
 274
 275 Specifying the type of feed
 276 ---------------------------
 277
 278 By default, feeds produced in this framework use RSS 2.0.
 279
 280 To change that, add a ``feed_type`` attribute to your ``Feed`` class, like so::
 281
 282     from django.utils.feedgenerator import Atom1Feed
 283
 284     class MyFeed(Feed):
 285         feed_type = Atom1Feed
 286
 287 Note that you set ``feed_type`` to a class object, not an instance.
 288
 289 Currently available feed types are:
 290
 291     * ``django.utils.feedgenerator.Rss201rev2Feed`` (RSS 2.01. Default.)
 292     * ``django.utils.feedgenerator.RssUserland091Feed`` (RSS 0.91.)
 293     * ``django.utils.feedgenerator.Atom1Feed`` (Atom 1.0.)
 294
 295 Enclosures
 296 ----------
 297
 298 To specify enclosures, such as those used in creating podcast feeds, use the
 299 ``item_enclosure_url``, ``item_enclosure_length`` and
 300 ``item_enclosure_mime_type`` hooks. See the ``ExampleFeed`` class below for
 301 usage examples.
 302
 303 Language
 304 --------
 305
 306 Feeds created by the syndication framework automatically include the
 307 appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). This
 308 comes directly from your `LANGUAGE_CODE setting`_.
 309
 310 .. _LANGUAGE_CODE setting: ../settings/#language-code
 311
 312 URLs
 313 ----
 314
 315 The ``link`` method/attribute can return either an absolute URL (e.g.
 316 ``"/blog/"``) or a URL with the fully-qualified domain and protocol (e.g.
 317 ``"http://www.example.com/blog/"``). If ``link`` doesn't return the domain,
 318 the syndication framework will insert the domain of the current site, according
 319 to your `SITE_ID setting`_.
 320
 321 Atom feeds require a ``<link rel="self">`` that defines the feed's current
 322 location. The syndication framework populates this automatically, using the
 323 domain of the current site according to the SITE_ID setting.
 324
 325 .. _SITE_ID setting: ../settings/#site-id
 326
 327 Publishing Atom and RSS feeds in tandem
 328 ---------------------------------------
 329
 330 Some developers like to make available both Atom *and* RSS versions of their
 331 feeds. That's easy to do with Django: Just create a subclass of your ``Feed``
 332 class and set the ``feed_type`` to something different. Then update your
 333 URLconf to add the extra versions.
 334
 335 Here's a full example::
 336
 337     from django.contrib.syndication.feeds import Feed
 338     from chicagocrime.models import NewsItem
 339     from django.utils.feedgenerator import Atom1Feed
 340
 341     class RssSiteNewsFeed(Feed):
 342         title = "Chicagocrime.org site news"
 343         link = "/sitenews/"
 344         description = "Updates on changes and additions to chicagocrime.org."
 345
 346         def items(self):
 347             return NewsItem.objects.order_by('-pub_date')[:5]
 348
 349     class AtomSiteNewsFeed(RssSiteNewsFeed):
 350         feed_type = Atom1Feed
 351         subtitle = RssSiteNewsFeed.description
 352
 353 .. Note::
 354     In this example, the RSS feed uses a ``description`` while the Atom feed
 355     uses a ``subtitle``. That's because Atom feeds don't provide for a
 356     feed-level "description," but they *do* provide for a "subtitle."
 357
 358     If you provide a ``description`` in your ``Feed`` class, Django will *not*
 359     automatically put that into the ``subtitle`` element, because a subtitle
 360     and description are not necessarily the same thing. Instead, you should
 361     define a ``subtitle`` attribute.
 362
 363     In the above example, we simply set the Atom feed's ``subtitle`` to the
 364     RSS feed's ``description``, because it's quite short already.
 365
 366 And the accompanying URLconf::
 367
 368     from django.conf.urls.defaults import *
 369     from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed
 370
 371     feeds = {
 372         'rss': RssSiteNewsFeed,
 373         'atom': AtomSiteNewsFeed,
 374     }
 375
 376     urlpatterns = patterns('',
 377         # ...
 378         (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
 379             {'feed_dict': feeds}),
 380         # ...
 381     )
 382
 383 Feed class reference
 384 --------------------
 385
 386 This example illustrates all possible attributes and methods for a ``Feed`` class::
 387
 388     from django.contrib.syndication.feeds import Feed
 389     from django.utils import feedgenerator
 390
 391     class ExampleFeed(Feed):
 392
 393         # FEED TYPE -- Optional. This should be a class that subclasses
 394         # django.utils.feedgenerator.SyndicationFeed. This designates which
 395         # type of feed this should be: RSS 2.0, Atom 1.0, etc.
 396         # If you don't specify feed_type, your feed will be RSS 2.0.
 397         # This should be a class, not an instance of the class.
 398
 399         feed_type = feedgenerator.Rss201rev2Feed
 400
 401         # TEMPLATE NAMES -- Optional. These should be strings representing
 402         # names of Django templates that the system should use in rendering the
 403         # title and description of your feed items. Both are optional.
 404         # If you don't specify one, or either, Django will use the template
 405         # 'feeds/SLUG_title.html' and 'feeds/SLUG_description.html', where SLUG
 406         # is the slug you specify in the URL.
 407
 408         title_template = None
 409         description_template = None
 410
 411         # TITLE -- One of the following three is required. The framework looks
 412         # for them in this order.
 413
 414         def title(self, obj):
 415             """
 416             Takes the object returned by get_object() and returns the feed's
 417             title as a normal Python string.
 418             """
 419
 420         def title(self):
 421             """
 422             Returns the feed's title as a normal Python string.
 423             """
 424
 425         title = 'foo' # Hard-coded title.
 426
 427         # LINK -- One of the following three is required. The framework looks
 428         # for them in this order.
 429
 430         def link(self, obj):
 431             """
 432             Takes the object returned by get_object() and returns the feed's
 433             link as a normal Python string.
 434             """
 435
 436         def link(self):
 437             """
 438             Returns the feed's link as a normal Python string.
 439             """
 440
 441         link = '/foo/bar/' # Hard-coded link.
 442
 443         # GUID -- One of the following three is optional. The framework looks
 444         # for them in this order. This property is only used for Atom feeds
 445         # (where it is the feed-level ID element). If not provided, the feed
 446         # link is used as the ID.
 447         #
 448         # (New in Django development version)
 449
 450         def feed_guid(self, obj):
 451             """
 452             Takes the object returned by get_object() and returns the globally
 453             unique ID for the feed as a normal Python string.
 454             """
 455
 456         def feed_guid(self):
 457             """
 458             Returns the feed's globally unique ID as a normal Python string.
 459             """
 460
 461         feed_guid = '/foo/bar/1234' # Hard-coded guid.
 462
 463         # DESCRIPTION -- One of the following three is required. The framework
 464         # looks for them in this order.
 465
 466         def description(self, obj):
 467             """
 468             Takes the object returned by get_object() and returns the feed's
 469             description as a normal Python string.
 470             """
 471
 472         def description(self):
 473             """
 474             Returns the feed's description as a normal Python string.
 475             """
 476
 477         description = 'Foo bar baz.' # Hard-coded description.
 478
 479         # AUTHOR NAME --One of the following three is optional. The framework
 480         # looks for them in this order.
 481
 482         def author_name(self, obj):
 483             """
 484             Takes the object returned by get_object() and returns the feed's
 485             author's name as a normal Python string.
 486             """
 487
 488         def author_name(self):
 489             """
 490             Returns the feed's author's name as a normal Python string.
 491             """
 492
 493         author_name = 'Sally Smith' # Hard-coded author name.
 494
 495         # AUTHOR E-MAIL --One of the following three is optional. The framework
 496         # looks for them in this order.
 497
 498         def author_email(self, obj):
 499             """
 500             Takes the object returned by get_object() and returns the feed's
 501             author's e-mail as a normal Python string.
 502             """
 503
 504         def author_email(self):
 505             """
 506             Returns the feed's author's e-mail as a normal Python string.
 507             """
 508
 509         author_email = 'test@example.com' # Hard-coded author e-mail.
 510
 511         # AUTHOR LINK --One of the following three is optional. The framework
 512         # looks for them in this order. In each case, the URL should include
 513         # the "http://" and domain name.
 514
 515         def author_link(self, obj):
 516             """
 517             Takes the object returned by get_object() and returns the feed's
 518             author's URL as a normal Python string.
 519             """
 520
 521         def author_link(self):
 522             """
 523             Returns the feed's author's URL as a normal Python string.
 524             """
 525
 526         author_link = 'http://www.example.com/' # Hard-coded author URL.
 527
 528         # CATEGORIES -- One of the following three is optional. The framework
 529         # looks for them in this order. In each case, the method/attribute
 530         # should return an iterable object that returns strings.
 531
 532         def categories(self, obj):
 533             """
 534             Takes the object returned by get_object() and returns the feed's
 535             categories as iterable over strings.
 536             """
 537
 538         def categories(self):
 539             """
 540             Returns the feed's categories as iterable over strings.
 541             """
 542
 543         categories = ("python", "django") # Hard-coded list of categories.
 544
 545         # COPYRIGHT NOTICE -- One of the following three is optional. The
 546         # framework looks for them in this order.
 547
 548         def copyright(self, obj):
 549             """
 550             Takes the object returned by get_object() and returns the feed's
 551             copyright notice as a normal Python string.
 552             """
 553
 554         def copyright(self):
 555             """
 556             Returns the feed's copyright notice as a normal Python string.
 557             """
 558
 559         copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
 560
 561         # TTL -- One of the following three is optional. The framework looks
 562         # for them in this order. Ignored for Atom feeds.
 563
 564         def ttl(self, obj):
 565             """
 566             Takes the object returned by get_object() and returns the feed's
 567             TTL (Time To Live) as a normal Python string.
 568             """
 569
 570         def ttl(self):
 571             """
 572             Returns the feed's TTL as a normal Python string.
 573             """
 574
 575         ttl = 600 # Hard-coded Time To Live.
 576
 577         # ITEMS -- One of the following three is required. The framework looks
 578         # for them in this order.
 579
 580         def items(self, obj):
 581             """
 582             Takes the object returned by get_object() and returns a list of
 583             items to publish in this feed.
 584             """
 585
 586         def items(self):
 587             """
 588             Returns a list of items to publish in this feed.
 589             """
 590
 591         items = ('Item 1', 'Item 2') # Hard-coded items.
 592
 593         # GET_OBJECT -- This is required for feeds that publish different data
 594         # for different URL parameters. (See "A complex example" above.)
 595
 596         def get_object(self, bits):
 597             """
 598             Takes a list of strings gleaned from the URL and returns an object
 599             represented by this feed. Raises
 600             django.core.exceptions.ObjectDoesNotExist on error.
 601             """
 602
 603         # ITEM LINK -- One of these three is required. The framework looks for
 604         # them in this order.
 605
 606         # First, the framework tries the two methods below, in
 607         # order. Failing that, it falls back to the get_absolute_url()
 608         # method on each item returned by items().
 609
 610         def item_link(self, item):
 611             """
 612             Takes an item, as returned by items(), and returns the item's URL.
 613             """
 614
 615         def item_link(self):
 616             """
 617             Returns the URL for every item in the feed.
 618             """
 619
 620         # ITEM_GUID -- The following method is optional. This property is
 621         # only used for Atom feeds (it is the ID element for an item in an
 622         # Atom feed). If not provided, the item's link is used by default.
 623         #
 624         # (New in Django development version)
 625
 626         def item_guid(self, obj):
 627             """
 628             Takes an item, as return by items(), and returns the item's ID.
 629             """
 630
 631         # ITEM AUTHOR NAME -- One of the following three is optional. The
 632         # framework looks for them in this order.
 633
 634         def item_author_name(self, item):
 635             """
 636             Takes an item, as returned by items(), and returns the item's
 637             author's name as a normal Python string.
 638             """
 639
 640         def item_author_name(self):
 641             """
 642             Returns the author name for every item in the feed.
 643             """
 644
 645         item_author_name = 'Sally Smith' # Hard-coded author name.
 646
 647         # ITEM AUTHOR E-MAIL --One of the following three is optional. The
 648         # framework looks for them in this order.
 649         #
 650         # If you specify this, you must specify item_author_name.
 651
 652         def item_author_email(self, obj):
 653             """
 654             Takes an item, as returned by items(), and returns the item's
 655             author's e-mail as a normal Python string.
 656             """
 657
 658         def item_author_email(self):
 659             """
 660             Returns the author e-mail for every item in the feed.
 661             """
 662
 663         item_author_email = 'test@example.com' # Hard-coded author e-mail.
 664
 665         # ITEM AUTHOR LINK --One of the following three is optional. The
 666         # framework looks for them in this order. In each case, the URL should
 667         # include the "http://" and domain name.
 668         #
 669         # If you specify this, you must specify item_author_name.
 670
 671         def item_author_link(self, obj):
 672             """
 673             Takes an item, as returned by items(), and returns the item's
 674             author's URL as a normal Python string.
 675             """
 676
 677         def item_author_link(self):
 678             """
 679             Returns the author URL for every item in the feed.
 680             """
 681
 682         item_author_link = 'http://www.example.com/' # Hard-coded author URL.
 683
 684         # ITEM ENCLOSURE URL -- One of these three is required if you're
 685         # publishing enclosures. The framework looks for them in this order.
 686
 687         def item_enclosure_url(self, item):
 688             """
 689             Takes an item, as returned by items(), and returns the item's
 690             enclosure URL.
 691             """
 692
 693         def item_enclosure_url(self):
 694             """
 695             Returns the enclosure URL for every item in the feed.
 696             """
 697
 698         item_enclosure_url = "/foo/bar.mp3" # Hard-coded enclosure link.
 699
 700         # ITEM ENCLOSURE LENGTH -- One of these three is required if you're
 701         # publishing enclosures. The framework looks for them in this order.
 702         # In each case, the returned value should be either an integer, or a
 703         # string representation of the integer, in bytes.
 704
 705         def item_enclosure_length(self, item):
 706             """
 707             Takes an item, as returned by items(), and returns the item's
 708             enclosure length.
 709             """
 710
 711         def item_enclosure_length(self):
 712             """
 713             Returns the enclosure length for every item in the feed.
 714             """
 715
 716         item_enclosure_length = 32000 # Hard-coded enclosure length.
 717
 718         # ITEM ENCLOSURE MIME TYPE -- One of these three is required if you're
 719         # publishing enclosures. The framework looks for them in this order.
 720
 721         def item_enclosure_mime_type(self, item):
 722             """
 723             Takes an item, as returned by items(), and returns the item's
 724             enclosure MIME type.
 725             """
 726
 727         def item_enclosure_mime_type(self):
 728             """
 729             Returns the enclosure MIME type for every item in the feed.
 730             """
 731
 732         item_enclosure_mime_type = "audio/mpeg" # Hard-coded enclosure MIME type.
 733
 734         # ITEM PUBDATE -- It's optional to use one of these three. This is a
 735         # hook that specifies how to get the pubdate for a given item.
 736         # In each case, the method/attribute should return a Python
 737         # datetime.datetime object.
 738
 739         def item_pubdate(self, item):
 740             """
 741             Takes an item, as returned by items(), and returns the item's
 742             pubdate.
 743             """
 744
 745         def item_pubdate(self):
 746             """
 747             Returns the pubdate for every item in the feed.
 748             """
 749
 750         item_pubdate = datetime.datetime(2005, 5, 3) # Hard-coded pubdate.
 751
 752         # ITEM CATEGORIES -- It's optional to use one of these three. This is
 753         # a hook that specifies how to get the list of categories for a given
 754         # item. In each case, the method/attribute should return an iterable
 755         # object that returns strings.
 756
 757         def item_categories(self, item):
 758             """
 759             Takes an item, as returned by items(), and returns the item's
 760             categories.
 761             """
 762
 763         def item_categories(self):
 764             """
 765             Returns the categories for every item in the feed.
 766             """
 767
 768         item_categories = ("python", "django") # Hard-coded categories.
 769
 770         # ITEM COPYRIGHT NOTICE (only applicable to Atom feeds) -- One of the
 771         # following three is optional. The framework looks for them in this
 772         # order.
 773
 774         def item_copyright(self, obj):
 775             """
 776             Takes an item, as returned by items(), and returns the item's
 777             copyright notice as a normal Python string.
 778             """
 779
 780         def item_copyright(self):
 781             """
 782             Returns the copyright notice for every item in the feed.
 783             """
 784
 785         item_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
 786
 787
 788 The low-level framework
 789 =======================
 790
 791 Behind the scenes, the high-level RSS framework uses a lower-level framework
 792 for generating feeds' XML. This framework lives in a single module:
 793 `django/utils/feedgenerator.py`_.
 794
 795 Feel free to use this framework on your own, for lower-level tasks.
 796
 797 The ``feedgenerator`` module contains a base class ``SyndicationFeed`` and
 798 several subclasses:
 799
 800     * ``RssUserland091Feed``
 801     * ``Rss201rev2Feed``
 802     * ``Atom1Feed``
 803
 804 Each of these three classes knows how to render a certain type of feed as XML.
 805 They share this interface:
 806
 807 ``__init__(title, link, description, language=None, author_email=None,``
 808 ``author_name=None, author_link=None, subtitle=None, categories=None,``
 809 ``feed_url=None)``
 810
 811 Initializes the feed with the given metadata, which applies to the entire feed
 812 (i.e., not just to a specific item in the feed).
 813
 814 All parameters, if given, should be Unicode objects, except ``categories``,
 815 which should be a sequence of Unicode objects.
 816
 817 ``add_item(title, link, description, author_email=None, author_name=None,``
 818 ``pubdate=None, comments=None, unique_id=None, enclosure=None, categories=())``
 819
 820 Add an item to the feed with the given parameters. All parameters, if given,
 821 should be Unicode objects, except:
 822
 823     * ``pubdate`` should be a `Python datetime object`_.
 824     * ``enclosure`` should be an instance of ``feedgenerator.Enclosure``.
 825     * ``categories`` should be a sequence of Unicode objects.
 826
 827 ``write(outfile, encoding)``
 828
 829 Outputs the feed in the given encoding to outfile, which is a file-like object.
 830
 831 ``writeString(encoding)``
 832
 833 Returns the feed as a string in the given encoding.
 834
 835 Example usage
 836 -------------
 837
 838 This example creates an Atom 1.0 feed and prints it to standard output::
 839
 840     >>> from django.utils import feedgenerator
 841     >>> f = feedgenerator.Atom1Feed(
 842     ...     title=u"My Weblog",
 843     ...     link=u"http://www.example.com/",
 844     ...     description=u"In which I write about what I ate today.",
 845     ...     language=u"en")
 846     >>> f.add_item(title=u"Hot dog today",
 847     ...     link=u"http://www.example.com/entries/1/",
 848     ...     description=u"<p>Today I had a Vienna Beef hot dog. It was pink, plump and perfect.</p>")
 849     >>> print f.writeString('utf8')
 850     <?xml version="1.0" encoding="utf8"?>
 851     <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en"><title>My Weblog</title>
 852     <link href="http://www.example.com/"></link><id>http://www.example.com/</id>
 853     <updated>Sat, 12 Nov 2005 00:28:43 -0000</updated><entry><title>Hot dog today</title>
 854     <link>http://www.example.com/entries/1/</link><id>tag:www.example.com/entries/1/</id>
 855     <summary type="html">&lt;p&gt;Today I had a Vienna Beef hot dog. It was pink, plump and perfect.&lt;/p&gt;</summary>
 856     </entry></feed>
 857
 858 .. _django/utils/feedgenerator.py: http://code.djangoproject.com/browser/django/trunk/django/utils/feedgenerator.py
 859 .. _Python datetime object: http://www.python.org/doc/current/lib/module-datetime.html