Feed 聚合框架

Django 提供了一个高级的 feed 聚合生成框架来创建 RSS 和 Atom feed。

要创建任何聚合 feed，你只需要写一个简短的 Python 类。你可以创建任何你想要的 feed。

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.

高级框架

概况

高级 feed 生成框架由 Feed 类提供。要创建一个 feed，需要写一个 Feed 类，并在你的 URLconf 中指向它的一个实例。

Feed 类

Feed 类是一个 Python 类，它表示一个聚合 feed。Feed 可以是简单的（例如，一个“站点新闻”feed，或者一个显示博客最新条目的基本 feed），也可以是更复杂的（例如，一个显示特定类别中所有博客条目的 feed，其中类别是可变的）。

Feed 类子类 django.contrib.syndication.views.Feed。它们可以存在于你代码库的任何地方。

Feed 类的实例是可以在你的 URLconf 中使用的视图。

一个简单的例子

这个简单的例子，取自于一个假设的警拍新闻网站，描述了一个最新的五个新闻项目的 feed：

  1. from django.contrib.syndication.views import Feed
  2. from django.urls import reverse
  3. from policebeat.models import NewsItem
  5. class LatestEntriesFeed(Feed):
  6.     title = "Police beat site news"
  7.     link = "/sitenews/"
  8.     description = "Updates on changes and additions to police beat central."
  10.     def items(self):
  11.         return NewsItem.objects.order_by('-pub_date')[:5]
  13.     def item_title(self, item):
  14.         return item.title
  16.     def item_description(self, item):
  17.         return item.description
  19.     # item_link is only needed if NewsItem has no get_absolute_url method.
  20.     def item_link(self, item):
  21.         return reverse('news-item', args=[item.pk])

要连接到这个 feed 的 URL，在你的 URLconf 中放入一个 Feed 对象的实例。例如：

  1. from django.urls import path
  2. from myproject.feeds import LatestEntriesFeed
  4. urlpatterns = [
  5.     # ...
  6.     path('latest/feed/', LatestEntriesFeed()),
  7.     # ...
  8. ]

注意：

  • Feed 类的子类 django.contrib.syndication.views.Feed。
  • title、link 和 description 分别对应标准的 RSS <title>、<link> 和 <description> 元素。
  • items() 是一个返回一个应该作为 <item> 元素包含在 feed 中的对象列表的方法。虽然这个例子使用 Django 的 对象关系映射器 返回 NewsItem 对象，但是 items() 并不是一定要返回模型实例。虽然你通过使用Django模型得到了一些“免费”的功能，但 items() 可以返回任何类型的对象。
  • 如果你正在创建一个 Atom feed，而不是 RSS feed，请设置 subtitle 属性而不是 description 属性。参见后面的 同时发布 Atom 和 RSS feeds 的例子。

还剩下一件事要做。在一个 RSS Feed 中，每个 <item> 都有一个 <title>、<link> 和 <description>。我们需要告诉框架在这些元素中放入哪些数据。

  • 对于 <title> 和 <description> 的内容，Django 尝试在 Feed 类上调用方法 item_title() 和 item_description()。它们会传递一个单一的参数 item，也就是对象本身。这些参数是可选的；默认情况下，两者都使用对象的字符串表示。

    如果你想对标题或描述进行特定格式化，可以使用 Django 模板 来代替。它们的路径可以通过 Feed 类中的 title_template 和 description_template 属性来指定。每个项目的模板都会被渲染，并传递两个模板上下文变量。

    请看下面使用描述模板的 一个复杂的例子 。

    Feed.get_context_data(\*kwargs*)

    如果你需要提供比前面提到的两个变量更多的信息，还有一种方法可以向标题和描述模板传递额外的信息。你可以在你的 Feed 子类中提供 get_context_data 方法的实现。例如：

    1. from mysite.models import Article
    2. from django.contrib.syndication.views import Feed
    4. class ArticlesFeed(Feed):
    5.     title = "My articles"
    6.     description_template = "feeds/articles.html"
    8.     def items(self):
    9.         return Article.objects.order_by('-pub_date')[:5]
    11.     def get_context_data(self, **kwargs):
    12.         context = super().get_context_data(**kwargs)
    13.         context['foo'] = 'bar'
    14.         return context

    还有模板：

    1. Something about {{ foo }}: {{ obj.description }}

    本方法将对 items() 返回的列表中的每个项目调用一次，其关键字参数如下：

    • item：当前项目。出于向后兼容的原因，这个上下文变量的名称是 {{ obj }}。
    • obj：由 get_object() 返回的对象。默认情况下，它不会暴露在模板中，以避免与 {{ obj }} 混淆（见上文），但你可以在实现 get_context_data() 时使用它。
    • site：如上所述的当前站点。
    • request：当前请求。

    get_context_data() 的行为模仿 通用视图——你应该调用 super() 从父类中获取上下文数据，添加你的数据并返回修改后的字典。

  • 要指定 <link> 的内容，你有两个选择。对于 items() 中的每一个项目，Django 首先尝试调用 Feed 类上的 item_link() 方法。以类似于标题和描述的方式，给它传递一个单一的参数，item。如果该方法不存在，Django 会尝试在该对象上执行一个 get_absolute_url() 方法。get_absolute_url() 和 item_link() 都应该以普通 Python 字符串的形式返回项目的 URL。和 get_absolute_url() 一样，item_link() 的结果将直接包含在 URL 中，所以你要负责在方法本身内部进行所有必要的 URL 引用和 ASCII 转换。

