Add attribute for XSLT, closes #37

As a consequence, rss_file will now use rss_str internally.
This means that the rss result is loaded into memory even
when writing to files, which could mean much poorer
performance for huge feeds in particular. If this is too
much, then we might reverse this commit, but I don't think
it will be much of a problem.

Author: tobinus

doc/user/basic_usage_guide/part_1.rst

@@ -56,6 +56,7 @@ Commonly used
     p.feed_url = "https://example.com/feeds/podcast.rss"  # URL of this feed
     p.category = Category("Technology", "Podcasting")
     p.owner = p.authors[0]
+    p.xslt = "https://example.com/feed/stylesheet.xsl"  # URL of XSLT stylesheet
 
 Read more:
 
@@ -65,6 +66,7 @@ Read more:
 * :attr:`~podgen.Podcast.feed_url`
 * :attr:`~podgen.Podcast.category`
 * :attr:`~podgen.Podcast.owner`
+* :attr:`~podgen.Podcast.xslt`
 
 
 Less commonly used

podgen/__main__.py

@@ -57,6 +57,7 @@ def main():
     p.complete = False
     p.new_feed_url = 'http://example.com/new-feed.rss'
     p.owner = Person('John Doe', '[email protected]')
+    p.xslt = "http://example.com/stylesheet.xsl"
 
     e1 = p.add_episode()
     e1.id = 'http://lernfunk.de/_MEDIAID_123#1'

podgen/podcast.py

@@ -15,7 +15,8 @@
 import dateutil.parser
 import dateutil.tz
 from podgen.episode import Episode
-from podgen.util import ensure_format, formatRFC2822, listToHumanreadableStr
+from podgen.util import ensure_format, formatRFC2822, listToHumanreadableStr, \
+    htmlencode
 from podgen.person import Person
 import podgen.version
 import sys
@@ -306,6 +307,37 @@ def __init__(self, **kwargs):
         .. _latest version of the standard: http://pubsubhubbub.github.io/PubSubHubbub/pubsubhubbub-core-0.4.html#rfc.section.4
         """
 
+        self.xslt = None
+        """
+        Absolute URL to the XSLT file which web browsers should use with this
+        feed.
+
+        `XSLT`_ stands for Extensible Stylesheet Language Transformations and
+        can be regarded as a template language made for transforming XML into
+        XHTML (among other things). You can use it to avoid giving users an
+        ugly XML listing when trying to subscribe to your podcast; this
+        technique is in fact employed by most podcast publishers today.
+        In a web browser, it looks like a web page, and to the
+        podcatchers, it looks like a normal podcast feed. To put it another
+        way, the very same URL can be used as an information web page about the
+        podcast as well as the URL you subscribe to in podcatchers.
+
+        :type: :obj:`str`
+        :RSS: Processor instruction right after the xml declaration called
+            ``xml-stylesheet``, with type set to ``text/xsl`` and href set to
+            this attribute.
+
+        .. note::
+
+           Firefox will use its own stylesheet for RSS feeds, so you
+           must test using another browser and possibly a `simple web server`_
+           (``python -m http.server 8000 -b 127.0.0.1``).
+
+        .. _XSLT: https://en.wikipedia.org/wiki/XSLT
+        .. _simple web server:
+           https://docs.python.org/3/library/http.server.html
+        """
+
         # Populate the podcast with the keyword arguments
         for attribute, value in iteritems(kwargs):
             if hasattr(self, attribute):
@@ -584,6 +616,34 @@ def _create_rss(self):
 
         return feed
 
+    def _add_xslt_pi(self, rss, xml_declaration):
+        """Add an XSLT processor instruction to the RSS string provided."""
+        # This is a hackish way of getting a processor instruction between
+        # the XML declaration and the RSS element; simply because lxml doesn't
+        # support processor instructions outside the root element. So we do
+        # a str.replace to replace the first newline with the processor
+        # instruction, since the XML declaration is followed by a newline.
+
+        # Get the processor instruction as a string
+        pi = self._get_xslt_pi()
+        if xml_declaration:
+            return rss.replace(
+             "\n",
+             '\n%s\n' % pi,
+             1)
+        else:
+            # No declaration, so just put it at the beginning (assuming the
+            # caller wants it there, why else would you set self.xslt?)
+            return pi + "\n" + rss
+
+    def _get_xslt_pi(self):
+        htmlescaped_url = htmlencode(self.xslt)
+        quote_sanitized = htmlescaped_url.replace('"', '').replace("\\", "")
+        return etree.tostring(etree.ProcessingInstruction(
+            "xml-stylesheet",
+            'type="text/xsl" href="' + quote_sanitized + '"',
+        ), encoding=str)
+
     def __str__(self):
         """Print the podcast in RSS format, using the default options.
 
