Ticket #6304: single_feed.diff

django/contrib/syndication/views.py

@@ -1 +1 @@
 from django.contrib.syndication import feeds
 from django.http import HttpResponse, Http404
 
-def feed(request, url, feed_dict=None):
+def multiple_feeds(request, url, feed_dict=None):
     if not feed_dict:
-        raise Http404, "No feeds are registered."
+        raise Http404("No feeds are registered.")
 
+    url_params = url.split('/')
     try:
-        slug, param = url.split('/', 1)
-    except ValueError:
-        slug, param = url, ''
+        slug, rest = url_params[0], url_params[1:]
+    except IndexError:
+        raise Http404("Slug not provided.")
 
     try:
-        f = feed_dict[slug]
+        feed_class = feed_dict[slug]
     except KeyError:
-        raise Http404, "Slug %r isn't registered." % slug
+        raise Http404("Slug %r isn't registered." % slug)
 
+    return single_feed(request, slug, *rest, **{'feed_class': feed_class})
+
+# This function used to be called feed(). Keep this alias for backwards
+# compatibility.
+feed = multiple_feeds
+
+def single_feed(request, slug, *url_args, **url_kwargs):
     try:
-        feedgen = f(slug, request).get_feed(param)
+        feed_class = url_kwargs.pop('feed_class')
+    except KeyError:
+        raise ValueError('single_feed() requires a `feed_class` keyword argument')
+    if url_kwargs:
+        raise ValueError('single_feed() got unknown keyword argument(s): %s' % ', '.join(url_kwargs.keys()))
+    try:
+        feedgen = feed_class(slug, request).get_feed(url_args)
     except feeds.FeedDoesNotExist:
-        raise Http404, "Invalid feed parameters. Slug %r is valid, but other parameters, or lack thereof, are not." % slug
-
+        raise Http404("Invalid feed parameters: %r" % (url_args,))
     response = HttpResponse(mimetype=feedgen.mime_type)
     feedgen.write(response, 'utf-8')
     return response

django/contrib/syndication/feeds.py

@@ -55 +55 @@
                 return attr()
         return attr
 
-    def get_feed(self, url=None):
+    def get_feed(self, url_params):
         """
         Returns a feedgenerator.DefaultFeed object, fully populated, for
         this feed. Raises FeedDoesNotExist for invalid parameters.
         """
-        if url:
+        # url_params is a list of captured parameters (as strings) from the
+        # URLconf. It can be empty.
+        if url_params:
             try:
-                obj = self.get_object(url.split('/'))
+                obj = self.get_object(url_params)
             except (AttributeError, ObjectDoesNotExist):
                 raise FeedDoesNotExist
         else:

docs/syndication_feeds.txt

@@ -40 +40 @@
 To activate syndication feeds on your Django site, add this line to your
 URLconf_::
 
-    (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed', {'feed_dict': feeds}),
+    (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.multiple_feeds', {'feed_dict': feeds}),
 
 This tells Django to use the RSS framework to handle all URLs starting with
 ``"feeds/"``. (You can change that ``"feeds/"`` prefix to fit your own needs.)
 
+(Note that this ``multiple_feeds`` view used to be called ``feed``, but it's
+been renamed in the Django development version to be clearer, and to allow for
+other feed views, such as ``single_feed()``, which is explained below. However,
+if your code refers to the ``feed`` view, it will still work.)
+
 This URLconf line has an extra argument: ``{'feed_dict': feeds}``. Use this
 extra argument to pass the syndication framework the feeds that should be
 published under that URL.
@@ -65 +70 @@
 
     urlpatterns = patterns('',
         # ...
-        (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
+        (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.multiple_feeds',
             {'feed_dict': feeds}),
         # ...
     )
@@ -377 +382 @@
 
     urlpatterns = patterns('',
         # ...
-        (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.feed',
+        (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.multiple_feeds',
             {'feed_dict': feeds}),
         # ...
     )
@@ -786 +791 @@
 
         item_copyright = 'Copyright (c) 2007, Sally Smith' # Hard-coded copyright notice.
 
+The ``single_feed()`` view
+--------------------------
 
+**New in Django development version**
+
+Above, we explained that your URLconf should point at the ``multiple_feeds()``
+view, like so::
+
+    (r'^feeds/(?P<url>.*)/$', 'django.contrib.syndication.views.multiple_feeds', {'feed_dict': feeds}),
+
+However, as explained above, the ``multiple_feeds()`` view makes a few
+assumptions that may not be appropriate for your particular setup. Specifically:
+
+    * It assumes you have multiple feeds. It's overkill to have to define a
+      ``feed_dict`` if you only have a single feed.
+
+    * It uses very simple URL parsing -- the captured value of ``url`` is
+      simply split by the slash character (``'/'``) and passed to
+      ``Feed.get_object()``. This is slightly inconvenient in that it requires
+      your ``Feed`` class to handle URL parsing.
+
+As an alternative to the ``multiple_feeds()`` view, Django provides a
+``single_feed()`` view. The difference here is that ``single_feed()`` only
+applies to a single ``Feed`` class (as opposed to a ``feed_dict``), and it
+accepts captured URL arguments, which means you can keep your URL-parsing
+logic in your URLconf.
+
+For example, consider the chicagocrime.org "per-beat" feed explained above.
+Recall the per-beat feeds, with URLs like this:
+
+    * ``/rss/beats/0613/`` -- Returns recent crimes for beat 0613.
+    * ``/rss/beats/1424/`` -- Returns recent crimes for beat 1424.
+
+In the implementation above, the URL parsing was handled in
+``BeatFeed.get_object()``. But using ``single_feed()``, we can implement the
+URL parsing in the URLconf, like this::
+
+    (r'^feeds/(beats)/(\d\d\d\d)/$', 'django.contrib.syndication.views.multiple_feeds',
+        {'feed_class': feeds.BlockFeed}),
+
+Then, with the URL parsing taken care of by the URLconf,
+``BeatFeed.get_object()`` no longer has to parse a string. Instead, it's passed
+a list of parameters captured from the URL::
+
+    class BeatFeed(Feed):
+        def get_object(self, bits):
+            return Beat.objects.get(beat__exact=bits[0])
+
+Note that, unlike the ``single_feed()`` implementation of
+``BeatFeed.get_object()``, here we don't have to worry about checking for a
+wacky URL such as ``"/rss/beats/0613/foo/bar/baz/"``, because that will have
+been caught by the URLconf.
+
 The low-level framework
 =======================