Debian Codegraph @

docs/ref/contrib/syndication.txt

raw
1 ==============================
2 The syndication feed framework
3 ==============================
4
5 .. module:: django.contrib.syndication
6 :synopsis: A framework for generating syndication feeds, in RSS and Atom,
7 quite easily.
8
9 Django comes with a high-level syndication-feed-generating framework for
10 creating RSS_ and :rfc:`Atom <4287>` feeds.
11
12 To create any syndication feed, all you have to do is write a short
13 Python class. You can create as many feeds as you want.
14
15 Django also comes with a lower-level feed-generating API. Use this if
16 you want to generate feeds outside of a web context, or in some other
17 lower-level way.
18
19 .. _RSS: https://developer.mozilla.org/en-US/docs/Glossary/RSS
20
21 The high-level framework
22 ========================
23
24 Overview
25 --------
26
27 The high-level feed-generating framework is supplied by the
28 :class:`~django.contrib.syndication.views.Feed` class. To create a
29 feed, write a :class:`~django.contrib.syndication.views.Feed` class
30 and point to an instance of it in your :doc:`URLconf
31 </topics/http/urls>`.
32
33 ``Feed`` classes
34 ----------------
35
36 A :class:`~django.contrib.syndication.views.Feed` class is a Python
37 class that represents a syndication feed. A feed can be simple (e.g.,
38 a "site news" feed, or a basic feed displaying the latest entries of a
39 blog) or more complex (e.g., a feed displaying all the blog entries in
40 a particular category, where the category is variable).
41
42 Feed classes subclass :class:`django.contrib.syndication.views.Feed`.
43 They can live anywhere in your codebase.
44
45 Instances of :class:`~django.contrib.syndication.views.Feed` classes
46 are views which can be used in your :doc:`URLconf </topics/http/urls>`.
47
48 A simple example
49 ----------------
50
51 This simple example, taken from a hypothetical police beat news site describes
52 a feed of the latest five news items::
53
54 from django.contrib.syndication.views import Feed
55 from django.urls import reverse
56 from policebeat.models import NewsItem
57
58
59 class LatestEntriesFeed(Feed):
60 title = "Police beat site news"
61 link = "/sitenews/"
62 description = "Updates on changes and additions to police beat central."
63
64 def items(self):
65 return NewsItem.objects.order_by("-pub_date")[:5]
66
67 def item_title(self, item):
68 return item.title
69
70 def item_description(self, item):
71 return item.description
72
73 # item_link is only needed if NewsItem has no get_absolute_url method.
74 def item_link(self, item):
75 return reverse("news-item", args=[item.pk])
76
77 To connect a URL to this feed, put an instance of the Feed object in
78 your :doc:`URLconf </topics/http/urls>`. For example::
79
80 from django.urls import path
81 from myproject.feeds import LatestEntriesFeed
82
83 urlpatterns = [
84 # ...
85 path("latest/feed/", LatestEntriesFeed()),
86 # ...
87 ]
88
89 Note:
90
91 * The Feed class subclasses :class:`django.contrib.syndication.views.Feed`.
92
93 * ``title``, ``link`` and ``description`` correspond to the
94 standard RSS ``<title>``, ``<link>`` and ``<description>`` elements,
95 respectively.
96
97 * ``items()`` is, a method that returns a list of objects that should be
98 included in the feed as ``<item>`` elements. Although this example returns
99 ``NewsItem`` objects using Django's :doc:`object-relational mapper
100 </ref/models/querysets>`, ``items()`` doesn't have to return model instances.
101 Although you get a few bits of functionality "for free" by using Django
102 models, ``items()`` can return any type of object you want.
103
104 * If you're creating an Atom feed, rather than an RSS feed, set the
105 ``subtitle`` attribute instead of the ``description`` attribute.
106 See `Publishing Atom and RSS feeds in tandem`_, later, for an example.
107
108 One thing is left to do. In an RSS feed, each ``<item>`` has a ``<title>``,
109 ``<link>`` and ``<description>``. We need to tell the framework what data to put
110 into those elements.
111
112 * For the contents of ``<title>`` and ``<description>``, Django tries
113 calling the methods ``item_title()`` and ``item_description()`` on
114 the :class:`~django.contrib.syndication.views.Feed` class. They are passed
115 a single parameter, ``item``, which is the object itself. These are
116 optional; by default, the string representation of the object is used for
117 both.
118
119 If you want to do any special formatting for either the title or
120 description, :doc:`Django templates </ref/templates/language>` can be used
121 instead. Their paths can be specified with the ``title_template`` and
122 ``description_template`` attributes on the
123 :class:`~django.contrib.syndication.views.Feed` class. The templates are
124 rendered for each item and are passed two template context variables:
125
126 * ``{{ obj }}`` -- The current object (one of whichever objects you
127 returned in ``items()``).
128
129 * ``{{ site }}`` -- A :class:`django.contrib.sites.models.Site` object
130 representing the current site. This is useful for ``{{ site.domain
131 }}`` or ``{{ site.name }}``. If you do *not* have the Django sites
132 framework installed, this will be set to a
133 :class:`~django.contrib.sites.requests.RequestSite` object. See the
134 :ref:`RequestSite section of the sites framework documentation
135 <requestsite-objects>` for more.
136
137 See `a complex example`_ below that uses a description template.
138
139 .. method:: Feed.get_context_data(**kwargs)
140
141 There is also a way to pass additional information to title and description
142 templates, if you need to supply more than the two variables mentioned
143 before. You can provide your implementation of ``get_context_data`` method
144 in your ``Feed`` subclass. For example::
145
146 from mysite.models import Article
147 from django.contrib.syndication.views import Feed
148
149
150 class ArticlesFeed(Feed):
151 title = "My articles"
152 description_template = "feeds/articles.html"
153
154 def items(self):
155 return Article.objects.order_by("-pub_date")[:5]
156
157 def get_context_data(self, **kwargs):
158 context = super().get_context_data(**kwargs)
159 context["foo"] = "bar"
160 return context
161
162 And the template:
163
164 .. code-block:: html+django
165
166 Something about {{ foo }}: {{ obj.description }}
167
168 This method will be called once per each item in the list returned by
169 ``items()`` with the following keyword arguments:
170
171 * ``item``: the current item. For backward compatibility reasons, the name
172 of this context variable is ``{{ obj }}``.
173
174 * ``obj``: the object returned by ``get_object()``. By default this is not
175 exposed to the templates to avoid confusion with ``{{ obj }}`` (see above),
176 but you can use it in your implementation of ``get_context_data()``.
177
178 * ``site``: current site as described above.
179
180 * ``request``: current request.
181
182 The behavior of ``get_context_data()`` mimics that of
183 :ref:`generic views <adding-extra-context>` - you're supposed to call
184 ``super()`` to retrieve context data from parent class, add your data
185 and return the modified dictionary.
186
187 * To specify the contents of ``<link>``, you have two options. For each item
188 in ``items()``, Django first tries calling the
189 ``item_link()`` method on the
190 :class:`~django.contrib.syndication.views.Feed` class. In a similar way to
191 the title and description, it is passed it a single parameter,
192 ``item``. If that method doesn't exist, Django tries executing a
193 ``get_absolute_url()`` method on that object. Both
194 ``get_absolute_url()`` and ``item_link()`` should return the
195 item's URL as a normal Python string. As with ``get_absolute_url()``, the
196 result of ``item_link()`` will be included directly in the URL, so you
197 are responsible for doing all necessary URL quoting and conversion to
198 ASCII inside the method itself.
199
200 A complex example
201 -----------------
202
203 The framework also supports more complex feeds, via arguments.
204
205 For example, a website could offer an RSS feed of recent crimes for every
206 police beat in a city. It'd be silly to create a separate
207 :class:`~django.contrib.syndication.views.Feed` class for each police beat; that
208 would violate the :ref:`DRY principle <dry>` and would couple data to
209 programming logic. Instead, the syndication framework lets you access the
210 arguments passed from your :doc:`URLconf </topics/http/urls>` so feeds can output
211 items based on information in the feed's URL.
212
213 The police beat feeds could be accessible via URLs like this:
214
215 * ``/beats/613/rss/`` -- Returns recent crimes for beat 613.
216 * ``/beats/1424/rss/`` -- Returns recent crimes for beat 1424.
217
218 These can be matched with a :doc:`URLconf </topics/http/urls>` line such as::
219
220 path("beats/<int:beat_id>/rss/", BeatFeed()),
221
222 Like a view, the arguments in the URL are passed to the ``get_object()``
223 method along with the request object.
224
225 Here's the code for these beat-specific feeds::
226
227 from django.contrib.syndication.views import Feed
228
229
230 class BeatFeed(Feed):
231 description_template = "feeds/beat_description.html"
232
233 def get_object(self, request, beat_id):
234 return Beat.objects.get(pk=beat_id)
235
236 def title(self, obj):
237 return "Police beat central: Crimes for beat %s" % obj.beat
238
239 def link(self, obj):
240 return obj.get_absolute_url()
241
242 def description(self, obj):
243 return "Crimes recently reported in police beat %s" % obj.beat
244
245 def items(self, obj):
246 return Crime.objects.filter(beat=obj).order_by("-crime_date")[:30]
247
248 To generate the feed's ``<title>``, ``<link>`` and ``<description>``, Django
249 uses the ``title()``, ``link()`` and ``description()`` methods. In
250 the previous example, they were string class attributes, but this example
251 illustrates that they can be either strings *or* methods. For each of
252 ``title``, ``link`` and ``description``, Django follows this
253 algorithm:
254
255 * First, it tries to call a method, passing the ``obj`` argument, where
256 ``obj`` is the object returned by ``get_object()``.
257
258 * Failing that, it tries to call a method with no arguments.
259
260 * Failing that, it uses the class attribute.
261
262 Also note that ``items()`` also follows the same algorithm -- first, it
263 tries ``items(obj)``, then ``items()``, then finally an ``items``
264 class attribute (which should be a list).
265
266 We are using a template for the item descriptions. It can be as minimal as
267 this:
268
269 .. code-block:: html+django
270
271 {{ obj.description }}
272
273 However, you are free to add formatting as desired.
274
275 The ``ExampleFeed`` class below gives full documentation on methods and
276 attributes of :class:`~django.contrib.syndication.views.Feed` classes.
277
278 Specifying the type of feed
279 ---------------------------
280
281 By default, feeds produced in this framework use RSS 2.0.
282
283 To change that, add a ``feed_type`` attribute to your
284 :class:`~django.contrib.syndication.views.Feed` class, like so::
285
286 from django.utils.feedgenerator import Atom1Feed
287
288
289 class MyFeed(Feed):
290 feed_type = Atom1Feed
291
292 Note that you set ``feed_type`` to a class object, not an instance.
293
294 Currently available feed types are:
295
296 * :class:`django.utils.feedgenerator.Rss201rev2Feed` (RSS 2.01. Default.)
297 * :class:`django.utils.feedgenerator.RssUserland091Feed` (RSS 0.91.)
298 * :class:`django.utils.feedgenerator.Atom1Feed` (Atom 1.0.)
299
300 Enclosures
301 ----------
302
303 To specify enclosures, such as those used in creating podcast feeds, use the
304 ``item_enclosures`` hook or, alternatively and if you only have a single
305 enclosure per item, the ``item_enclosure_url``, ``item_enclosure_length``, and
306 ``item_enclosure_mime_type`` hooks. See the ``ExampleFeed`` class below for
307 usage examples.
308
309 Language
310 --------
311
312 Feeds created by the syndication framework automatically include the
313 appropriate ``<language>`` tag (RSS 2.0) or ``xml:lang`` attribute (Atom). By
314 default, this is :func:`django.utils.translation.get_language()`. You can change it
315 by setting the ``language`` class attribute.
316
317 URLs
318 ----
319
320 The ``link`` method/attribute can return either an absolute path (e.g.
321 ``"/blog/"``) or a URL with the fully-qualified domain and protocol (e.g.
322 ``"https://www.example.com/blog/"``). If ``link`` doesn't return the domain,
323 the syndication framework will insert the domain of the current site, according
324 to your :setting:`SITE_ID setting <SITE_ID>`.
325
326 Atom feeds require a ``<link rel="self">`` that defines the feed's current
327 location. The syndication framework populates this automatically, using the
328 domain of the current site according to the :setting:`SITE_ID` setting.
329
330 Publishing Atom and RSS feeds in tandem
331 ---------------------------------------
332
333 Some developers like to make available both Atom *and* RSS versions of their
334 feeds. To do that, you can create a subclass of your
335 :class:`~django.contrib.syndication.views.Feed` class and set the ``feed_type``
336 to something different. Then update your URLconf to add the extra versions.
337
338 Here's a full example::
339
340 from django.contrib.syndication.views import Feed
341 from policebeat.models import NewsItem
342 from django.utils.feedgenerator import Atom1Feed
343
344
345 class RssSiteNewsFeed(Feed):
346 title = "Police beat site news"
347 link = "/sitenews/"
348 description = "Updates on changes and additions to police beat central."
349
350 def items(self):
351 return NewsItem.objects.order_by("-pub_date")[:5]
352
353
354 class AtomSiteNewsFeed(RssSiteNewsFeed):
355 feed_type = Atom1Feed
356 subtitle = RssSiteNewsFeed.description
357
358 .. Note::
359 In this example, the RSS feed uses a ``description`` while the Atom
360 feed uses a ``subtitle``. That's because Atom feeds don't provide for
361 a feed-level "description," but they *do* provide for a "subtitle."
362
363 If you provide a ``description`` in your
364 :class:`~django.contrib.syndication.views.Feed` class, Django will *not*
365 automatically put that into the ``subtitle`` element, because a
366 subtitle and description are not necessarily the same thing. Instead, you
367 should define a ``subtitle`` attribute.
368
369 In the above example, we set the Atom feed's ``subtitle`` to the RSS feed's
370 ``description``, because it's quite short already.
371
372 And the accompanying URLconf::
373
374 from django.urls import path
375 from myproject.feeds import AtomSiteNewsFeed, RssSiteNewsFeed
376
377 urlpatterns = [
378 # ...
379 path("sitenews/rss/", RssSiteNewsFeed()),
380 path("sitenews/atom/", AtomSiteNewsFeed()),
381 # ...
382 ]
383
384 ``Feed`` class reference
385 ------------------------
386
387 .. class:: views.Feed
388
389 This example illustrates all possible attributes and methods for a
390 :class:`~django.contrib.syndication.views.Feed` class::
391
392 from django.contrib.syndication.views import Feed
393 from django.utils import feedgenerator
394
395
396 class ExampleFeed(Feed):
397 # FEED TYPE -- Optional. This should be a class that subclasses
398 # django.utils.feedgenerator.SyndicationFeed. This designates
399 # which type of feed this should be: RSS 2.0, Atom 1.0, etc. If
400 # you don't specify feed_type, your feed will be RSS 2.0. This
401 # should be a class, not an instance of the class.
402
403 feed_type = feedgenerator.Rss201rev2Feed
404
405 # TEMPLATE NAMES -- Optional. These should be strings
406 # representing names of Django templates that the system should
407 # use in rendering the title and description of your feed items.
408 # Both are optional. If a template is not specified, the
409 # item_title() or item_description() methods are used instead.
410
411 title_template = None
412 description_template = None
413
414 # LANGUAGE -- Optional. This should be a string specifying a language
415 # code. Defaults to django.utils.translation.get_language().
416 language = "de"
417
418 # TITLE -- One of the following three is required. The framework
419 # looks for them in this order.
420
421 def title(self, obj):
422 """
423 Takes the object returned by get_object() and returns the
424 feed's title as a normal Python string.
425 """
426
427 def title(self):
428 """
429 Returns the feed's title as a normal Python string.
430 """
431
432 title = "foo" # Hard-coded title.
433
434 # LINK -- One of the following three is required. The framework
435 # looks for them in this order.
436
437 def link(self, obj):
438 """
439 # Takes the object returned by get_object() and returns the URL
440 # of the HTML version of the feed as a normal Python string.
441 """
442
443 def link(self):
444 """
445 Returns the URL of the HTML version of the feed as a normal Python
446 string.
447 """
448
449 link = "/blog/" # Hard-coded URL.
450
451 # FEED_URL -- One of the following three is optional. The framework
452 # looks for them in this order.
453
454 def feed_url(self, obj):
455 """
456 # Takes the object returned by get_object() and returns the feed's
457 # own URL as a normal Python string.
458 """
459
460 def feed_url(self):
461 """
462 Returns the feed's own URL as a normal Python string.
463 """
464
465 feed_url = "/blog/rss/" # Hard-coded URL.
466
467 # GUID -- One of the following three is optional. The framework looks
468 # for them in this order. This property is only used for Atom feeds
469 # (where it is the feed-level ID element). If not provided, the feed
470 # link is used as the ID.
471
472 def feed_guid(self, obj):
473 """
474 Takes the object returned by get_object() and returns the globally
475 unique ID for the feed as a normal Python string.
476 """
477
478 def feed_guid(self):
479 """
480 Returns the feed's globally unique ID as a normal Python string.
481 """
482
483 feed_guid = "/foo/bar/1234" # Hard-coded guid.
484
485 # DESCRIPTION -- One of the following three is required. The framework
486 # looks for them in this order.
487
488 def description(self, obj):
489 """
490 Takes the object returned by get_object() and returns the feed's
491 description as a normal Python string.
492 """
493
494 def description(self):
495 """
496 Returns the feed's description as a normal Python string.
497 """
498
499 description = "Foo bar baz." # Hard-coded description.
500
501 # AUTHOR NAME --One of the following three is optional. The framework
502 # looks for them in this order.
503
504 def author_name(self, obj):
505 """
506 Takes the object returned by get_object() and returns the feed's
507 author's name as a normal Python string.
508 """
509
510 def author_name(self):
511 """
512 Returns the feed's author's name as a normal Python string.
513 """
514
515 author_name = "Sally Smith" # Hard-coded author name.
516
517 # AUTHOR EMAIL --One of the following three is optional. The framework
518 # looks for them in this order.
519
520 def author_email(self, obj):
521 """
522 Takes the object returned by get_object() and returns the feed's
523 author's email as a normal Python string.
524 """
525
526 def author_email(self):
527 """
528 Returns the feed's author's email as a normal Python string.
529 """
530
531 author_email = "[email protected]" # Hard-coded author email.
532
533 # AUTHOR LINK --One of the following three is optional. The framework
534 # looks for them in this order. In each case, the URL should include
535 # the scheme (such as "https://") and domain name.
536
537 def author_link(self, obj):
538 """
539 Takes the object returned by get_object() and returns the feed's
540 author's URL as a normal Python string.
541 """
542
543 def author_link(self):
544 """
545 Returns the feed's author's URL as a normal Python string.
546 """
547
548 author_link = "https://www.example.com/" # Hard-coded author URL.
549
550 # CATEGORIES -- One of the following three is optional. The framework
551 # looks for them in this order. In each case, the method/attribute
552 # should return an iterable object that returns strings.
553
554 def categories(self, obj):
555 """
556 Takes the object returned by get_object() and returns the feed's
557 categories as iterable over strings.
558 """
559
560 def categories(self):
561 """
562 Returns the feed's categories as iterable over strings.
563 """
564
565 categories = ["python", "django"] # Hard-coded list of categories.
566
567 # COPYRIGHT NOTICE -- One of the following three is optional. The
568 # framework looks for them in this order.
569
570 def feed_copyright(self, obj):
571 """
572 Takes the object returned by get_object() and returns the feed's
573 copyright notice as a normal Python string.
574 """
575
576 def feed_copyright(self):
577 """
578 Returns the feed's copyright notice as a normal Python string.
579 """
580
581 feed_copyright = "Copyright (c) 2007, Sally Smith" # Hard-coded copyright notice.
582
583 # TTL -- One of the following three is optional. The framework looks
584 # for them in this order. Ignored for Atom feeds.
585
586 def ttl(self, obj):
587 """
588 Takes the object returned by get_object() and returns the feed's
589 TTL (Time To Live) as a normal Python string.
590 """
591
592 def ttl(self):
593 """
594 Returns the feed's TTL as a normal Python string.
595 """
596
597 ttl = 600 # Hard-coded Time To Live.
598
599 # STYLESHEETS -- Optional. To set, provide one of the following three.
600 # The framework looks for them in this order.
601
602 def stylesheets(self, obj):
603 """
604 Takes the object returned by get_object() and returns the feed's
605 stylesheets (as URL strings or as Stylesheet instances).
606 """
607
608 def stylesheets(self):
609 """
610 Returns the feed's stylesheets (as URL strings or Stylesheet
611 instances).
612 """
613
614 # Hardcoded stylesheets.
615 stylesheets = ["/stylesheet1.xsl", "stylesheet2.xsl"]
616
617 # ITEMS -- One of the following three is required. The framework looks
618 # for them in this order.
619
620 def items(self, obj):
621 """
622 Takes the object returned by get_object() and returns a list of
623 items to publish in this feed.
624 """
625
626 def items(self):
627 """
628 Returns a list of items to publish in this feed.
629 """
630
631 items = ["Item 1", "Item 2"] # Hard-coded items.
632
633 # GET_OBJECT -- This is required for feeds that publish different data
634 # for different URL parameters. (See "A complex example" above.)
635
636 def get_object(self, request, *args, **kwargs):
637 """
638 Takes the current request and the arguments from the URL, and
639 returns an object represented by this feed. Raises
640 django.core.exceptions.ObjectDoesNotExist on error.
641 """
642
643 # ITEM TITLE AND DESCRIPTION -- If title_template or
644 # description_template are not defined, these are used instead. Both are
645 # optional, by default they will use the string representation of the
646 # item.
647
648 def item_title(self, item):
649 """
650 Takes an item, as returned by items(), and returns the item's
651 title as a normal Python string.
652 """
653
654 def item_title(self):
655 """
656 Returns the title for every item in the feed.
657 """
658
659 item_title = "Breaking News: Nothing Happening" # Hard-coded title.
660
661 def item_description(self, item):
662 """
663 Takes an item, as returned by items(), and returns the item's
664 description as a normal Python string.
665 """
666
667 def item_description(self):
668 """
669 Returns the description for every item in the feed.
670 """
671
672 item_description = "A description of the item." # Hard-coded description.
673
674 def get_context_data(self, **kwargs):
675 """
676 Returns a dictionary to use as extra context if either
677 description_template or item_template are used.
678
679 Default implementation preserves the old behavior
680 of using {'obj': item, 'site': current_site} as the context.
681 """
682
683 # ITEM LINK -- One of these three is required. The framework looks for
684 # them in this order.
685
686 # First, the framework tries the two methods below, in
687 # order. Failing that, it falls back to the get_absolute_url()
688 # method on each item returned by items().
689
690 def item_link(self, item):
691 """
692 Takes an item, as returned by items(), and returns the item's URL.
693 """
694
695 def item_link(self):
696 """
697 Returns the URL for every item in the feed.
698 """
699
700 # ITEM_GUID -- The following method is optional. If not provided, the
701 # item's link is used by default.
702
703 def item_guid(self, obj):
704 """
705 Takes an item, as return by items(), and returns the item's ID.
706 """
707
708 # ITEM_GUID_IS_PERMALINK -- The following method is optional. If
709 # provided, it sets the 'isPermaLink' attribute of an item's
710 # GUID element. This method is used only when 'item_guid' is
711 # specified.
712
713 def item_guid_is_permalink(self, obj):
714 """
715 Takes an item, as returned by items(), and returns a boolean.
716 """
717
718 item_guid_is_permalink = False # Hard coded value
719
720 # ITEM AUTHOR NAME -- One of the following three is optional. The
721 # framework looks for them in this order.
722
723 def item_author_name(self, item):
724 """
725 Takes an item, as returned by items(), and returns the item's
726 author's name as a normal Python string.
727 """
728
729 def item_author_name(self):
730 """
731 Returns the author name for every item in the feed.
732 """
733
734 item_author_name = "Sally Smith" # Hard-coded author name.
735
736 # ITEM AUTHOR EMAIL --One of the following three is optional. The
737 # framework looks for them in this order.
738 #
739 # If you specify this, you must specify item_author_name.
740
741 def item_author_email(self, obj):
742 """
743 Takes an item, as returned by items(), and returns the item's
744 author's email as a normal Python string.
745 """
746
747 def item_author_email(self):
748 """
749 Returns the author email for every item in the feed.
750 """
751
752 item_author_email = "[email protected]" # Hard-coded author email.
753
754 # ITEM AUTHOR LINK -- One of the following three is optional. The
755 # framework looks for them in this order. In each case, the URL should
756 # include the scheme (such as "https://") and domain name.
757 #
758 # If you specify this, you must specify item_author_name.
759
760 def item_author_link(self, obj):
761 """
762 Takes an item, as returned by items(), and returns the item's
763 author's URL as a normal Python string.
764 """
765
766 def item_author_link(self):
767 """
768 Returns the author URL for every item in the feed.
769 """
770
771 item_author_link = "https://www.example.com/" # Hard-coded author URL.
772
773 # ITEM ENCLOSURES -- One of the following three is optional. The
774 # framework looks for them in this order. If one of them is defined,
775 # ``item_enclosure_url``, ``item_enclosure_length``, and
776 # ``item_enclosure_mime_type`` will have no effect.
777
778 def item_enclosures(self, item):
779 """
780 Takes an item, as returned by items(), and returns a list of
781 ``django.utils.feedgenerator.Enclosure`` objects.
782 """
783
784 def item_enclosures(self):
785 """
786 Returns the ``django.utils.feedgenerator.Enclosure`` list for every
787 item in the feed.
788 """
789
790 item_enclosures = [] # Hard-coded enclosure list
791
792 # ITEM ENCLOSURE URL -- One of these three is required if you're
793 # publishing enclosures and you're not using ``item_enclosures``. The
794 # framework looks for them in this order.
795
796 def item_enclosure_url(self, item):
797 """
798 Takes an item, as returned by items(), and returns the item's
799 enclosure URL.
800 """
801
802 def item_enclosure_url(self):
803 """
804 Returns the enclosure URL for every item in the feed.
805 """
806
807 item_enclosure_url = "/foo/bar.mp3" # Hard-coded enclosure link.
808
809 # ITEM ENCLOSURE LENGTH -- One of these three is required if you're
810 # publishing enclosures and you're not using ``item_enclosures``. The
811 # framework looks for them in this order. In each case, the returned
812 # value should be either an integer, or a string representation of the
813 # integer, in bytes.
814
815 def item_enclosure_length(self, item):
816 """
817 Takes an item, as returned by items(), and returns the item's
818 enclosure length.
819 """
820
821 def item_enclosure_length(self):
822 """
823 Returns the enclosure length for every item in the feed.
824 """
825
826 item_enclosure_length = 32000 # Hard-coded enclosure length.
827
828 # ITEM ENCLOSURE MIME TYPE -- One of these three is required if you're
829 # publishing enclosures and you're not using ``item_enclosures``. The
830 # framework looks for them in this order.
831
832 def item_enclosure_mime_type(self, item):
833 """
834 Takes an item, as returned by items(), and returns the item's
835 enclosure MIME type.
836 """
837
838 def item_enclosure_mime_type(self):
839 """
840 Returns the enclosure MIME type for every item in the feed.
841 """
842
843 item_enclosure_mime_type = "audio/mpeg" # Hard-coded enclosure MIME type.
844
845 # ITEM PUBDATE -- It's optional to use one of these three. This is a
846 # hook that specifies how to get the pubdate for a given item.
847 # In each case, the method/attribute should return a Python
848 # datetime.datetime object.
849
850 def item_pubdate(self, item):
851 """
852 Takes an item, as returned by items(), and returns the item's
853 pubdate.
854 """
855
856 def item_pubdate(self):
857 """
858 Returns the pubdate for every item in the feed.
859 """
860
861 item_pubdate = datetime.datetime(2005, 5, 3) # Hard-coded pubdate.
862
863 # ITEM UPDATED -- It's optional to use one of these three. This is a
864 # hook that specifies how to get the updateddate for a given item.
865 # In each case, the method/attribute should return a Python
866 # datetime.datetime object.
867
868 def item_updateddate(self, item):
869 """
870 Takes an item, as returned by items(), and returns the item's
871 updateddate.
872 """
873
874 def item_updateddate(self):
875 """
876 Returns the updateddate for every item in the feed.
877 """
878
879 item_updateddate = datetime.datetime(2005, 5, 3) # Hard-coded updateddate.
880
881 # ITEM CATEGORIES -- It's optional to use one of these three. This is
882 # a hook that specifies how to get the list of categories for a given
883 # item. In each case, the method/attribute should return an iterable
884 # object that returns strings.
885
886 def item_categories(self, item):
887 """
888 Takes an item, as returned by items(), and returns the item's
889 categories.
890 """
891
892 def item_categories(self):
893 """
894 Returns the categories for every item in the feed.
895 """
896
897 item_categories = ["python", "django"] # Hard-coded categories.
898
899 # ITEM COPYRIGHT NOTICE (only applicable to Atom feeds) -- One of the
900 # following three is optional. The framework looks for them in this
901 # order.
902
903 def item_copyright(self, obj):
904 """
905 Takes an item, as returned by items(), and returns the item's
906 copyright notice as a normal Python string.
907 """
908
909 def item_copyright(self):
910 """
911 Returns the copyright notice for every item in the feed.
912 """
913
914 item_copyright = "Copyright (c) 2007, Sally Smith" # Hard-coded copyright notice.
915
916 # ITEM COMMENTS URL -- It's optional to use one of these three. This is
917 # a hook that specifies how to get the URL of a page for comments for a
918 # given item.
919
920 def item_comments(self, obj):
921 """
922 Takes an item, as returned by items(), and returns the item's
923 comments URL as a normal Python string.
924 """
925
926 def item_comments(self):
927 """
928 Returns the comments URL for every item in the feed.
929 """
930
931 item_comments = "https://www.example.com/comments" # Hard-coded comments URL
932
933 The low-level framework
934 =======================
935
936 Behind the scenes, the high-level RSS framework uses a lower-level framework
937 for generating feeds' XML. This framework lives in a single module:
938 :source:`django/utils/feedgenerator.py`.
939
940 You use this framework on your own, for lower-level feed generation. You can
941 also create custom feed generator subclasses for use with the ``feed_type``
942 ``Feed`` option.
943
944 .. currentmodule:: django.utils.feedgenerator
945
946 ``SyndicationFeed`` classes
947 ---------------------------
948
949 The :mod:`~django.utils.feedgenerator` module contains a base class:
950
951 * :class:`django.utils.feedgenerator.SyndicationFeed`
952
953 and several subclasses:
954
955 * :class:`django.utils.feedgenerator.RssUserland091Feed`
956 * :class:`django.utils.feedgenerator.Rss201rev2Feed`
957 * :class:`django.utils.feedgenerator.Atom1Feed`
958
959 Each of these three classes knows how to render a certain type of feed as XML.
960 They share this interface:
961
962 :meth:`.SyndicationFeed.__init__`
963 Initialize the feed with the given dictionary of metadata, which applies to
964 the entire feed. Required keyword arguments are:
965
966 * ``title``
967 * ``link``
968 * ``description``
969
970 There's also a bunch of other optional keywords:
971
972 * ``language``
973 * ``author_email``
974 * ``author_name``
975 * ``author_link``
976 * ``subtitle``
977 * ``categories``
978 * ``feed_url``
979 * ``feed_copyright``
980 * ``feed_guid``
981 * ``ttl``
982 * ``stylesheets``
983
984 Any extra keyword arguments you pass to ``__init__`` will be stored in
985 ``self.feed`` for use with `custom feed generators`_.
986
987 All parameters should be strings, except for two:
988
989 * ``categories`` should be a sequence of strings.
990 * ``stylesheets`` should be a sequence of either strings or
991 :class:`~django.utils.feedgenerator.Stylesheet` instances.
992
993 Beware that some control characters are
994 `not allowed <https://www.w3.org/International/questions/qa-controls>`_ in
995 XML documents. If your content has some of them, you might encounter a
996 :exc:`ValueError` when producing the feed.
997
998 .. versionchanged:: 5.2
999
1000 The ``stylesheets`` argument was added.
1001
1002 :meth:`.SyndicationFeed.add_item`
1003 Add an item to the feed with the given parameters.
1004
1005 Required keyword arguments are:
1006
1007 * ``title``
1008 * ``link``
1009 * ``description``
1010
1011 Optional keyword arguments are:
1012
1013 * ``author_email``
1014 * ``author_name``
1015 * ``author_link``
1016 * ``pubdate``
1017 * ``comments``
1018 * ``unique_id``
1019 * ``enclosures``
1020 * ``categories``
1021 * ``item_copyright``
1022 * ``ttl``
1023 * ``updateddate``
1024
1025 Extra keyword arguments will be stored for `custom feed generators`_.
1026
1027 All parameters, if given, should be strings, except:
1028
1029 * ``pubdate`` should be a Python :class:`~datetime.datetime` object.
1030 * ``updateddate`` should be a Python :class:`~datetime.datetime` object.
1031 * ``enclosures`` should be a list of
1032 :class:`django.utils.feedgenerator.Enclosure` instances.
1033 * ``categories`` should be a sequence of strings.
1034
1035 :meth:`.SyndicationFeed.write`
1036 Outputs the feed in the given encoding to outfile, which is a file-like object.
1037
1038 :meth:`.SyndicationFeed.writeString`
1039 Returns the feed as a string in the given encoding.
1040
1041 For example, to create an Atom 1.0 feed and print it to standard output:
1042
1043 .. code-block:: pycon
1044
1045 >>> from django.utils import feedgenerator
1046 >>> from datetime import datetime
1047 >>> f = feedgenerator.Atom1Feed(
1048 ... title="My Blog",
1049 ... link="https://www.example.com/",
1050 ... description="In which I write about what I ate today.",
1051 ... language="en",
1052 ... author_name="Myself",
1053 ... feed_url="https://example.com/atom.xml",
1054 ... )
1055 >>> f.add_item(
1056 ... title="Hot dog today",
1057 ... link="https://www.example.com/entries/1/",
1058 ... pubdate=datetime.now(),
1059 ... description="<p>Today I had a Vienna Beef hot dog. It was pink, plump and perfect.</p>",
1060 ... )
1061 >>> print(f.writeString("UTF-8"))
1062 <?xml version="1.0" encoding="UTF-8"?>
1063 <feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
1064 ...
1065 </feed>
1066
1067 .. currentmodule:: django.contrib.syndication
1068
1069 Custom feed generators
1070 ----------------------
1071
1072 If you need to produce a custom feed format, you've got a couple of options.
1073
1074 If the feed format is totally custom, you'll want to subclass
1075 ``SyndicationFeed`` and completely replace the ``write()`` and
1076 ``writeString()`` methods.
1077
1078 However, if the feed format is a spin-off of RSS or Atom (i.e. GeoRSS_, Apple's
1079 `iTunes podcast format`_, etc.), you've got a better choice. These types of
1080 feeds typically add extra elements and/or attributes to the underlying format,
1081 and there are a set of methods that ``SyndicationFeed`` calls to get these extra
1082 attributes. Thus, you can subclass the appropriate feed generator class
1083 (``Atom1Feed`` or ``Rss201rev2Feed``) and extend these callbacks. They are:
1084
1085 .. _georss: https://georss.org
1086 .. _itunes podcast format: https://help.apple.com/itc/podcasts_connect/#/itcb54353390
1087
1088 ``SyndicationFeed.root_attributes(self)``
1089 Return a ``dict`` of attributes to add to the root feed element
1090 (``feed``/``channel``).
1091
1092 ``SyndicationFeed.add_root_elements(self, handler)``
1093 Callback to add elements inside the root feed element
1094 (``feed``/``channel``). ``handler`` is an
1095 :class:`~xml.sax.saxutils.XMLGenerator` from Python's built-in SAX library;
1096 you'll call methods on it to add to the XML document in process.
1097
1098 ``SyndicationFeed.item_attributes(self, item)``
1099 Return a ``dict`` of attributes to add to each item (``item``/``entry``)
1100 element. The argument, ``item``, is a dictionary of all the data passed to
1101 ``SyndicationFeed.add_item()``.
1102
1103 ``SyndicationFeed.add_item_elements(self, handler, item)``
1104 Callback to add elements to each item (``item``/``entry``) element.
1105 ``handler`` and ``item`` are as above.
1106
1107 .. warning::
1108
1109 If you override any of these methods, be sure to call the superclass methods
1110 since they add the required elements for each feed format.
1111
1112 For example, you might start implementing an iTunes RSS feed generator like so::
1113
1114 class iTunesFeed(Rss201rev2Feed):
1115 def root_attributes(self):
1116 attrs = super().root_attributes()
1117 attrs["xmlns:itunes"] = "http://www.itunes.com/dtds/podcast-1.0.dtd"
1118 return attrs
1119
1120 def add_root_elements(self, handler):
1121 super().add_root_elements(handler)
1122 handler.addQuickElement("itunes:explicit", "clean")
1123
1124 There's a lot more work to be done for a complete custom feed class, but the
1125 above example should demonstrate the basic idea.
1126
1127 .. _feed-stylesheets:
1128
1129 Feed stylesheets
1130 ----------------
1131
1132 .. versionadded:: 5.2
1133
1134 If you wish to have your RSS feed render nicely in a browser, you will need to
1135 provide styling information for the XML file, typically in XSLT_ or CSS
1136 formats.
1137
1138 You can add this to your RSS feed by setting the ``stylesheets`` attribute on
1139 the feed class.
1140
1141 This can be a hardcoded URL::
1142
1143 from django.contrib.syndication.views import Feed
1144
1145
1146 class FeedWithHardcodedStylesheet(Feed):
1147 stylesheets = [
1148 "https://example.com/rss_stylesheet.xslt",
1149 ]
1150
1151 You can also use Django's static files system::
1152
1153 from django.contrib.syndication.views import Feed
1154 from django.templatetags.static import static
1155
1156
1157 class FeedWithStaticFileStylesheet(Feed):
1158 stylesheets = [
1159 static("rss_styles.xslt"),
1160 ]
1161
1162 Another option is to have a view in your project that renders the XSLT
1163 document. You can then link it like so::
1164
1165 from django.contrib.syndication.views import Feed
1166 from django.urls import reverse_lazy
1167
1168
1169 class FeedWithStylesheetView(Feed):
1170 stylesheets = [
1171 reverse_lazy("your-custom-view-name"),
1172 ]
1173
1174 Django will normally try to guess the MIME type of the given URL based on its
1175 extension, but if that fails you can specify it using the
1176 :class:`~django.utils.feedgenerator.Stylesheet` class::
1177
1178 from django.contrib.syndication.views import Feed
1179 from django.utils.feedgenerator import Stylesheet
1180
1181
1182 class FeedWithHardcodedStylesheet(Feed):
1183 stylesheets = [
1184 Stylesheet("https://example.com/rss_stylesheet", mimetype="text/xsl"),
1185 ]
1186
1187 Similarly, if you'd like to use a different ``media`` attribute than ``screen``
1188 (Django's default), you can use the
1189 :class:`~django.utils.feedgenerator.Stylesheet` class again::
1190
1191 from django.contrib.syndication.views import Feed
1192 from django.utils.feedgenerator import Stylesheet
1193
1194
1195 class FeedWithHardcodedStylesheet(Feed):
1196 stylesheets = [
1197 Stylesheet("https://example.com/rss_stylesheet.xslt", media="print"),
1198 ]
1199
1200 Any of these options can be combined when using multiple stylesheets::
1201
1202 from django.contrib.syndication.views import Feed
1203 from django.utils.feedgenerator import Stylesheet
1204
1205
1206 class MultiStylesheetFeed(Feed):
1207 stylesheets = [
1208 "/stylesheet1.xsl",
1209 Stylesheet("/stylesheet2.xsl"),
1210 ]
1211
1212 .. _xslt: https://developer.mozilla.org/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT