Fixed #12978 -- Added support for RSS feed stylesheets.

django/contrib/syndication/views.py

@@ -160,6 +160,7 @@ class Feed:
             feed_copyright=self._get_dynamic_attr("feed_copyright", obj),
             feed_guid=self._get_dynamic_attr("feed_guid", obj),
             ttl=self._get_dynamic_attr("ttl", obj),
+            stylesheets=self._get_dynamic_attr("stylesheets", obj),
             **self.feed_extra_kwargs(obj),
         )
 

django/utils/feedgenerator.py

@@ -24,6 +24,7 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
 
 import datetime
 import email
+import mimetypes
 from io import StringIO
 from urllib.parse import urlparse
 
@@ -57,6 +58,53 @@ def get_tag_uri(url, date):
     return "tag:%s%s:%s/%s" % (bits.hostname, d, bits.path, bits.fragment)
 
 
+def _guess_stylesheet_mimetype(url):
+    """
+    Return the given stylesheet's mimetype tuple, using a slightly custom
+    version of Python's mimetypes.guess_type().
+    """
+    mimetypedb = mimetypes.MimeTypes()
+
+    # The official mimetype for XSLT files is technically `application/xslt+xml`
+    # but as of 2024 almost no browser supports that (they all expect text/xsl).
+    # On top of that, windows seems to assume that the type for xsl is text/xml.
+    mimetypedb.readfp(StringIO("text/xsl\txsl\ntext/xsl\txslt"))
+
+    return mimetypedb.guess_type(url)
+
+
+class Stylesheet:
+    """An RSS stylesheet"""
+
+    def __init__(self, url, mimetype="", media="screen"):
+        self._url = url
+        self._mimetype = mimetype
+        self.media = media
+
+    # Using a property to delay the evaluation of self._url as late as possible
+    # in case of a lazy object (like reverse_lazy(...) for example).
+    @property
+    def url(self):
+        return iri_to_uri(self._url)
+
+    @property
+    def mimetype(self):
+        if self._mimetype == "":
+            return _guess_stylesheet_mimetype(self.url)[0]
+        return self._mimetype
+
+    def __str__(self):
+        data = [f'href="{self.url}"']
+        if self.mimetype is not None:
+            data.append(f'type="{self.mimetype}"')
+        if self.media is not None:
+            data.append(f'media="{self.media}"')
+        return " ".join(data)
+
+    def __repr__(self):
+        return repr((self.url, self.mimetype, self.media))
+
+
 class SyndicationFeed:
     "Base class for all syndication feeds. Subclasses should provide write()"
 
@@ -75,12 +123,24 @@ class SyndicationFeed:
         feed_copyright=None,
         feed_guid=None,
         ttl=None,
+        stylesheets=None,
         **kwargs,
     ):
         def to_str(s):
             return str(s) if s is not None else s
 
+        def to_stylesheet(s):
+            return s if isinstance(s, Stylesheet) else Stylesheet(s)
+
         categories = categories and [str(c) for c in categories]
+
+        if stylesheets is not None:
+            if isinstance(stylesheets, (Stylesheet, str)):
+                raise TypeError(
+                    f"stylesheets should be a list, not {stylesheets.__class__}"
+                )
+            stylesheets = [to_stylesheet(s) for s in stylesheets]
+
         self.feed = {
             "title": to_str(title),
             "link": iri_to_uri(link),
@@ -95,6 +155,7 @@ class SyndicationFeed:
             "feed_copyright": to_str(feed_copyright),
             "id": feed_guid or link,
             "ttl": to_str(ttl),
+            "stylesheets": stylesheets,
             **kwargs,
         }
         self.items = []
@@ -166,6 +227,12 @@ class SyndicationFeed:
         """
         pass
 
+    def add_stylesheets(self, handler):
+        """
+        Add stylesheet(s) to the feed. Called from write().
+        """
+        pass
+
     def item_attributes(self, item):
         """
         Return extra attributes to place on each item (i.e. item/entry) element.
@@ -228,6 +295,9 @@ class RssFeed(SyndicationFeed):
     def write(self, outfile, encoding):
         handler = SimplerXMLGenerator(outfile, encoding, short_empty_elements=True)
         handler.startDocument()
+        # 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 +317,10 @@ class RssFeed(SyndicationFeed):
             self.add_item_elements(handler, item)
             handler.endElement("item")
 
