Fixed #12978: Added support for RSS feed stylesheets.

django/contrib/syndication/views.py

@@ -160,6 +160,7 @@ def get_feed(self, obj, request):
             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),
+            stylesheet=self._get_dynamic_attr("stylesheet", obj),
             **self.feed_extra_kwargs(obj),
         )
 

django/utils/feedgenerator.py

@@ -24,6 +24,7 @@
 
 import datetime
 import email
+import mimetypes
 from io import StringIO
 from urllib.parse import urlparse
 
@@ -57,6 +58,40 @@ def get_tag_uri(url, date):
     return "tag:%s%s:%s/%s" % (bits.hostname, d, bits.path, bits.fragment)
 
 
+NOT_PROVIDED = object()
+
+
+class Stylesheet:
+    """An RSS stylesheet"""
+
+    MIMETYPE_OVERRIDES = {
+        # The official mimetype for XSLT files is technically `application/xslt+xml`
+        # but as of 2024 almost no browser support that.
+        "application/xslt+xml": "text/xsl",
+    }
+
+    def __init__(self, url, mimetype=NOT_PROVIDED, media="screen"):
+        self.url = iri_to_uri(url)
+
+        if mimetype is NOT_PROVIDED:
+            mimetype, _ = mimetypes.guess_type(self.url)
+            mimetype = self.MIMETYPE_OVERRIDES.get(mimetype, mimetype)
+
+        self.mimetype = mimetype
+        self.media = media
+
+    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,11 +110,19 @@ def __init__(
         feed_copyright=None,
         feed_guid=None,
         ttl=None,
+        stylesheet=None,
         **kwargs,
     ):
         def to_str(s):
             return str(s) if s is not None else s
 
+        def to_stylesheet(s):
+            if s is None:
+                return None
+            if isinstance(s, Stylesheet):
+                return s
+            return Stylesheet(s)
+
         categories = categories and [str(c) for c in categories]
         self.feed = {
             "title": to_str(title),
@@ -95,6 +138,7 @@ def to_str(s):
             "feed_copyright": to_str(feed_copyright),
             "id": feed_guid or link,
             "ttl": to_str(ttl),
+            "stylesheet": to_stylesheet(stylesheet),
             **kwargs,
         }
         self.items = []
@@ -166,6 +210,12 @@ def add_root_elements(self, handler):
         """
         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.
@@ -227,7 +277,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 +300,13 @@ 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 (stylesheet := self.feed["stylesheet"]) is not None:
+            handler.processingInstruction("xml-stylesheet", str(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.
 
+        # STYLESHEET -- One of the following three is optional. The framework
+        # looks for them in this order.
+
+        def stylesheet(self, obj):
+            """
+            Takes the object returned by get_object() and returns the feed's
+            stylesheet (an URL string or a Stylesheet instance).
+            """
+
+        def stylesheet(self):
+            """
+            Returns the feed's stylesheet (an URL string or a Stylesheet
+            instance).
+            """
+
+        stylesheet = "/link/to/stylesheet.xsl"
+        stylesheet = feedgenerator.Stylesheet("/link/to/stylesheet.xsl")
+
         # ITEMS -- One of the following three is required. The framework looks
         # for them in this order.
 
@@ -961,6 +979,7 @@ They share this interface:
     * ``feed_copyright``
     * ``feed_guid``
     * ``ttl``
+    * ``stylesheet``
 
     Any extra keyword arguments you pass to ``__init__`` will be stored in
     ``self.feed`` for use with `custom feed generators`_.
@@ -1095,3 +1114,67 @@ 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
+----------------
+
+.. versionadded:: 5.1
+
+You can add styling to your RSS feed using a stylesheet (typically in the XSLT_
+or CSS formats) by setting the ``stylesheet`` attribute on the feed class.
+
+This can be a hardcoded URL::
+
+    from django.contrib.syndication.views import Feed
+
+
+    class FeedWithHardcodedStylesheet(Feed):
+        ...  # author, etc.
+        stylesheet = "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.
+        stylesheet = 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):
+        ...  # author, etc.
+        stylesheet = 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):
+        ...  # author, etc.
+        stylesheet = 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):
+        ...  # author, etc.
+        stylesheet = Stylesheet("https://example.com/rss_stylesheet.xslt", media="print")
+
+.. _xslt: https://developer.mozilla.org/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT

docs/ref/utils.txt

@@ -331,6 +331,28 @@ 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.1
+
+.. class:: Stylesheet
+
+    Represents an RSS stylesheet
+
+    .. method:: __init__(url, mimetype, media="screen")
+
+        ``url`` is the URL of the stylesheet. This argument is required.
+
+        ``mimetype`` is the MIME type of the stylesheet. This argument is
+        optional. If not provided, 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.
+
+        ``media`` will be used as the ``media`` attribute of the stylesheet.
+        Django uses ``media="screen"`` by default. Use ``media=None`` if you
+        don't want your stylesheet to have a ``media`` attribute.
+
 ``SyndicationFeed``
 -------------------
 
@@ -339,7 +361,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, stylesheet=None, **kwargs)
 
         Initialize the feed with the given dictionary of metadata, which applies
         to the entire feed.
@@ -348,7 +370,12 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004
         ``self.feed``.
 
         All parameters should be strings, except ``categories``, which should
-        be a sequence of strings.
+        be a sequence of strings. The ``stylesheet`` argument can be a string
+        or an instance of :class:`Stylesheet`.
+
+        .. versionadded:: 5.1
+
+            The ``stylesheet`` 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 +395,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.1
+
+        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,7 +158,9 @@ Minor features
 :mod:`django.contrib.syndication`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* ...
+* All :class:`~django.utils.feedgenerator.SyndicationFeed` classes now support
+  a ``stylesheet`` attribute. If specified, an ``<? xml-stylesheet ?>``
+  processing instruction will be added to the top of the document.
 
 Asynchronous views
 ~~~~~~~~~~~~~~~~~~

tests/syndication_tests/feeds.py

@@ -236,6 +236,10 @@ def item_title(self, item):
         return "Title: %s" % item.title
 
 
+class TestFeedWithStylesheet(TestRss2Feed):
+    stylesheet = "/stylesheet.xsl"
+
+
 class NaiveDatesFeed(TestAtomFeed):
     """
     A feed with naive (non-timezone-aware) dates.