一个复杂的例子

该框架还支持更复杂的 feed，通过参数。

例如，一个网站可以为一个城市的每一个警察局提供最近发生的犯罪行为的 RSS feed。如果为每个警察巡逻创建一个单独的 Feed 类，那就太傻了；那会违反 DRY 原则，并且会把数据和编程逻辑联系起来。相反，聚合框架让你访问从你的 URLconf 传递的参数，这样 feed 就可以根据 URL 中的信息输出项目。

可以通过这样的网址访问警察局 feed：

  • /beats/613/rss/ —— 返回 613 警察局的最近犯罪情况。
  • /beats/1424/rss/ —— 返回 1424 警察局的最近犯罪情况。

这些可以用 URLconf 行来匹配，如：

  1. path('beats/<int:beat_id>/rss/', BeatFeed()),

像视图一样，URL 中的参数和请求对象一起传递给 get_object() 方法。

以下是这些特定警察局 feed 的代码：

  1. from django.contrib.syndication.views import Feed
  3. class BeatFeed(Feed):
  4.     description_template = 'feeds/beat_description.html'
  6.     def get_object(self, request, beat_id):
  7.         return Beat.objects.get(pk=beat_id)
  9.     def title(self, obj):
  10.         return "Police beat central: Crimes for beat %s" % obj.beat
  12.     def link(self, obj):
  13.         return obj.get_absolute_url()
  15.     def description(self, obj):
  16.         return "Crimes recently reported in police beat %s" % obj.beat
  18.     def items(self, obj):
  19.         return Crime.objects.filter(beat=obj).order_by('-crime_date')[:30]

为了生成 feed 的 <title>、<link> 和 <description>，Django 使用了 title()、link() 和 description() 方法。在前面的例子中，它们是字符串类属性，但这个例子说明它们可以是字符串 或 方法。对于每一个 title、link 和``description``，Django 都遵循这个算法。

  • 首先，它试图调用一个方法，传递 obj 参数，其中 obj 是 get_object() 返回的对象。
  • 如果失败了，它就会尝试调用一个没有参数的方法。
  • 如果失败了，它就会使用类属性。

还请注意，items() 也遵循同样的算法——首先，它尝试 items(obj)，然后是 items()，最后是 items 类属性（应该是一个列表）。

我们是用一个模板来描述项目。可以是这样的最小化：

  1. {{ obj.description }}

但是，你可以根据需要自由添加格式。

下面的 ExampleFeed 类给出了关于 Feed 类的方法和属性的完整文档。

指定 feed 的类型

默认情况下，这个框架中产生的 feed 使用 RSS 2.0。

要改变这一点，可以在你的 Feed 类中添加一个 feed_type 属性，像这样：

  1. from django.utils.feedgenerator import Atom1Feed
  3. class MyFeed(Feed):
  4.     feed_type = Atom1Feed

