Fixed #13110 -- Added support for multiple enclosures in Atom feeds.

The ``item_enclosures`` hook returns a list of ``Enclosure`` objects which is
then used by the feed builder. If the feed is a RSS feed, an exception is
raised as RSS feeds don't allow multiple enclosures per feed item.

The ``item_enclosures`` hook defaults to an empty list or, if the
``item_enclosure_url`` hook is defined, to a list with a single ``Enclosure``
built from the ``item_enclosure_url``, ``item_enclosure_length``, and
``item_enclosure_mime_type`` hooks.

4 files changed, 61 insertions, 9 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index f37ec25179..fb3dc859c3 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -94,6 +94,9 @@ details on these changes.
 * The ``callable_obj`` keyword argument to
   ``SimpleTestCase.assertRaisesMessage()`` will be removed.
 
+* The ``enclosure`` keyword argument to ``SyndicationFeed.add_item()`` will be
+  removed.
+
 .. _deprecation-removed-in-1.10:
 
 1.10
diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt
index 4d0e3da100..0a91a16e40 100644
--- a/docs/ref/contrib/syndication.txt
+++ b/docs/ref/contrib/syndication.txt
@@ -298,10 +298,16 @@ Enclosures
 ----------
 
 To specify enclosures, such as those used in creating podcast feeds, use the
-``item_enclosure_url``, ``item_enclosure_length`` and
+``item_enclosures`` hook or, alternatively and if you only have a single
+enclosure per item, the ``item_enclosure_url``, ``item_enclosure_length``, and
 ``item_enclosure_mime_type`` hooks. See the ``ExampleFeed`` class below for
 usage examples.
 
+.. versionchanged:: 1.9
+
+    Support for multiple enclosures per feed item was added through the
+    ``item_enclosures`` hook.
+
 Language
 --------
 
@@ -742,8 +748,28 @@ This example illustrates all possible attributes and methods for a
 
         item_author_link = 'http://www.example.com/' # Hard-coded author URL.
 
+        # ITEM ENCLOSURES -- One of the following three is optional. The
+        # framework looks for them in this order. If one of them is defined,
+        # ``item_enclosure_url``, ``item_enclosure_length``, and
+        # ``item_enclosure_mime_type`` will have no effect.
+
+        def item_enclosures(self, item):
+            """
+            Takes an item, as returned by items(), and returns a list of
+            ``django.utils.feedgenerator.Enclosure`` objects.
+            """
+
+        def item_enclosure_url(self):
+            """
+            Returns the ``django.utils.feedgenerator.Enclosure`` list for every
+            item in the feed.
+            """
+
+        item_enclosures = []  # Hard-coded enclosure list
+
         # ITEM ENCLOSURE URL -- One of these three is required if you're
-        # publishing enclosures. The framework looks for them in this order.
+        # publishing enclosures and you're not using ``item_enclosures``. The
+        # framework looks for them in this order.
 
         def item_enclosure_url(self, item):
             """
@@ -759,9 +785,10 @@ This example illustrates all possible attributes and methods for a
         item_enclosure_url = "/foo/bar.mp3" # Hard-coded enclosure link.
 
         # ITEM ENCLOSURE LENGTH -- One of these three is required if you're
-        # publishing enclosures. The framework looks for them in this order.
-        # In each case, the returned value should be either an integer, or a
-        # string representation of the integer, in bytes.
+        # publishing enclosures and you're not using ``item_enclosures``. The
+        # framework looks for them in this order. In each case, the returned
+        # value should be either an integer, or a string representation of the
+        # integer, in bytes.
 
         def item_enclosure_length(self, item):
             """
@@ -777,7 +804,8 @@ This example illustrates all possible attributes and methods for a
         item_enclosure_length = 32000 # Hard-coded enclosure length.
 
         # ITEM ENCLOSURE MIME TYPE -- One of these three is required if you're
-        # publishing enclosures. The framework looks for them in this order.
+        # publishing enclosures and you're not using ``item_enclosures``. The
+        # framework looks for them in this order.
 
         def item_enclosure_mime_type(self, item):
             """
@@ -941,6 +969,7 @@ They share this interface:
     * ``comments``
     * ``unique_id``
     * ``enclosure``
+    * ``enclosures``
     * ``categories``
     * ``item_copyright``
     * ``ttl``
@@ -954,8 +983,15 @@ They share this interface:
     * ``updateddate`` should be a Python  :class:`~datetime.datetime` object.
     * ``enclosure`` should be an instance of
       :class:`django.utils.feedgenerator.Enclosure`.
+    * ``enclosures`` should be a list of
+      :class:`django.utils.feedgenerator.Enclosure` instances.
     * ``categories`` should be a sequence of Unicode objects.
 
+    .. deprecated:: 1.9
+
+        The ``enclosure`` keyword argument is deprecated in favor of the
+        ``enclosures`` keyword argument.
+
 :meth:`.SyndicationFeed.write`
     Outputs the feed in the given encoding to outfile, which is a file-like object.
 
diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index c416c82db1..c1df458872 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -351,11 +351,18 @@ SyndicationFeed
         All parameters should be Unicode objects, except ``categories``, which
         should be a sequence of Unicode objects.
 
-    .. method:: add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, updateddate=None, **kwargs)
+    .. method:: add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs)
 
         Adds an item to the feed. All args are expected to be Python ``unicode``
         objects except ``pubdate`` and ``updateddate``, which are ``datetime.datetime``
-        objects, and ``enclosure``, which is an instance of the ``Enclosure`` class.
+        objects, ``enclosure``, which is an ``Enclosure`` instance, and
+        ``enclosures``, which is a list of ``Enclosure`` instances.
+
+        .. deprecated:: 1.9
+
+            The ``enclosure`` keyword argument is deprecated in favor of the
+            new ``enclosures`` keyword argument which accepts a list of
+            ``Enclosure`` objects.
 
     .. method:: num_items()
 
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 30f812c4d9..411d8bc255 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -303,7 +303,9 @@ Minor features
 :mod:`django.contrib.syndication`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* ...
+* Support for multiple enclosures per feed item has been added. If multiple
+  enclosures are defined on a RSS feed, an exception is raised as RSS feeds,
+  unlike Atom feeds, do not support multiple enclosures per feed item.
 
 Cache
 ^^^^^
@@ -1265,6 +1267,10 @@ Miscellaneous
   :func:`~django.utils.safestring.mark_safe` when constructing the method's
   return value instead.
 
+* The ``enclosure`` keyword argument to ``SyndicationFeed.add_item()`` is
+  deprecated. Use the new ``enclosures`` argument which accepts a list of
+  ``Enclosure`` objects instead of a single one.
+
 .. removed-features-1.9:
 
 Features removed in 1.9