Фреймворк для генерации лент новостей

Обзор

Высокоуровневый фреймворк для генерации лент данных предоставляется классом Feed. Для создания ленты напишите класс Feed и укажите его экземпляр в вашем URLconf.

Классы лент

Класс Feed — это класс Python, представляющий ленту данных. Лента может быть простой (например, лента «новостей сайта» или базовая лента, отображающая последние записи блога) или более сложной (например, лента, отображающая все записи блога в определённой категории, где категория является переменной).

Классы лент наследуются от django.contrib.syndication.views.Feed. Они могут находиться где угодно в вашем коде.

Экземпляры классов Feed являются представлениями, которые могут быть использованы в вашем URLconf.

Простой пример

Этот простой пример, взятый из гипотетического новостного сайта полицейского участка, описывает ленту последних пяти новостей:

from django.contrib.syndication.views import Feed
from django.urls import reverse
from policebeat.models import NewsItem


class LatestEntriesFeed(Feed):
    title = "Police beat site news"
    link = "/sitenews/"
    description = "Updates on changes and additions to police beat central."

    def items(self):
        return NewsItem.objects.order_by("-pub_date")[:5]

    def item_title(self, item):
        return item.title

    def item_description(self, item):
        return item.description

    # item_link is only needed if NewsItem has no get_absolute_url method.
    def item_link(self, item):
        return reverse("news-item", args=[item.pk])

Чтобы связать URL-адрес с этой лентой, поместите экземпляр объекта Feed в ваш URLconf. Например:

from django.urls import path
from myproject.feeds import LatestEntriesFeed

urlpatterns = [
    # ...
    path("latest/feed/", LatestEntriesFeed()),
    # ...
]

Примечание:

• Класс Feed наследуется от django.contrib.syndication.views.Feed.
• title, link и description соответствуют стандартным элементам RSS <title>, <link> и <description> соответственно.
• items() — метод, возвращающий список объектов, которые должны быть включены в ленту в качестве элементов <item>. Хотя в этом примере возвращаются объекты NewsItem с помощью ORM Django, items() не обязательно должен возвращать экземпляры модели. Хотя при использовании моделей Django вы получаете некоторые функции «бесплатно», items() может возвращать любой тип объекта, который вы хотите.
• Если вы создаёте ленту Atom, а не RSS, установите атрибут subtitle вместо атрибута description. См. Публикация лент Atom и RSS в паре ниже для примера.

Осталось одно действие. В ленте RSS каждый <item> имеет <title>, <link> и <description>. Нам нужно сказать фреймворку, какие данные поместить в эти элементы.

• Для содержимого <title> и <description> Django пытается вызвать методы item_title() и item_description() в классе Feed. Им передаётся единственный параметр, item, который является самим объектом. Они являются необязательными; по умолчанию используется строковое представление объекта для обоих.

  Если вы хотите выполнить специальную форматирование для заголовка или описания, можно использовать шаблоны Django вместо. Их пути можно указать с помощью атрибутов title_template и description_template в классе Feed. Шаблоны рендерятся для каждого элемента и им передаются две переменные контекста шаблона:

  • {{ obj }} — текущий объект (один из объектов, которые вы вернули в items()).
  • {{ site }} — объект django.contrib.sites.models.Site, представляющий текущий сайт. Это полезно для {{ site.domain }} или {{ site.name }}. Если у вас не установлен фреймворк Django sites, это будет объект RequestSite. См. раздел RequestSite в документации фреймворка sites для получения дополнительной информации.

  См. сложный пример ниже, который использует шаблон описания.

  Feed.get_context_data(**kwargs)

  Также есть способ передать дополнительную информацию шаблонам заголовка и описания, если вам нужно предоставить больше, чем две упомянутые переменные. Вы можете реализовать метод get_context_data в своем подклассе Feed. Например:

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

  И шаблон:

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

  Этот метод будет вызываться один раз для каждого элемента в списке, возвращаемом items(), со следующими ключевыми аргументами:

  • item: текущий элемент. По причинам обратной совместимости имя этой переменной контекста — {{ obj }}.
  • obj: объект, возвращаемый get_object(). По умолчанию он не предоставляется шаблонам для избежания путаницы с {{ obj }} (см. выше), но вы можете использовать его в своей реализации метода get_context_data().
  • site: текущий сайт, как описано выше.
  • request: текущий запрос.

  Поведение get_context_data() аналогично поведению обобщенных представлений — вы должны вызвать super() для получения данных контекста из родительского класса, добавить свои данные и вернуть измененный словарь.