请注意，你把 feed_type 设置为一个类对象，而不是一个实例。

目前可用的 feed 类型有：

封面

要指定封面，如创建播客 feed 时使用的封面，使用 item_enclosures 钩子，或者，如果每个项目只有一个封面，则使用 item_enclosure_url、item_enclosure_length 和 item_enclosure_mime_type` 钩子。请看下面的 ExampleFeed 类的使用示例。

语言

由聚合框架创建的 Feed 会自动包含相应的 <language> 标签（RSS 2.0）或 xml:lang 属性（Atom）。默认情况下，这是 django.utils.translation.get_language()。你可以通过设置 language 类属性来改变它。

URL

link 方法／属性可以返回一个绝对路径（例如 "/blog/"），也可以返回一个带有完全限定的域名和协议的 URL（例如 "https://www.example.com/blog/"）。如果 link 没有返回域名，聚合框架会根据你的 SITE_ID 配置，插入当前网站的域名。

Atom feeds 需要一个 <link rel="self">，定义 feed 的当前位置。聚合框架会根据 SITE_ID 设置，使用当前网站的域名自动填充。

同时发布 Atom 和 RSS feed

有些开发者喜欢同时提供 Atom 和 RSS 版本的 feed。要做到这一点，你可以创建一个 Feed 类的子类，并将 feed_type 设置为不同的内容。然后更新你的 URLconf 来添加额外的版本。

这有一个完整的例子：

  1. from django.contrib.syndication.views import Feed
  2. from policebeat.models import NewsItem
  3. from django.utils.feedgenerator import Atom1Feed
  5. class RssSiteNewsFeed(Feed):
  6.     title = "Police beat site news"
  7.     link = "/sitenews/"
  8.     description = "Updates on changes and additions to police beat central."
  10.     def items(self):
  11.         return NewsItem.objects.order_by('-pub_date')[:5]
  13. class AtomSiteNewsFeed(RssSiteNewsFeed):
  14.     feed_type = Atom1Feed
  15.     subtitle = RssSiteNewsFeed.description

注解

在这个例子中，RSS feed使用 description，而 Atom feed 使用 subtitle。这是因为 Atom feed 不提供 feed 级别的“描述”，但它们 提供 “副标题”。

如果你在你的 Feed 类中提供了一个 description，Django 不会自动将其放入 subtitle 元素中，因为副标题和描述不一定是一回事。相反，你应该定义一个 subtitle 属性。

在上面的例子中，我们将 Atom feed 的 subtitle 设置为 RSS feed 的 description，因为它已经很短了。

并附带 URLconf：

  1. from django.urls import path
  2. from myproject.feeds import AtomSiteNewsFeed, RssSiteNewsFeed
  4. urlpatterns = [
  5.     # ...
  6.     path('sitenews/rss/', RssSiteNewsFeed()),
  7.     path('sitenews/atom/', AtomSiteNewsFeed()),
  8.     # ...
  9. ]

Feed 类参考

class views.Feed

这个例子说明了 Feed 类的所有可能的属性和方法：

  1. from django.contrib.syndication.views import Feed
  2. from django.utils import feedgenerator
  4. class ExampleFeed(Feed):
  6.     # FEED TYPE -- Optional. This should be a class that subclasses
  7.     # django.utils.feedgenerator.SyndicationFeed. This designates
  8.     # which type of feed this should be: RSS 2.0, Atom 1.0, etc. If
  9.     # you don't specify feed_type, your feed will be RSS 2.0. This
  10.     # should be a class, not an instance of the class.
  12.     feed_type = feedgenerator.Rss201rev2Feed
  14.     # TEMPLATE NAMES -- Optional. These should be strings
  15.     # representing names of Django templates that the system should
  16.     # use in rendering the title and description of your feed items.
  17.     # Both are optional. If a template is not specified, the
  18.     # item_title() or item_description() methods are used instead.
  20.     title_template = None
  21.     description_template = None
  23.     # LANGUAGE -- Optional. This should be a string specifying a language
  24.     # code. Defaults to django.utils.translation.get_language().
  25.     language = 'de'
  27.     # TITLE -- One of the following three is required. The framework
  28.     # looks for them in this order.
  30.     def title(self, obj):
  31.         """
  32.         Takes the object returned by get_object() and returns the
  33.         feed's title as a normal Python string.
  34.         """
  36.     def title(self):
  37.         """
  38.         Returns the feed's title as a normal Python string.
  39.         """
  41.     title = 'foo' # Hard-coded title.
  43.     # LINK -- One of the following three is required. The framework
  44.     # looks for them in this order.
  46.     def link(self, obj):
  47.         """
  48.         # Takes the object returned by get_object() and returns the URL
  49.         # of the HTML version of the feed as a normal Python string.
  50.         """
  52.     def link(self):
  53.         """
  54.         Returns the URL of the HTML version of the feed as a normal Python
  55.         string.
  56.         """
  58.     link = '/blog/' # Hard-coded URL.
  60.     # FEED_URL -- One of the following three is optional. The framework
  61.     # looks for them in this order.
  63.     def feed_url(self, obj):
  64.         """
  65.         # Takes the object returned by get_object() and returns the feed's
  66.         # own URL as a normal Python string.
  67.         """
  69.     def feed_url(self):
  70.         """
  71.         Returns the feed's own URL as a normal Python string.
  72.         """
  74.     feed_url = '/blog/rss/' # Hard-coded URL.
  76.     # GUID -- One of the following three is optional. The framework looks
  77.     # for them in this order. This property is only used for Atom feeds
  78.     # (where it is the feed-level ID element). If not provided, the feed
  79.     # link is used as the ID.
  81.     def feed_guid(self, obj):
  82.         """
  83.         Takes the object returned by get_object() and returns the globally
  84.         unique ID for the feed as a normal Python string.
  85.         """
  87.     def feed_guid(self):
  88.         """
  89.         Returns the feed's globally unique ID as a normal Python string.
  90.         """
  92.     feed_guid = '/foo/bar/1234' # Hard-coded guid.
  94.     # DESCRIPTION -- One of the following three is required. The framework
  95.     # looks for them in this order.
  97.     def description(self, obj):
  98.         """
  99.         Takes the object returned by get_object() and returns the feed's
  100.         description as a normal Python string.
  101.         """
  103.     def description(self):
  104.         """
  105.         Returns the feed's description as a normal Python string.
  106.         """
  108.     description = 'Foo bar baz.' # Hard-coded description.
  110.     # AUTHOR NAME --One of the following three is optional. The framework
  111.     # looks for them in this order.
  113.     def author_name(self, obj):
  114.         """
  115.         Takes the object returned by get_object() and returns the feed's
  116.         author's name as a normal Python string.
  117.         """
  119.     def author_name(self):
  120.         """
  121.         Returns the feed's author's name as a normal Python string.
  122.         """
  124.     author_name = 'Sally Smith' # Hard-coded author name.
  126.     # AUTHOR EMAIL --One of the following three is optional. The framework
  127.     # looks for them in this order.
  129.     def author_email(self, obj):
  130.         """
  131.         Takes the object returned by get_object() and returns the feed's
  132.         author's email as a normal Python string.
  133.         """
  135.     def author_email(self):
  136.         """
  137.         Returns the feed's author's email as a normal Python string.
  138.         """
  140.     author_email = 'test@example.com' # Hard-coded author email.
  142.     # AUTHOR LINK --One of the following three is optional. The framework
  143.     # looks for them in this order. In each case, the URL should include
  144.     # the "http://" and domain name.
  146.     def author_link(self, obj):
  147.         """
  148.         Takes the object returned by get_object() and returns the feed's
  149.         author's URL as a normal Python string.
  150.         """
  152.     def author_link(self):
  153.         """
  154.         Returns the feed's author's URL as a normal Python string.
  155.         """
  157.     author_link = 'https://www.example.com/' # Hard-coded author URL.
  159.     # CATEGORIES -- One of the following three is optional. The framework
  160.     # looks for them in this order. In each case, the method/attribute
  161.     # should return an iterable object that returns strings.
  163.     def categories(self, obj):
  164.         """
  165.         Takes the object returned by get_object() and returns the feed's
  166.         categories as iterable over strings.
  167.         """
  169.     def categories(self):
  170.         """
  171.         Returns the feed's categories as iterable over strings.
  172.         """
  174.     categories = ("python", "django") # Hard-coded list of categories.
  176.     # COPYRIGHT NOTICE -- One of the following three is optional. The
  177.     # framework looks for them in this order.
  179.     def feed_copyright(self, obj):
  180.         """
  181.         Takes the object returned by get_object() and returns the feed's
  182.         copyright notice as a normal Python string.
  183.         """
  185.     def feed_copyright(self):
  186.         """
  187.         Returns the feed's copyright notice as a normal Python string.
  188.         """
  190.     feed_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
  192.     # TTL -- One of the following three is optional. The framework looks
  193.     # for them in this order. Ignored for Atom feeds.
  195.     def ttl(self, obj):
  196.         """
  197.         Takes the object returned by get_object() and returns the feed's
  198.         TTL (Time To Live) as a normal Python string.
  199.         """
  201.     def ttl(self):
  202.         """
  203.         Returns the feed's TTL as a normal Python string.
  204.         """
  206.     ttl = 600 # Hard-coded Time To Live.
  208.     # ITEMS -- One of the following three is required. The framework looks
  209.     # for them in this order.
  211.     def items(self, obj):
  212.         """
  213.         Takes the object returned by get_object() and returns a list of
  214.         items to publish in this feed.
  215.         """
  217.     def items(self):
  218.         """
  219.         Returns a list of items to publish in this feed.
  220.         """
  222.     items = ('Item 1', 'Item 2') # Hard-coded items.
  224.     # GET_OBJECT -- This is required for feeds that publish different data
  225.     # for different URL parameters. (See "A complex example" above.)
  227.     def get_object(self, request, *args, **kwargs):
  228.         """
  229.         Takes the current request and the arguments from the URL, and
  230.         returns an object represented by this feed. Raises
  231.         django.core.exceptions.ObjectDoesNotExist on error.
  232.         """
  234.     # ITEM TITLE AND DESCRIPTION -- If title_template or
  235.     # description_template are not defined, these are used instead. Both are
  236.     # optional, by default they will use the string representation of the
  237.     # item.
  239.     def item_title(self, item):
  240.         """
  241.         Takes an item, as returned by items(), and returns the item's
  242.         title as a normal Python string.
  243.         """
  245.     def item_title(self):
  246.         """
  247.         Returns the title for every item in the feed.
  248.         """
  250.     item_title = 'Breaking News: Nothing Happening' # Hard-coded title.
  252.     def item_description(self, item):
  253.         """
  254.         Takes an item, as returned by items(), and returns the item's
  255.         description as a normal Python string.
  256.         """
  258.     def item_description(self):
  259.         """
  260.         Returns the description for every item in the feed.
  261.         """
  263.     item_description = 'A description of the item.' # Hard-coded description.
  265.     def get_context_data(self, **kwargs):
  266.         """
  267.         Returns a dictionary to use as extra context if either
  268.         description_template or item_template are used.
  270.         Default implementation preserves the old behavior
  271.         of using {'obj': item, 'site': current_site} as the context.
  272.         """
  274.     # ITEM LINK -- One of these three is required. The framework looks for
  275.     # them in this order.
  277.     # First, the framework tries the two methods below, in
  278.     # order. Failing that, it falls back to the get_absolute_url()
  279.     # method on each item returned by items().
  281.     def item_link(self, item):
  282.         """
  283.         Takes an item, as returned by items(), and returns the item's URL.
  284.         """
  286.     def item_link(self):
  287.         """
  288.         Returns the URL for every item in the feed.
  289.         """
  291.     # ITEM_GUID -- The following method is optional. If not provided, the
  292.     # item's link is used by default.
  294.     def item_guid(self, obj):
  295.         """
  296.         Takes an item, as return by items(), and returns the item's ID.
  297.         """
  299.     # ITEM_GUID_IS_PERMALINK -- The following method is optional. If
  300.     # provided, it sets the 'isPermaLink' attribute of an item's
  301.     # GUID element. This method is used only when 'item_guid' is
  302.     # specified.
  304.     def item_guid_is_permalink(self, obj):
  305.         """
  306.         Takes an item, as returned by items(), and returns a boolean.
  307.         """
  309.     item_guid_is_permalink = False  # Hard coded value
  311.     # ITEM AUTHOR NAME -- One of the following three is optional. The
  312.     # framework looks for them in this order.
  314.     def item_author_name(self, item):
  315.         """
  316.         Takes an item, as returned by items(), and returns the item's
  317.         author's name as a normal Python string.
  318.         """
  320.     def item_author_name(self):
  321.         """
  322.         Returns the author name for every item in the feed.
  323.         """
  325.     item_author_name = 'Sally Smith' # Hard-coded author name.
  327.     # ITEM AUTHOR EMAIL --One of the following three is optional. The
  328.     # framework looks for them in this order.
  329.     #
  330.     # If you specify this, you must specify item_author_name.
  332.     def item_author_email(self, obj):
  333.         """
  334.         Takes an item, as returned by items(), and returns the item's
  335.         author's email as a normal Python string.
  336.         """
  338.     def item_author_email(self):
  339.         """
  340.         Returns the author email for every item in the feed.
  341.         """
  343.     item_author_email = 'test@example.com' # Hard-coded author email.
  345.     # ITEM AUTHOR LINK -- One of the following three is optional. The
  346.     # framework looks for them in this order. In each case, the URL should
  347.     # include the "http://" and domain name.
  348.     #
  349.     # If you specify this, you must specify item_author_name.
  351.     def item_author_link(self, obj):
  352.         """
  353.         Takes an item, as returned by items(), and returns the item's
  354.         author's URL as a normal Python string.
  355.         """
  357.     def item_author_link(self):
  358.         """
  359.         Returns the author URL for every item in the feed.
  360.         """
  362.     item_author_link = 'https://www.example.com/' # Hard-coded author URL.
  364.     # ITEM ENCLOSURES -- One of the following three is optional. The
  365.     # framework looks for them in this order. If one of them is defined,
  366.     # ``item_enclosure_url``, ``item_enclosure_length``, and
  367.     # ``item_enclosure_mime_type`` will have no effect.
  369.     def item_enclosures(self, item):
  370.         """
  371.         Takes an item, as returned by items(), and returns a list of
  372.         ``django.utils.feedgenerator.Enclosure`` objects.
  373.         """
  375.     def item_enclosures(self):
  376.         """
  377.         Returns the ``django.utils.feedgenerator.Enclosure`` list for every
  378.         item in the feed.
  379.         """
  381.     item_enclosures = []  # Hard-coded enclosure list
  383.     # ITEM ENCLOSURE URL -- One of these three is required if you're
  384.     # publishing enclosures and you're not using ``item_enclosures``. The
  385.     # framework looks for them in this order.
  387.     def item_enclosure_url(self, item):
  388.         """
  389.         Takes an item, as returned by items(), and returns the item's
  390.         enclosure URL.
  391.         """
  393.     def item_enclosure_url(self):
  394.         """
  395.         Returns the enclosure URL for every item in the feed.
  396.         """
  398.     item_enclosure_url = "/foo/bar.mp3" # Hard-coded enclosure link.
  400.     # ITEM ENCLOSURE LENGTH -- One of these three is required if you're
  401.     # publishing enclosures and you're not using ``item_enclosures``. The
  402.     # framework looks for them in this order. In each case, the returned
  403.     # value should be either an integer, or a string representation of the
  404.     # integer, in bytes.
  406.     def item_enclosure_length(self, item):
  407.         """
  408.         Takes an item, as returned by items(), and returns the item's
  409.         enclosure length.
  410.         """
  412.     def item_enclosure_length(self):
  413.         """
  414.         Returns the enclosure length for every item in the feed.
  415.         """
  417.     item_enclosure_length = 32000 # Hard-coded enclosure length.
  419.     # ITEM ENCLOSURE MIME TYPE -- One of these three is required if you're
  420.     # publishing enclosures and you're not using ``item_enclosures``. The
  421.     # framework looks for them in this order.
  423.     def item_enclosure_mime_type(self, item):
  424.         """
  425.         Takes an item, as returned by items(), and returns the item's
  426.         enclosure MIME type.
  427.         """
  429.     def item_enclosure_mime_type(self):
  430.         """
  431.         Returns the enclosure MIME type for every item in the feed.
  432.         """
  434.     item_enclosure_mime_type = "audio/mpeg" # Hard-coded enclosure MIME type.
  436.     # ITEM PUBDATE -- It's optional to use one of these three. This is a
  437.     # hook that specifies how to get the pubdate for a given item.
  438.     # In each case, the method/attribute should return a Python
  439.     # datetime.datetime object.
  441.     def item_pubdate(self, item):
  442.         """
  443.         Takes an item, as returned by items(), and returns the item's
  444.         pubdate.
  445.         """
  447.     def item_pubdate(self):
  448.         """
  449.         Returns the pubdate for every item in the feed.
  450.         """
  452.     item_pubdate = datetime.datetime(2005, 5, 3) # Hard-coded pubdate.
  454.     # ITEM UPDATED -- It's optional to use one of these three. This is a
  455.     # hook that specifies how to get the updateddate for a given item.
  456.     # In each case, the method/attribute should return a Python
  457.     # datetime.datetime object.
  459.     def item_updateddate(self, item):
  460.         """
  461.         Takes an item, as returned by items(), and returns the item's
  462.         updateddate.
  463.         """
  465.     def item_updateddate(self):
  466.         """
  467.         Returns the updateddate for every item in the feed.
  468.         """
  470.     item_updateddate = datetime.datetime(2005, 5, 3) # Hard-coded updateddate.
  472.     # ITEM CATEGORIES -- It's optional to use one of these three. This is
  473.     # a hook that specifies how to get the list of categories for a given
  474.     # item. In each case, the method/attribute should return an iterable
  475.     # object that returns strings.
  477.     def item_categories(self, item):
  478.         """
  479.         Takes an item, as returned by items(), and returns the item's
  480.         categories.
  481.         """
  483.     def item_categories(self):
  484.         """
  485.         Returns the categories for every item in the feed.
  486.         """
  488.     item_categories = ("python", "django") # Hard-coded categories.
  490.     # ITEM COPYRIGHT NOTICE (only applicable to Atom feeds) -- One of the
  491.     # following three is optional. The framework looks for them in this
  492.     # order.
  494.     def item_copyright(self, obj):
  495.         """
  496.         Takes an item, as returned by items(), and returns the item's
  497.         copyright notice as a normal Python string.
  498.         """
  500.     def item_copyright(self):
  501.         """
  502.         Returns the copyright notice for every item in the feed.
  503.         """
  505.     item_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
  507.     # ITEM COMMENTS URL -- It's optional to use one of these three. This is
  508.     # a hook that specifies how to get the URL of a page for comments for a
  509.     # given item.
  511.     def item_comments(self, obj):
  512.         """
  513.         Takes an item, as returned by items(), and returns the item's
  514.         comments URL as a normal Python string.
  515.         """
  517.     def item_comments(self):
  518.         """
  519.         Returns the comments URL for every item in the feed.
  520.         """
  522.     item_comments = 'https://www.example.com/comments' # Hard-coded comments URL

Changed in Django 3.2:

通过 item_comments 钩子增加了对每个 feed 项目的评论 URL 的支持。

低级框架

在幕后，高级 RSS 框架使用一个低级框架来生成 feed 的 XML。这个框架存在于一个模块中：django/utils/feedgenerator.py。

你可以自己使用这个框架，进行低级的 feed 生成。你也可以创建自定义的 feed 生成器子类，用于 feed_type Feed 选项。

SyndicationFeed 类

feedgenerator 模块包含一个基类：

和几个子类：

这三个类中的每一个都知道如何将某种类型的 feed 渲染成 XML。它们共享这个接口：

SyndicationFeed.__init__()

用给定的元数据字典初始化 feed，该字典适用于整个 feed。所需的关键字参数有：

  • title
  • link
  • description

还有一堆其他可选的关键词：

  • language
  • author_email
  • author_name
  • author_link
  • subtitle
  • categories
  • feed_url
  • feed_copyright
  • feed_guid
  • ttl

你传递给 __init__ 的任何额外的关键字参数将被存储在 self.feed 中，供 自定义 feed 生成器 使用。

所有参数都应该是字符串，但 categories 除外，它应该是一个字符串序列。请注意，在 XML 文档中，有些控制字符是 不允许的 。如果你的内容中有一些，你可能会在生成 feed 时遇到一个 ValueError。

SyndicationFeed.add_item()

用给定的参数将一个项目添加到 feed 中。

必须的关键字参数是：

  • title
  • link
  • description

可选的关键字参数是：

  • author_email
  • author_name
  • author_link
  • pubdate
  • comments
  • unique_id
  • enclosures
  • categories
  • item_copyright
  • ttl
  • updateddate

额外的关键字参数将被存储在 自定义 feed 生成器 。

所有参数，如果给定，都应该是字符串，除了：

  • pubdate 应该是一个 Python datetime 对象。
  • updateddate 应该是一个 Python datetime 对象。
  • enclosures 应该是一个 django.utils.feedgenerator.Eclosure 实例的列表。
  • categories 应是一个字符串序列。

SyndicationFeed.write()

将给定编码的 feed 输出到 outfile，一个类似文件的对象。

SyndicationFeed.writeString()

以给定编码的字符串形式返回 feed。

例如，要创建一个 Atom 1.0 feed 并将其打印成标准输出：

  1. >>> from django.utils import feedgenerator
  2. >>> from datetime import datetime
  3. >>> f = feedgenerator.Atom1Feed(
  4. ...     title="My Blog",
  5. ...     link="https://www.example.com/",
  6. ...     description="In which I write about what I ate today.",
  7. ...     language="en",
  8. ...     author_name="Myself",
  9. ...     feed_url="https://example.com/atom.xml")
  10. >>> f.add_item(title="Hot dog today",
  11. ...     link="https://www.example.com/entries/1/",
  12. ...     pubdate=datetime.now(),
  13. ...     description="<p>Today I had a Vienna Beef hot dog. It was pink, plump and perfect.</p>")
  14. >>> print(f.writeString('UTF-8'))
  15. <?xml version="1.0" encoding="UTF-8"?>
  16. <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
  17. ...
  18. </feed>

自定义 feed 生成器

如果你需要制作一个自定义的 feed 格式，你有几个选择。

如果 feed 格式是完全自定义的，你会想要子类化 SyndicationFeed 并完全替换 write() 和 writeString() 方法。

然而，如果 feed 格式是 RSS 或 Atom 的衍生产品（即 GeoRSS ，苹果的 iTunes podcast format 等），你就有了更好的选择。这些类型的 feeds 通常会向底层格式添加额外的元素和／或属性，而且 SyndicationFeed 调用一组方法来获取这些额外的属性。因此，你可以子类化适当的 feed 生成器类（Atom1Feed 或 Rss201rev2Feed）并扩展这些回调。它们是：

SyndicationFeed.root_attributes(self)

返回一个属性的 dict 以添加到根 feed 元素（feed／channel）。

SyndicationFeed.add_root_elements(self, handler)

回调以在根 feed 元素（feed／channel）中添加元素。handler 是一个 XMLGenerator，来自 Python 内置的 SAX 库;你将调用它上的方法来添加到正在处理的 XML 文档中。

SyndicationFeed.item_attributes(self, item)

返回要添加到每个项目（item／entry）元素的 dict 属性。参数 item 是传递给 SyndicationFeed.add_item() 的所有数据的字典。

SyndicationFeed.add_item_elements(self, handler, item)

回调为每个项目（item／entry）元素添加元素。handler 和 item 同上。

警告

如果你覆盖了这些方法中的任何一个，一定要调用超级类方法，因为它们为每种 feed 格式添加了所需的元素。

例如，你可以这样开始实现一个 iTunes RSS feed 生成器：

  1. class iTunesFeed(Rss201rev2Feed):
  2.     def root_attributes(self):
  3.         attrs = super().root_attributes()
  4.         attrs['xmlns:itunes'] = 'http://www.itunes.com/dtds/podcast-1.0.dtd'
  5.         return attrs
  7.     def add_root_elements(self, handler):
  8.         super().add_root_elements(handler)
  9.         handler.addQuickElement('itunes:explicit', 'clean')

对于一个完整的自定义 feed 类来说，还有很多工作要做，但上面的例子应该展示了基本的想法。