@@ -607,14 +667,28 @@ def rss_str(self, minimize=False, encoding='UTF-8',
         :returns: The generated RSS feed as a :obj:`str`.
         """
         feed = self._create_rss()
-        return etree.tostring(feed, pretty_print=not minimize, encoding=encoding,
+        rss = etree.tostring(feed, pretty_print=not minimize, encoding=encoding,
                               xml_declaration=xml_declaration).decode(encoding)
-
+        if self.xslt:
+            return self._add_xslt_pi(rss, xml_declaration=xml_declaration)
+        else:
+            return rss
 
     def rss_file(self, filename, minimize=False,
                  encoding='UTF-8', xml_declaration=True):
         """Generate an RSS feed and write the resulting XML to a file.
 
+        .. note::
+
+           If atomicity is needed, then you are expected to provide that
+           yourself. That means that you should write the feed to a temporary
+           file which you rename to the final name afterwards; renaming is an
+           atomic operation on Unix(like) systems.
+
+        .. note::
+
+           File-like objects given to this method will not be closed.
+
         :param filename: Name of file to write, or a file-like object, or a URL.
         :type filename: str or fd
         :param minimize: Set to True to disable splitting the feed into multiple
@@ -628,10 +702,20 @@ def rss_file(self, filename, minimize=False,
         :type xml_declaration: bool
         :returns: Nothing.
         """
-        feed = self._create_rss()
-        doc = etree.ElementTree(feed)
-        doc.write(filename, pretty_print=not minimize, encoding=encoding,
-                  xml_declaration=xml_declaration)
+        rss = self.rss_str(minimize=minimize, encoding=encoding,
+                           xml_declaration=xml_declaration)
+        # Have we got a filename, or a file-like object?
+        if isinstance(filename, string_types):
+            # It is a string, assume it is filename
+            with open(filename, "w") as fd:
+                fd.write(rss)
+        elif hasattr(filename, "write"):
+            # It is file-like enough to fool us
+            filename.write(rss)
+        else:
+            raise TypeError("filename must either be a filename (str/unicode) "
+                            "or a file-like object (with write method); "
+                            "%s satisfies none of those conditions." % filename)
 
     def apply_episode_order(self):
         """Make sure that the episodes appear on iTunes in the exact order

podgen/tests/test_podcast.py

@@ -65,6 +65,7 @@ def setUp(self):
         self.owner = self.author
         self.complete = True
         self.new_feed_url = "https://example.com/feeds/myfeed2.rss"
+        self.xslt = "http://example.com/feed/stylesheet.xsl"
 
 
         fg.name = self.name
@@ -86,6 +87,7 @@ def setUp(self):
         fg.owner = self.owner
         fg.complete = self.complete
         fg.new_feed_url = self.new_feed_url
+        fg.xslt = self.xslt
 
         self.fg = fg
 
@@ -110,7 +112,8 @@ def test_constructor(self):
             image=self.image,
             owner=self.owner,
             complete=self.complete,
-            new_feed_url=self.new_feed_url
+            new_feed_url=self.new_feed_url,
+            xslt=self.xslt,
         )
         # Test that the fields are actually set
         self.test_baseFeed()
@@ -144,10 +147,15 @@ def test_baseFeed(self):
         assert fg.new_feed_url == self.new_feed_url
         assert fg.skip_days == self.skip_days
         assert fg.skip_hours == self.skip_hours
+        assert fg.xslt == self.xslt
 
     def test_rssFeedFile(self):
         fg = self.fg
+        rssString = self.getRssFeedFileContents(fg, xml_declaration=False)\
+            .replace('\n', '')
+        self.checkRssString(rssString)
 
+    def getRssFeedFileContents(self, fg, **kwargs):
         # Keep track of our temporary file and its filename
         filename = None
         file = None
@@ -158,10 +166,10 @@ def test_rssFeedFile(self):
             # Close the file; we will just use its name
             file.close()
             # Write the RSS to the file (overwriting it)
-            fg.rss_file(filename=filename, xml_declaration=False)
+            fg.rss_file(filename=filename, **kwargs)
             # Read the resulting RSS
             with open(filename, "r") as myfile:
-                rssString=myfile.read().replace('\n', '')
+                rssString = myfile.read()
         finally:
             # We don't need the file any longer, so delete it
             if filename:
@@ -175,14 +183,19 @@ def test_rssFeedFile(self):
                 # We were interrupted between entering the try-block and
                 # getting the temporary file. Not much we can do.
                 pass
+        return rssString
 
-        self.checkRssString(rssString)
 
     def test_rssFeedString(self):
         fg = self.fg
         rssString = fg.rss_str(xml_declaration=False)
         self.checkRssString(rssString)
 
+    def test_rssStringAndFileAreEqual(self):
+        rss_string = self.fg.rss_str()
+        rss_file = self.getRssFeedFileContents(self.fg)
+        self.assertEqual(rss_string, rss_file)
+
     def checkRssString(self, rssString):
         feed = etree.fromstring(rssString)
         nsRss = self.nsContent
@@ -491,5 +504,39 @@ def test_modifyingSkipHoursAfterwards(self):
         self.fg.skip_hours.remove(26)
         self.fg.rss_str()  # Now it works
 
+    # Tests for xslt
+    def test_xslt_str(self):
+        def use_str(**kwargs):
+            return self.fg.rss_str(**kwargs)
+        self.help_test_xslt_using(use_str)
+
+    def test_xslt_file(self):
+        def use_file(**kwargs):
+            return self.getRssFeedFileContents(self.fg, **kwargs)
+        self.help_test_xslt_using(use_file)
+
+    def help_test_xslt_using(self, generated_feed):
+        """Run tests for xslt, generating the feed str using the given function.
+        """
+        xslt_path = "http://example.com/mystylesheet.xsl"
+        xslt_pi = "<?xml-stylesheet"
+
+        # No xslt when set to None
+        self.fg.xslt = None
+        assert xslt_pi not in generated_feed()
+        assert xslt_pi not in generated_feed(minimize=True)
+        assert xslt_pi not in generated_feed(xml_declaration=False)
+
+        self.fg.xslt = xslt_path
+
+        # Now we have the stylesheet in there
+        assert xslt_pi in generated_feed()
+        assert xslt_pi in generated_feed(minimize=True)
+        assert xslt_pi in generated_feed(xml_declaration=False)
+
+        assert xslt_path in generated_feed()
+        assert xslt_path in generated_feed(minimize=True)
+        assert xslt_path in generated_feed(xml_declaration=False)
+
 if __name__ == '__main__':
     unittest.main()