• Для указания содержимого <link> у вас есть два варианта. Для каждого элемента в items() Django сначала пытается вызвать метод item_link() в классе Feed. Аналогично заголовку и описанию, ему передаётся единственный параметр, item. Если этот метод не существует, Django пытается выполнить метод get_absolute_url() для этого объекта. Методы get_absolute_url() и item_link() должны возвращать URL элемента в виде обычной строки Python. Как и в случае с get_absolute_url(), результат item_link() будет включён непосредственно в URL, поэтому вы несёте ответственность за выполнение всех необходимых операций с кодировкой URL и преобразования в ASCII внутри метода.

Сложный пример

Фреймворк также поддерживает более сложные ленты с помощью аргументов.

Например, веб-сайт может предложить ленту RSS с последними преступлениями для каждого полицейского участка в городе. Было бы глупо создавать отдельный класс Feed для каждого полицейского участка; это нарушило бы принцип DRY и связало бы данные с логикой программирования. Вместо этого фреймворк syndication позволяет получить доступ к аргументам, переданным из вашего URLconf, чтобы ленты могли выводить элементы на основе информации в URL-адресе ленты.

Ленты для участков могут быть доступны по таким URL-адресам:

• /beats/613/rss/ — возвращает последние преступления для участка 613.
• /beats/1424/rss/ — возвращает последние преступления для участка 1424.

Эти URL-адреса можно сопоставить с строкой URLconf такого типа:

path("beats/<int:beat_id>/rss/", BeatFeed()),

Как и для представления, аргументы в URL передаются методу get_object() вместе с объектом запроса.

Вот код для этих лент, специфичных для участка:

from django.contrib.syndication.views import Feed


class BeatFeed(Feed):
    description_template = "feeds/beat_description.html"

    def get_object(self, request, beat_id):
        return Beat.objects.get(pk=beat_id)

    def title(self, obj):
        return "Police beat central: Crimes for beat %s" % obj.beat

    def link(self, obj):
        return obj.get_absolute_url()

    def description(self, obj):
        return "Crimes recently reported in police beat %s" % obj.beat

    def items(self, obj):
        return Crime.objects.filter(beat=obj).order_by("-crime_date")[:30]

Для генерации <title>, <link> и <description> ленты Django использует методы title(), link() и description(). В предыдущем примере они были строковыми атрибутами класса, но этот пример иллюстрирует, что они могут быть либо строками, либо методами. Для каждого из title, link и description Django следует этому алгоритму:

• Сначала он пытается вызвать метод, передав аргумент obj, где obj — это объект, возвращаемый get_object().
• Если это не удаётся, он пытается вызвать метод без аргументов.
• Если это не удаётся, он использует атрибут класса.

Обратите также внимание, что items() также следует тому же алгоритму — сначала он пытается вызвать items(obj), затем items(), а затем, наконец, атрибут класса items (который должен быть списком).

Мы используем шаблон для описаний элементов. Он может быть таким же минимальным:

{{ obj.description }}

Однако вы можете добавить форматирование по своему желанию.

Класс ExampleFeed ниже предоставляет полную документацию по методам и атрибутам классов Feed.

Указание типа ленты

По умолчанию, ленты, созданные в этой системе, используют формат RSS 2.0.

Чтобы изменить это, добавьте атрибут feed_type к вашему классу Feed, как показано ниже:

from django.utils.feedgenerator import Atom1Feed


class MyFeed(Feed):
    feed_type = Atom1Feed

Обратите внимание, что вы устанавливаете feed_type в объект класса, а не в экземпляр.

В настоящее время доступны следующие типы лент:

• django.utils.feedgenerator.Rss201rev2Feed (RSS 2.01. По умолчанию.)
• django.utils.feedgenerator.RssUserland091Feed (RSS 0.91.)
• django.utils.feedgenerator.Atom1Feed (Atom 1.0.)

Вложения

