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