Merge pull request #41 from tobinus/link-to-xlst-#37

Add attribute for XSLT, closes #37

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()