Для указания вложений, например, используемых при создании лент подкастов, используйте крючок item_enclosures или, как альтернативу, если у вас есть только одно вложение на элемент, крючки item_enclosure_url, item_enclosure_length и item_enclosure_mime_type. См. примеры использования в классе ExampleFeed ниже.

Язык

Ленты, созданные с помощью фреймворка синдикации, автоматически включают соответствующий тег <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 setting.

Ленты Atom требуют <link rel="self">, определяющего текущее местоположение ленты. Фреймворк синдикации заполняет его автоматически, используя домен текущего сайта в соответствии с настройкой SITE_ID.

Публикация лент Atom и RSS совместно

Некоторые разработчики предпочитают предоставлять как ленты Atom, так и RSS версии своих лент. Для этого можно создать подкласс вашего класса Feed и установить feed_type на другое значение. Затем обновите свой URLconf, чтобы добавить дополнительные версии.

Вот полный пример:

from django.contrib.syndication.views import Feed
from policebeat.models import NewsItem
from django.utils.feedgenerator import Atom1Feed


class RssSiteNewsFeed(Feed):
    title = "Police beat site news"
    link = "/sitenews/"
    description = "Updates on changes and additions to police beat central."

    def items(self):
        return NewsItem.objects.order_by("-pub_date")[:5]


class AtomSiteNewsFeed(RssSiteNewsFeed):
    feed_type = Atom1Feed
    subtitle = RssSiteNewsFeed.description

И соответствующий URLconf:

from django.urls import path
from myproject.feeds import AtomSiteNewsFeed, RssSiteNewsFeed

urlpatterns = [
    # ...
    path("sitenews/rss/", RssSiteNewsFeed()),
    path("sitenews/atom/", AtomSiteNewsFeed()),
    # ...
]

Feed справка по классу

class views.Feed

Этот пример иллюстрирует все возможные атрибуты и методы класса Feed:

from django.contrib.syndication.views import Feed
from django.utils import feedgenerator


