Fixed #35420: Added support for RSS feed stylesheets.

django/utils/feedgenerator.py

@@ -75,6 +75,7 @@ def __init__(
         feed_copyright=None,
         feed_guid=None,
         ttl=None,
+        xsl_stylesheet_url=None,
         **kwargs,
     ):
         def to_str(s):
@@ -95,6 +96,7 @@ def to_str(s):
             "feed_copyright": to_str(feed_copyright),
             "id": feed_guid or link,
             "ttl": to_str(ttl),
+            "xsl_stylesheet_url": iri_to_uri(xsl_stylesheet_url),
             **kwargs,
         }
         self.items = []
@@ -166,6 +168,12 @@ def add_root_elements(self, handler):
         """
         pass
 
+    def add_stylesheets(self, handler):
+        """
+        Add stylesheet(s) to the feed (XSLT).
+        """
+        pass
+
     def item_attributes(self, item):
         """
         Return extra attributes to place on each item (i.e. item/entry) element.
@@ -227,7 +235,10 @@ class RssFeed(SyndicationFeed):
 
     def write(self, outfile, encoding):
         handler = SimplerXMLGenerator(outfile, encoding, short_empty_elements=True)
-        handler.startDocument()
+        self.start_document(handler)
+        # any stylesheet must come after the start of the document but before any tag
+        # https://www.w3.org/Style/styling-XML.en.html
+        self.add_stylesheets(handler)
         handler.startElement("rss", self.rss_attributes())
         handler.startElement("channel", self.root_attributes())
         self.add_root_elements(handler)
@@ -247,6 +258,15 @@ def write_items(self, handler):
             self.add_item_elements(handler, item)
             handler.endElement("item")
 
+    def start_document(self, handler):
+        handler.startDocument()
+
+    def add_stylesheets(self, handler):
+        if (url := self.feed["xsl_stylesheet_url"]) is not None:
+            handler.processingInstruction(
+                "xml-stylesheet", f'href="{url}" type="text/xsl"'
+            )
+
     def add_root_elements(self, handler):
         handler.addQuickElement("title", self.feed["title"])
         handler.addQuickElement("link", self.feed["link"])

docs/ref/contrib/syndication.txt

@@ -596,6 +596,22 @@ This example illustrates all possible attributes and methods for a
 
         ttl = 600  # Hard-coded Time To Live.
 