+    def add_stylesheets(self, handler):
+        for stylesheet in self.feed["stylesheets"] or []:
+            handler.processingInstruction("xml-stylesheet", stylesheet)
+
     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,24 @@ This example illustrates all possible attributes and methods for a
 
         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.
 
@@ -961,16 +979,26 @@ They share this interface:
     * ``feed_copyright``
     * ``feed_guid``
     * ``ttl``
+    * ``stylesheets``
 
     Any extra keyword arguments you pass to ``__init__`` will be stored in
     ``self.feed`` for use with `custom feed generators`_.
 
-    All parameters should be strings, except ``categories``, which should be a
-    sequence of strings. Beware that some control characters
-    are `not allowed <https://www.w3.org/International/questions/qa-controls>`_
-    in XML documents. If your content has some of them, you might encounter a
+    All parameters should be strings, except for two:
+
+    * ``categories`` should be a sequence of strings.
+    * ``stylesheets`` should be a sequence of either strings or
+      :class:`~django.utils.feedgenerator.Stylesheet` instances.
+
+    Beware that some control characters are
+    `not allowed <https://www.w3.org/International/questions/qa-controls>`_ in
+    XML documents. If your content has some of them, you might encounter a
     :exc:`ValueError` when producing the feed.
 
+    .. versionchanged:: 5.2
+
+        The ``stylesheets`` argument was added.
+
 :meth:`.SyndicationFeed.add_item`
     Add an item to the feed with the given parameters.
 
@@ -1095,3 +1123,90 @@ 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:
+
+Feed stylesheets
+----------------
+
+.. versionadded:: 5.2
+
+If you wish to have your RSS feed render nicely in a browser, you will need to
+provide styling information for the XML file, typically in XSLT_ or CSS
+formats.
+
+You can add this to your RSS feed by setting the ``stylesheets`` attribute on
+the feed class.
+
+This can be a hardcoded URL::
+
+    from django.contrib.syndication.views import Feed
+
+
+    class FeedWithHardcodedStylesheet(Feed):
+        stylesheets = [
+            "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):
+        stylesheets = [
+            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_lazy
+
+
+    class FeedWithStylesheetView(Feed):
+        stylesheets = [
+            reverse_lazy("your-custom-view-name"),
+        ]
+
+Django will normally try to guess the MIME type of the given URL based on its
+extension, but if that fails you can specify it using the
+:class:`~django.utils.feedgenerator.Stylesheet` class::
+
+    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"),
+        ]
+
+Similarly, if you'd like to use a different ``media`` attribute than ``screen``
+(Django's default), you can use the
+:class:`~django.utils.feedgenerator.Stylesheet` class again::
+
+    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"),
+        ]
+
+Any of these options can be combined when using multiple stylesheets::
+
+    from django.contrib.syndication.views import Feed
+    from django.utils.feedgenerator import Stylesheet
+
+
+    class MultiStylesheetFeed(Feed):
+        stylesheets = [
+            "/stylesheet1.xsl",
+            Stylesheet("/stylesheet2.xsl"),
+        ]
+
+.. _xslt: https://developer.mozilla.org/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT

docs/ref/utils.txt

@@ -331,6 +331,32 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
 
     See https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id
 
+``Stylesheet``
+--------------
+
+.. versionadded:: 5.2
+
+.. class:: Stylesheet(url, mimetype="", media="screen")
+
+    Represents an RSS stylesheet.
+
+    .. attribute:: url
+
+        Required argument. The URL where the stylesheet is located.
+
+    .. attribute:: mimetype
+
+        An optional string containing the MIME type of the stylesheet. If not
+        specified, Django will attempt to guess it by using Python's
+        :py:func:`mimetypes.guess_type()`. Use ``mimetype=None`` if you don't
+        want your stylesheet to have a MIME type specified.
+
+    .. attribute:: media
+
+        An optional string which will be used as the ``media`` attribute of
+        the stylesheet. Defaults to ``"screen"``. Use ``media=None`` if you
+        don't want your stylesheet to have a ``media`` attribute.
+
 ``SyndicationFeed``
 -------------------
 
@@ -339,7 +365,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, stylesheets=None, **kwargs)
 
         Initialize the feed with the given dictionary of metadata, which applies
         to the entire feed.