class ExampleFeed(Feed):
    # FEED TYPE -- Optional. This should be a class that subclasses
    # django.utils.feedgenerator.SyndicationFeed. This designates
    # which type of feed this should be: RSS 2.0, Atom 1.0, etc. If
    # you don't specify feed_type, your feed will be RSS 2.0. This
    # should be a class, not an instance of the class.

    feed_type = feedgenerator.Rss201rev2Feed

    # TEMPLATE NAMES -- Optional. These should be strings
    # representing names of Django templates that the system should
    # use in rendering the title and description of your feed items.
    # Both are optional. If a template is not specified, the
    # item_title() or item_description() methods are used instead.

    title_template = None
    description_template = None

    # LANGUAGE -- Optional. This should be a string specifying a language
    # code. Defaults to django.utils.translation.get_language().
    language = "de"

    # 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 URL
        # of the HTML version of the feed as a normal Python string.
        """

    def link(self):
        """
        Returns the URL of the HTML version of the feed as a normal Python
        string.
        """

    link = "/blog/"  # Hard-coded URL.

    # FEED_URL -- One of the following three is optional. The framework
    # looks for them in this order.

    def feed_url(self, obj):
        """
        # Takes the object returned by get_object() and returns the feed's
        # own URL as a normal Python string.
        """

    def feed_url(self):
        """
        Returns the feed's own URL as a normal Python string.
        """

    feed_url = "/blog/rss/"  # Hard-coded URL.

    # GUID -- One of the following three is optional. The framework looks
    # for them in this order. This property is only used for Atom feeds
    # (where it is the feed-level ID element). If not provided, the feed
    # link is used as the ID.

    def feed_guid(self, obj):
        """
        Takes the object returned by get_object() and returns the globally
        unique ID for the feed as a normal Python string.
        """

    def feed_guid(self):
        """
        Returns the feed's globally unique ID as a normal Python string.
        """

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

    # DESCRIPTION -- One of the following three is required. The framework
    # looks for them in this order.

    def description(self, obj):
        """
        Takes the object returned by get_object() and returns the feed's
        description as a normal Python string.
        """

    def description(self):
        """
        Returns the feed's description as a normal Python string.
        """

    description = "Foo bar baz."  # Hard-coded description.

    # AUTHOR NAME --One of the following three is optional. The framework
    # looks for them in this order.

    def author_name(self, obj):
        """
        Takes the object returned by get_object() and returns the feed's
        author's name as a normal Python string.
        """

    def author_name(self):
        """
        Returns the feed's author's name as a normal Python string.
        """

    author_name = "Sally Smith"  # Hard-coded author name.

    # AUTHOR EMAIL --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 email as a normal Python string.
        """

    def author_email(self):
        """
        Returns the feed's author's email as a normal Python string.
        """

    author_email = "test@example.com"  # Hard-coded author email.

    # 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 scheme (such as "https://") 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 = "https://www.example.com/"  # Hard-coded author URL.

    # CATEGORIES -- One of the following three is optional. The framework
    # looks for them in this order. In each case, the method/attribute
    # should return an iterable object that returns strings.

    def categories(self, obj):
        """
        Takes the object returned by get_object() and returns the feed's
        categories as iterable over strings.
        """

    def categories(self):
        """
        Returns the feed's categories as iterable over strings.
        """

    categories = ["python", "django"]  # Hard-coded list of categories.

    # COPYRIGHT NOTICE -- One of the following three is optional. The
    # framework looks for them in this order.

    def feed_copyright(self, obj):
        """
        Takes the object returned by get_object() and returns the feed's
        copyright notice as a normal Python string.
        """

    def feed_copyright(self):
        """
        Returns the feed's copyright notice as a normal Python string.
        """

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

    # TTL -- One of the following three is optional. The framework looks
    # for them in this order. Ignored for Atom feeds.

    def ttl(self, obj):
        """
        Takes the object returned by get_object() and returns the feed's
        TTL (Time To Live) as a normal Python string.
        """

    def ttl(self):
        """
        Returns the feed's TTL as a normal Python string.
        """

    ttl = 600  # Hard-coded Time To Live.

    # STYLESHEETS -- Optional. To set, provide one of the following three.
    # The framework looks for them in this order.

    def stylesheets(self, obj):
        """
        Takes the object returned by get_object() and returns the feed's
        stylesheets (as URL strings or as Stylesheet instances).
        """

    def stylesheets(self):
        """
        Returns the feed's stylesheets (as URL strings or Stylesheet
        instances).
        """

    # Hardcoded stylesheets.
    stylesheets = ["/stylesheet1.xsl", "stylesheet2.xsl"]

    # 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, request, *args, **kwargs):
        """
        Takes the current request and the arguments from the URL, and
        returns an object represented by this feed. Raises
        django.core.exceptions.ObjectDoesNotExist on error.
        """

    # ITEM TITLE AND DESCRIPTION -- If title_template or
    # description_template are not defined, these are used instead. Both are
    # optional, by default they will use the string representation of the
    # item.

    def item_title(self, item):
        """
        Takes an item, as returned by items(), and returns the item's
        title as a normal Python string.
        """

    def item_title(self):
        """
        Returns the title for every item in the feed.
        """

    item_title = "Breaking News: Nothing Happening"  # Hard-coded title.

    def item_description(self, item):
        """
        Takes an item, as returned by items(), and returns the item's
        description as a normal Python string.
        """

    def item_description(self):
        """
        Returns the description for every item in the feed.
        """

    item_description = "A description of the item."  # Hard-coded description.

    def get_context_data(self, **kwargs):
        """
        Returns a dictionary to use as extra context if either
        description_template or item_template are used.

        Default implementation preserves the old behavior
        of using {'obj': item, 'site': current_site} as the context.
        """

    # ITEM LINK -- One of these three is required. The framework looks for
    # them in this order.

    # First, the framework tries the two methods below, in
    # order. Failing that, it falls back to the get_absolute_url()
    # method on each item returned by items().

    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_GUID -- The following method is optional. If not provided, the
    # item's link is used by default.

    def item_guid(self, obj):
        """
        Takes an item, as return by items(), and returns the item's ID.
        """

    # ITEM_GUID_IS_PERMALINK -- The following method is optional. If
    # provided, it sets the 'isPermaLink' attribute of an item's
    # GUID element. This method is used only when 'item_guid' is
    # specified.

    def item_guid_is_permalink(self, obj):
        """
        Takes an item, as returned by items(), and returns a boolean.
        """

    item_guid_is_permalink = False  # Hard coded value

    # 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 EMAIL --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 email as a normal Python string.
        """

    def item_author_email(self):
        """
        Returns the author email for every item in the feed.
        """

    item_author_email = "test@example.com"  # Hard-coded author email.

    # 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 scheme (such as "https://") 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 = "https://www.example.com/"  # Hard-coded author URL.

    # ITEM ENCLOSURES -- One of the following three is optional. The
    # framework looks for them in this order. If one of them is defined,
    # ``item_enclosure_url``, ``item_enclosure_length``, and
    # ``item_enclosure_mime_type`` will have no effect.

    def item_enclosures(self, item):
        """
        Takes an item, as returned by items(), and returns a list of
        ``django.utils.feedgenerator.Enclosure`` objects.
        """

    def item_enclosures(self):
        """
        Returns the ``django.utils.feedgenerator.Enclosure`` list for every
        item in the feed.
        """

    item_enclosures = []  # Hard-coded enclosure list

    # ITEM ENCLOSURE URL -- One of these three is required if you're
    # publishing enclosures and you're not using ``item_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 and you're not using ``item_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 and you're not using ``item_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 MIME type 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 UPDATED -- It's optional to use one of these three. This is a
    # hook that specifies how to get the updateddate for a given item.
    # In each case, the method/attribute should return a Python
    # datetime.datetime object.

    def item_updateddate(self, item):
        """
        Takes an item, as returned by items(), and returns the item's
        updateddate.
        """

    def item_updateddate(self):
        """
        Returns the updateddate for every item in the feed.
        """

    item_updateddate = datetime.datetime(2005, 5, 3)  # Hard-coded updateddate.

    # 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.

    # ITEM COMMENTS URL -- It's optional to use one of these three. This is
    # a hook that specifies how to get the URL of a page for comments for a
    # given item.

    def item_comments(self, obj):
        """
        Takes an item, as returned by items(), and returns the item's
        comments URL as a normal Python string.
        """

    def item_comments(self):
        """
        Returns the comments URL for every item in the feed.
        """

    item_comments = "https://www.example.com/comments"  # Hard-coded comments URL

Классы SyndicationFeed

Модуль feedgenerator содержит базовый класс:

• django.utils.feedgenerator.SyndicationFeed

и несколько подклассов:

• django.utils.feedgenerator.RssUserland091Feed
• django.utils.feedgenerator.Rss201rev2Feed
• django.utils.feedgenerator.Atom1Feed

Каждый из этих трёх классов знает, как преобразовать определённый тип потока в XML. Они разделяют этот интерфейс:

SyndicationFeed.__init__()

Инициализирует поток с заданным словарем метаданных, который применяется ко всему потоку. Требуемые ключевые аргументы:

• title
• link
• description

Также есть множество других необязательных ключевых аргументов:

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

Любые дополнительные ключевые аргументы, которые вы передаёте __init__, будут сохранены в self.feed для использования с пользовательскими генераторами потоков.

Все параметры должны быть строками, за исключением двух:

• categories должно быть последовательностью строк.
• stylesheets должно быть последовательностью строк или экземпляров Stylesheet.

Обратите внимание, что некоторые управляющие символы не разрешены в XML-документах. Если ваш контент содержит некоторые из них, вы можете столкнуться с ошибкой ValueError при создании потока.

Изменено в Django 5.2:

Добавлен аргумент stylesheets.

SyndicationFeed.add_item()

Добавляет элемент в поток с заданными параметрами.

Требуемые ключевые аргументы:

• title
• link
• description

Необязательные ключевые аргументы:

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

Дополнительные ключевые аргументы будут сохранены для пользовательских генераторов потоков.

Все параметры, если указаны, должны быть строками, за исключением:

• pubdate должно быть объектом Python datetime.
• updateddate должно быть объектом Python datetime.
• enclosures должно быть списком экземпляров django.utils.feedgenerator.Enclosure.
• categories должно быть последовательностью строк.

SyndicationFeed.write()

Выводит поток в заданной кодировке в outfile, который является объектом типа файл.

SyndicationFeed.writeString()

Возвращает поток в виде строки в заданной кодировке.

Например, чтобы создать поток Atom 1.0 и вывести его в стандартный вывод:

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

Пользовательские генераторы потоков

Если вам нужно создать пользовательский формат потока, у вас есть несколько вариантов.

Если формат потока полностью пользовательский, вы захотите создать подкласс SyndicationFeed и полностью заменить методы write() и writeString().

Однако, если формат потока является производным от RSS или Atom (например, GeoRSS, формат подкаста iTunes Apple и т.д.), у вас есть лучший выбор. Эти типы потоков обычно добавляют дополнительные элементы и/или атрибуты к основному формату, и есть набор методов, которые SyndicationFeed вызывает для получения этих дополнительных атрибутов. Таким образом, вы можете создать подкласс соответствующего класса генератора потоков (Atom1Feed или Rss201rev2Feed) и расширить эти обратные вызовы. Они являются:

SyndicationFeed.root_attributes(self)

Возвращает словарь атрибутов, которые нужно добавить к корневому элементу потока (feed/channel).

SyndicationFeed.add_root_elements(self, handler)

Обратный вызов для добавления элементов внутри корневого элемента потока (feed/channel). handler — это XMLGenerator из встроенной библиотеки SAX Python; вы будете вызывать методы на нём, чтобы добавить в XML-документ в процессе.

SyndicationFeed.item_attributes(self, item)

Возвращает словарь атрибутов, которые нужно добавить к каждому элементу (item/entry).

SyndicationFeed.add_item_elements(self, handler, item)

Обратный вызов для добавления элементов в каждый элемент (item/entry). handler и item — такие же, как выше.

Например, вы можете начать реализацию генератора iTunes RSS-потока следующим образом:

class iTunesFeed(Rss201rev2Feed):
    def root_attributes(self):
        attrs = super().root_attributes()
        attrs["xmlns:itunes"] = "http://www.itunes.com/dtds/podcast-1.0.dtd"
        return attrs

    def add_root_elements(self, handler):
        super().add_root_elements(handler)
        handler.addQuickElement("itunes:explicit", "clean")

Для завершения пользовательского класса потока необходимо сделать гораздо больше, но пример выше должен продемонстрировать основную идею.

Стили потоков

Если вы хотите, чтобы ваш RSS-поток отображался красиво в браузере, вам необходимо предоставить информацию об оформлении XML-файла, обычно в форматах XSLT или CSS.

Вы можете добавить это в свой RSS-поток, установив атрибут stylesheets в классе потока.

Это может быть жёстко закодированный URL:

from django.contrib.syndication.views import Feed


class FeedWithHardcodedStylesheet(Feed):
    stylesheets = [
        "https://example.com/rss_stylesheet.xslt",
    ]

Вы также можете использовать систему статических файлов Django:

from django.contrib.syndication.views import Feed
from django.templatetags.static import static


class FeedWithStaticFileStylesheet(Feed):
    stylesheets = [
        static("rss_styles.xslt"),
    ]

Другой вариант — иметь представление в своём проекте, которое рендерит XSLT-документ. Вы можете связать его следующим образом:

from django.contrib.syndication.views import Feed
from django.urls import reverse_lazy


class FeedWithStylesheetView(Feed):
    stylesheets = [
        reverse_lazy("your-custom-view-name"),
    ]

Django обычно пытается угадать MIME-тип заданного URL на основе его расширения, но если это не удаётся, вы можете указать его с помощью класса Stylesheet:

from django.contrib.syndication.views import Feed
from django.utils.feedgenerator import Stylesheet


class FeedWithHardcodedStylesheet(Feed):
    stylesheets = [
        Stylesheet("https://example.com/rss_stylesheet", mimetype="text/xsl"),
    ]

Аналогично, если вы хотите использовать другой атрибут media, чем screen (по умолчанию Django), вы можете снова использовать класс Stylesheet:

from django.contrib.syndication.views import Feed
from django.utils.feedgenerator import Stylesheet


class FeedWithHardcodedStylesheet(Feed):
    stylesheets = [
        Stylesheet("https://example.com/rss_stylesheet.xslt", media="print"),
    ]

Любой из этих вариантов можно комбинировать при использовании нескольких таблиц стилей:

from django.contrib.syndication.views import Feed
from django.utils.feedgenerator import Stylesheet


class MultiStylesheetFeed(Feed):
    stylesheets = [
        "/stylesheet1.xsl",
        Stylesheet("/stylesheet2.xsl"),
    ]