+        # XSL STYLESHEET URL -- One of the following three is optional. The
+        # framework looks for them in this order.
+
+        def xsl_stylesheet_url(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            stylesheet URL (only XSl is supported)
+            """
+
+        def xsl_stylesheet_url(self):
+            """
+            Returns the feed's stylesheet URL (only XSL is supported)
+            """
+
+        xsl_stylesheet_url = "/link/to/stylesheet.xsl"  # Hard-coded URL
+
         # ITEMS -- One of the following three is required. The framework looks
         # for them in this order.
 
@@ -961,6 +977,7 @@ They share this interface:
     * ``feed_copyright``
     * ``feed_guid``
     * ``ttl``
+    * ``xsl_stylesheet_url``
 
     Any extra keyword arguments you pass to ``__init__`` will be stored in
     ``self.feed`` for use with `custom feed generators`_.
@@ -1095,3 +1112,44 @@ For example, you might start implementing an iTunes RSS feed generator like so::
 
 There's a lot more work to be done for a complete custom feed class, but the
 above example should demonstrate the basic idea.
+
+Feed stylesheets
+----------------
+
+You can add styling to your RSS feed using an `XSLT stylesheet`_ by passing
+an ``xsl_stylesheet_url`` argument to the feed's constructor.
+
+This can be a hardcoded URL::
+
+    from django.contrib.syndication.views import Feed
+
+    class FeedWithHardcodedStylesheet(Feed):
+        ... # author, etc.
+        xsl_stylesheet_url = "https://example.com/rss_stylesheet.xslt"
+
+
+You can also use Django's static files system::
+
+    from django.contrib.syndication.views import Feed
+    from django.templatetags.static import static
+
+    class FeedWithStaticFileStylesheet(Feed):
+        ... # author, etc.
+        xsl_stylesheet_url = static("rss_styles.xslt")
+
+
+Another option is to have a view in your project that renders the XSLT document.
+You can then link it like so::
+
+    from django.contrib.syndication.views import Feed
+    from django.urls import reverse
+
+    class FeedWithStylesheetView(Feed):
+        ... # author, etc.
+        xsl_stylesheet_url = reverse("your-custom-view-name")
+
+.. _xslt stylesheet: https://developer.mozilla.org/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT
+
+.. versionadded:: 5.1
+
+The ability to specify ``xsl_stylesheet_url`` was added.

docs/ref/utils.txt

@@ -339,7 +339,7 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
     Base class for all syndication feeds. Subclasses should provide
     ``write()``.
 
-    .. method:: __init__(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)
+    .. method:: __init__(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, xsl_stylesheet_url=None, **kwargs)
 
         Initialize the feed with the given dictionary of metadata, which applies
         to the entire feed.
@@ -350,6 +350,10 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
         All parameters should be strings, except ``categories``, which should
         be a sequence of strings.
 
+        .. versionadded:: 5.1
+
+        The ``xsl_stylesheet_url`` argument was added.
+
     .. method:: add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs)
 
         Adds an item to the feed. All args are expected to be strings except
@@ -368,6 +372,11 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
         Add elements in the root (i.e. feed/channel) element.
         Called from ``write()``.
 
+    .. method:: add_stylesheets(self, handler)
+
+        Add stylesheet information to the document.
+        Called from ``write()``.
+
     .. method:: item_attributes(item)
 
         Return extra attributes to place on each item (i.e. item/entry)

docs/releases/5.1.txt

@@ -158,6 +158,10 @@ Minor features
 :mod:`django.contrib.syndication`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+* All :class:`~django.utils.feedgenerator.SyndicationFeed` classes now support
+  an ``xsl_stylesheet_url`` attribute. If specified, an ``<? xml-stylesheet ?>``
+  processing instruction will be added to the top of the document.
+
 * ...
 
 Asynchronous views

tests/syndication_tests/tests.py

@@ -4,8 +4,10 @@
 from django.contrib.sites.models import Site
 from django.contrib.syndication import views
 from django.core.exceptions import ImproperlyConfigured
+from django.templatetags.static import static
 from django.test import TestCase, override_settings
 from django.test.utils import requires_tz_support
+from django.urls import reverse
 from django.utils import timezone
 from django.utils.feedgenerator import (
     Atom1Feed,
@@ -561,6 +563,26 @@ def test_feed_no_content_self_closing_tag(self):
                 doc = feed.writeString("utf-8")
                 self.assertIn(f'<{tag} href="https://feed.url.com" rel="self"/>', doc)
 
+    def test_xsl_stylesheet(self):
+        testdata = [
+            ("/test.xsl", "/test.xsl"),
+            ("https://example.com/test.xsl", "https://example.com/test.xsl"),
+            (reverse("syndication-xsl-stylesheet"), "/syndication/stylesheet.xsl"),
+            (static("stylesheet.xsl"), "/static/stylesheet.xsl"),
+        ]
+        for url, expected in testdata:
+            with self.subTest(stylesheet_url=url):
+                feed = Rss201rev2Feed(
+                    title="test",
+                    link="https://example.com",
+                    description="test",
+                    xsl_stylesheet_url=url,
+                )
+                doc = feed.writeString("utf-8")
+                self.assertIn(
+                    f'<?xml-stylesheet href="{expected}" type="text/xsl"?>', doc
+                )
+
     @requires_tz_support
     def test_feed_last_modified_time_naive_date(self):
         """

tests/syndication_tests/urls.py

@@ -40,4 +40,9 @@
     path("syndication/rss2/multiple-enclosure/", feeds.TestMultipleEnclosureRSSFeed()),
     path("syndication/atom/single-enclosure/", feeds.TestSingleEnclosureAtomFeed()),
     path("syndication/atom/multiple-enclosure/", feeds.TestMultipleEnclosureAtomFeed()),
+    path(
+        "syndication/stylesheet.xsl",
+        lambda request: None,
+        name="syndication-xsl-stylesheet",
+    ),
 ]