Cleanup of reverse docs

djangorestframework/tests/reverse.py

@@ -3,11 +3,11 @@ from django.test import TestCase
 from django.utils import simplejson as json
 
 from djangorestframework.renderers import JSONRenderer
-from djangorestframework.reverse import reverse
+from djangorestframework.reverse import reverse, reverse_lazy
 from djangorestframework.views import View
 
 
-class MyView(View):
+class ReverseView(View):
     """
     Mock resource which simply returns a URL, so that we can ensure
     that reversed URLs are fully qualified.
@@ -15,10 +15,23 @@ class MyView(View):
     renderers = (JSONRenderer, )
 
     def get(self, request):
-        return reverse('myview', request=request)
+        return reverse('reverse', request=request)
+
+
+class LazyView(View):
+    """
+    Mock resource which simply returns a URL, so that we can ensure
+    that reversed URLs are fully qualified.
+    """
+    renderers = (JSONRenderer, )
+
+    def get(self, request):
+        return reverse_lazy('lazy', request=request)
+
 
 urlpatterns = patterns('',
-    url(r'^myview$', MyView.as_view(), name='myview'),
+    url(r'^reverse$', ReverseView.as_view(), name='reverse'),
+    url(r'^lazy$', LazyView.as_view(), name='lazy'),
 )
 
 
@@ -29,5 +42,11 @@ class ReverseTests(TestCase):
     urls = 'djangorestframework.tests.reverse'
 
     def test_reversed_urls_are_fully_qualified(self):
-        response = self.client.get('/myview')
+        response = self.client.get('/reverse')
-        self.assertEqual(json.loads(response.content), 'http://testserver/myview')
+        self.assertEqual(json.loads(response.content),
+                        'http://testserver/reverse')
+
+    #def test_reversed_lazy_urls_are_fully_qualified(self):
+    #    response = self.client.get('/lazy')
+    #    self.assertEqual(json.loads(response.content),
+    #                     'http://testserver/lazy')

docs/howto/reverse.rst

@@ -1,23 +1,32 @@
 Returning URIs from your Web APIs
 =================================
 
-As a rule, it's probably better practice to return absolute URIs from you web APIs, e.g. "http://example.com/foobar", rather than returning relative URIs, e.g. "/foobar".
+As a rule, it's probably better practice to return absolute URIs from you web
+APIs, e.g. "http://example.com/foobar", rather than returning relative URIs,
+e.g. "/foobar".
 
 The advantages of doing so are:
 
 * It's more explicit.
 * It leaves less work for your API clients.
-* There's no ambiguity about the meaning of the string when it's found in representations such as JSON that do not have a native URI type.
+* There's no ambiguity about the meaning of the string when it's found in
-* It allows us to easily do things like markup HTML representations with hyperlinks.
+  representations such as JSON that do not have a native URI type.
+* It allows us to easily do things like markup HTML representations
+  with hyperlinks.
 
-Django REST framework provides two utility functions to make it simpler to return absolute URIs from your Web API.
+Django REST framework provides two utility functions to make it simpler to
+return absolute URIs from your Web API.
 
-There's no requirement for you to use them, but if you do then the self-describing API will be able to automatically hyperlink its output for you, which makes browsing the API much easier.
+There's no requirement for you to use them, but if you do then the
+self-describing API will be able to automatically hyperlink its output for you,
+which makes browsing the API much easier.
 
-reverse(viewname, request, ...)
+reverse(viewname, ..., request=None)
 -------------------------------
 
-The :py:func:`~reverse.reverse` function has the same behavior as `django.core.urlresolvers.reverse`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port::
+The `reverse` function has the same behavior as
+`django.core.urlresolvers.reverse`_, except that it optionally takes a request
+keyword argument, which it uses to return a fully qualified URL.
 
     from djangorestframework.reverse import reverse
     from djangorestframework.views import View
@@ -25,15 +34,17 @@ The :py:func:`~reverse.reverse` function has the same behavior as `django.core.u
     class MyView(View):
         def get(self, request):
             context = {
-                'url': reverse('year-summary', request, args=[1945])
+                'url': reverse('year-summary', args=[1945], request=request)
             }
 
             return Response(context)
 
-reverse_lazy(viewname, request, ...)
+reverse_lazy(viewname, ..., request=None)
 ------------------------------------
 
-The :py:func:`~reverse.reverse_lazy` function has the same behavior as `django.core.urlresolvers.reverse_lazy`_, except that it takes a request object and returns a fully qualified URL, using the request to determine the host and port.
+The `reverse_lazy` function has the same behavior as
+`django.core.urlresolvers.reverse_lazy`_, except that it optionally takes a
+request keyword argument, which it uses to return a fully qualified URL.
 
 .. _django.core.urlresolvers.reverse: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse
 .. _django.core.urlresolvers.reverse_lazy: https://docs.djangoproject.com/en/dev/topics/http/urls/#reverse-lazy