@@ -347,8 +373,15 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
         Any extra keyword arguments you pass to ``__init__`` will be stored in
         ``self.feed``.
 
-        All parameters should be strings, except ``categories``, which should
-        be a sequence of strings.
+        All parameters should be strings, except for two:
+
+        * ``categories`` should be a sequence of strings.
+        * ``stylesheets`` should be a sequence of either strings or
+          :class:`Stylesheet` instances.
+
+        .. versionchanged:: 5.2
+
+            The ``stylesheets`` 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)
 
@@ -368,6 +401,13 @@ 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)
+
+        .. versionadded:: 5.2
+
+        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.2.txt

@@ -100,7 +100,10 @@ Minor features
 :mod:`django.contrib.syndication`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* ...
+* All :class:`~django.utils.feedgenerator.SyndicationFeed` classes now support
+  a ``stylesheets`` attribute. If specified, an ``<? xml-stylesheet ?>``
+  processing instruction will be added to the top of the document for each
+  stylesheet in the given list. See :ref:`feed-stylesheets` for more details.
 
 Asynchronous views
 ~~~~~~~~~~~~~~~~~~

tests/syndication_tests/feeds.py

@@ -236,6 +236,13 @@ class TestGetObjectFeed(TestRss2Feed):
         return "Title: %s" % item.title
 
 
+class TestFeedWithStylesheets(TestRss2Feed):
+    stylesheets = [
+        "/stylesheet1.xsl",
+        feedgenerator.Stylesheet("/stylesheet2.xsl"),
+    ]
+
+
 class NaiveDatesFeed(TestAtomFeed):
     """
     A feed with naive (non-timezone-aware) dates.

tests/syndication_tests/tests.py

@@ -4,12 +4,16 @@ from xml.dom import minidom
 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, reverse_lazy
 from django.utils import timezone
 from django.utils.feedgenerator import (
     Atom1Feed,
     Rss201rev2Feed,
+    Stylesheet,
+    SyndicationFeed,
     rfc2822_date,
     rfc3339_date,
 )
@@ -561,6 +565,125 @@ class SyndicationFeedTest(FeedTestCase):
                 doc = feed.writeString("utf-8")
                 self.assertIn(f'<{tag} href="https://feed.url.com" rel="self"/>', doc)
 
+    def test_stylesheets_none(self):
+        feed = Rss201rev2Feed(
+            title="test",
+            link="https://example.com",
+            description="test",
+            stylesheets=None,
+        )
+        self.assertNotIn("xml-stylesheet", feed.writeString("utf-8"))
+
+    def test_stylesheets(self):
+        testdata = [
+            # Plain strings.
+            ("/test.xsl", 'href="/test.xsl" type="text/xsl" media="screen"'),
+            ("/test.xslt", 'href="/test.xslt" type="text/xsl" media="screen"'),
+            ("/test.css", 'href="/test.css" type="text/css" media="screen"'),
+            ("/test", 'href="/test" media="screen"'),
+            (
+                "https://example.com/test.xsl",
+                'href="https://example.com/test.xsl" type="text/xsl" media="screen"',
+            ),
+            (
+                "https://example.com/test.css",
+                'href="https://example.com/test.css" type="text/css" media="screen"',
+            ),
+            (
+                "https://example.com/test",
+                'href="https://example.com/test" media="screen"',
+            ),
+            ("/♥.xsl", 'href="/%E2%99%A5.xsl" type="text/xsl" media="screen"'),
+            (
+                static("stylesheet.xsl"),
+                'href="/static/stylesheet.xsl" type="text/xsl" media="screen"',
+            ),
+            (
+                static("stylesheet.css"),
+                'href="/static/stylesheet.css" type="text/css" media="screen"',
+            ),
+            (static("stylesheet"), 'href="/static/stylesheet" media="screen"'),
+            (
+                reverse("syndication-xsl-stylesheet"),
+                'href="/syndication/stylesheet.xsl" type="text/xsl" media="screen"',
+            ),
+            (
+                reverse_lazy("syndication-xsl-stylesheet"),
+                'href="/syndication/stylesheet.xsl" type="text/xsl" media="screen"',
+            ),
+            # Stylesheet objects.
+            (
+                Stylesheet("/test.xsl"),
+                'href="/test.xsl" type="text/xsl" media="screen"',
+            ),
+            (Stylesheet("/test.xsl", mimetype=None), 'href="/test.xsl" media="screen"'),
+            (Stylesheet("/test.xsl", media=None), 'href="/test.xsl" type="text/xsl"'),
+            (Stylesheet("/test.xsl", mimetype=None, media=None), 'href="/test.xsl"'),
+            (
+                Stylesheet("/test.xsl", mimetype="text/xml"),
+                'href="/test.xsl" type="text/xml" media="screen"',
+            ),
+        ]
+        for stylesheet, expected in testdata:
+            feed = Rss201rev2Feed(
+                title="test",
+                link="https://example.com",
+                description="test",
+                stylesheets=[stylesheet],
+            )
+            doc = feed.writeString("utf-8")
+            with self.subTest(expected=expected):
+                self.assertIn(f"<?xml-stylesheet {expected}?>", doc)
+
+    def test_stylesheets_instructions_are_at_the_top(self):
+        response = self.client.get("/syndication/stylesheet/")
+        doc = minidom.parseString(response.content)
+        self.assertEqual(doc.childNodes[0].nodeName, "xml-stylesheet")
+        self.assertEqual(
+            doc.childNodes[0].data,
+            'href="/stylesheet1.xsl" type="text/xsl" media="screen"',
+        )
+        self.assertEqual(doc.childNodes[1].nodeName, "xml-stylesheet")
+        self.assertEqual(
+            doc.childNodes[1].data,
+            'href="/stylesheet2.xsl" type="text/xsl" media="screen"',
+        )
+
+    def test_stylesheets_typeerror_if_str_or_stylesheet(self):
+        for stylesheet, error_message in [
+            ("/stylesheet.xsl", "stylesheets should be a list, not <class 'str'>"),
+            (
+                Stylesheet("/stylesheet.xsl"),
+                "stylesheets should be a list, "
+                "not <class 'django.utils.feedgenerator.Stylesheet'>",
+            ),
+        ]:
+            args = ("title", "/link", "description")
+            with self.subTest(stylesheets=stylesheet):
+                self.assertRaisesMessage(
+                    TypeError,
+                    error_message,
+                    SyndicationFeed,
+                    *args,
+                    stylesheets=stylesheet,
+                )
+
+    def test_stylesheets_repr(self):
+        testdata = [
+            (Stylesheet("/test.xsl", mimetype=None), "('/test.xsl', None, 'screen')"),
+            (Stylesheet("/test.xsl", media=None), "('/test.xsl', 'text/xsl', None)"),
+            (
+                Stylesheet("/test.xsl", mimetype=None, media=None),
+                "('/test.xsl', None, None)",
+            ),
+            (
+                Stylesheet("/test.xsl", mimetype="text/xml"),
+                "('/test.xsl', 'text/xml', 'screen')",
+            ),
+        ]
+        for stylesheet, expected in testdata:
+            self.assertEqual(repr(stylesheet), expected)
+
     @requires_tz_support
     def test_feed_last_modified_time_naive_date(self):
         """

tests/syndication_tests/urls.py

@@ -36,8 +36,14 @@ urlpatterns = [
     path("syndication/articles/", feeds.ArticlesFeed()),
     path("syndication/template/", feeds.TemplateFeed()),
     path("syndication/template_context/", feeds.TemplateContextFeed()),
+    path("syndication/stylesheet/", feeds.TestFeedWithStylesheets()),
     path("syndication/rss2/single-enclosure/", feeds.TestSingleEnclosureRSSFeed()),
     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",
+    ),
 ]

tests/utils_tests/test_feedgenerator.py

@@ -1,7 +1,9 @@
 import datetime
+from unittest import mock
 
 from django.test import SimpleTestCase
 from django.utils import feedgenerator
+from django.utils.functional import SimpleLazyObject
 from django.utils.timezone import get_fixed_timezone
 
 
@@ -148,3 +150,12 @@ class FeedgeneratorTests(SimpleTestCase):
                     rss_feed.latest_post_date().tzinfo,
                     datetime.timezone.utc,
                 )
+
+    def test_stylesheet_keeps_lazy_urls(self):
+        m = mock.Mock(return_value="test.css")
+        stylesheet = feedgenerator.Stylesheet(SimpleLazyObject(m))
+        m.assert_not_called()
+        self.assertEqual(
+            str(stylesheet), 'href="test.css" type="text/css" media="screen"'
+        )
+        m.assert_called_once()