[1.9.x] Fixed #25969 -- Replaced render_to_response() with render() in docs examples.

Backport of 4d83b0163e from master

django/contrib/gis/maps/google/__init__.py

@@ -7,7 +7,7 @@
   Example:
 
    * In the view:
-      return render_to_response('template.html', {'google' : GoogleMap(key="abcdefg")})
+      return render(request, 'template.html', {'google': GoogleMap(key="abcdefg")})
 
    * In the template:
 

django/contrib/gis/maps/google/overlays.py

@@ -24,7 +24,7 @@ class GEvent(object):
 
     Example:
 
-      from django.shortcuts import render_to_response
+      from django.shortcuts import render
       from django.contrib.gis.maps.google import GoogleMap, GEvent, GPolyline
 
       def sample_request(request):
@@ -32,8 +32,9 @@ class GEvent(object):
           event = GEvent('click',
             'function() { location.href = "http://www.google.com"}')
           polyline.add_event(event)
-          return render_to_response('mytemplate.html',
+          return render(request, 'mytemplate.html', {
-          {'google' : GoogleMap(polylines=[polyline])})
+              'google': GoogleMap(polylines=[polyline]),
+          })
     """
 
     def __init__(self, event, action):
@@ -271,7 +272,7 @@ class GMarker(GOverlayBase):
 
     Example:
 
-      from django.shortcuts import render_to_response
+      from django.shortcuts import render
       from django.contrib.gis.maps.google.overlays import GMarker, GEvent
 
       def sample_request(request):
@@ -279,8 +280,9 @@ class GMarker(GOverlayBase):
           event = GEvent('click',
                          'function() { location.href = "http://www.google.com"}')
           marker.add_event(event)
-          return render_to_response('mytemplate.html',
+          return render(request, 'mytemplate.html', {
-                 {'google' : GoogleMap(markers=[marker])})
+              'google': GoogleMap(markers=[marker]),
+          })
     """
     def __init__(self, geom, title=None, draggable=False, icon=None):
         """

docs/internals/deprecation.txt

@@ -529,8 +529,8 @@ details on these changes.
   :class:`~django.template.response.SimpleTemplateResponse`, and
   :class:`~django.template.response.TemplateResponse`, will be removed.
   ``content_type`` should be used instead. This also applies to the
-  :func:`~django.shortcuts.render_to_response` shortcut and
+  ``render_to_response()`` shortcut and the sitemap views,
-  the sitemap views, :func:`~django.contrib.sitemaps.views.index` and
+  :func:`~django.contrib.sitemaps.views.index` and
   :func:`~django.contrib.sitemaps.views.sitemap`.
 
 * When :class:`~django.http.HttpResponse` is instantiated with an iterator,

docs/ref/csrf.txt

@@ -45,31 +45,11 @@ To take advantage of CSRF protection in your views, follow these steps:
    This should not be done for POST forms that target external URLs, since
    that would cause the CSRF token to be leaked, leading to a vulnerability.
 
-3. In the corresponding view functions, ensure that the
+3. In the corresponding view functions, ensure that
-   ``'django.template.context_processors.csrf'`` context processor is
+   :class:`~django.template.RequestContext` is used to render the response so
-   being used. Usually, this can be done in one of two ways:
+   that ``{% csrf_token %}`` will work properly. If you're using the
-
+   :func:`~django.shortcuts.render` function, generic views, or contrib apps,
-   1. Use RequestContext, which always uses
+   you are covered already since these all use ``RequestContext``.
-      ``'django.template.context_processors.csrf'`` (no matter what template
-      context processors are configured in the :setting:`TEMPLATES` setting).
-      If you are using generic views or contrib apps, you are covered already,
-      since these apps use RequestContext throughout.
-
-   2. Manually import and use the processor to generate the CSRF token and
-      add it to the template context. e.g.::
-
-          from django.shortcuts import render_to_response
-          from django.template.context_processors import csrf
-
-          def my_view(request):
-              c = {}
-              c.update(csrf(request))
-              # ... view code here
-              return render_to_response("a_template.html", c)
-
-      You may want to write your own
-      :func:`~django.shortcuts.render_to_response()` wrapper that takes care
-      of this step for you.
 
 .. _csrf-ajax:
 

docs/ref/template-response.txt

@@ -345,8 +345,7 @@ Using TemplateResponse and SimpleTemplateResponse
 
 A :class:`TemplateResponse` object can be used anywhere that a normal
 :class:`django.http.HttpResponse` can be used. It can also be used as an
-alternative to calling :func:`~django.shortcuts.render()` or
+alternative to calling :func:`~django.shortcuts.render()`.
-:func:`~django.shortcuts.render_to_response()`.
 
 For example, the following simple view returns a :class:`TemplateResponse`
 with a simple template and a context containing a queryset::

docs/releases/1.3.txt

@@ -321,7 +321,7 @@ requests. These include:
   template tags that require access to template context.
 
 * A new :meth:`~django.shortcuts.render()` shortcut -- an alternative
-  to :meth:`~django.shortcuts.render_to_response()` providing a
+  to ``django.shortcuts.render_to_response()`` providing a
   :class:`~django.template.RequestContext` by default.
 
 * Support for combining :class:`F expressions <django.db.models.F>`

docs/releases/1.7.txt

@@ -859,7 +859,7 @@ Templates
   * :func:`django.template.loader.get_template()`
   * :func:`django.template.loader.select_template()`
   * :func:`django.shortcuts.render()`
-  * :func:`django.shortcuts.render_to_response()`
+  * ``django.shortcuts.render_to_response()``
 
 * The :tfilter:`time` filter now accepts timezone-related :ref:`format
   specifiers <date-and-time-formatting-specifiers>` ``'e'``, ``'O'`` , ``'T'``
@@ -1830,8 +1830,7 @@ removed in Django 1.7 (please see the
 * :class:`~django.http.HttpResponse`,
   :class:`~django.template.response.SimpleTemplateResponse`,
   :class:`~django.template.response.TemplateResponse`,
-  :func:`~django.shortcuts.render_to_response`,
+  ``render_to_response()``, :func:`~django.contrib.sitemaps.views.index`, and
-  :func:`~django.contrib.sitemaps.views.index`, and
   :func:`~django.contrib.sitemaps.views.sitemap` no longer take a ``mimetype``
   argument
 

docs/releases/1.8.txt

@@ -1593,7 +1593,7 @@ The following functions will no longer accept a ``dirs`` parameter to override
 * :func:`django.template.loader.get_template()`
 * :func:`django.template.loader.select_template()`
 * :func:`django.shortcuts.render()`
-* :func:`django.shortcuts.render_to_response()`
+* ``django.shortcuts.render_to_response()``
 
 The parameter didn't work consistently across different template loaders and
 didn't work for included templates.

docs/topics/cache.txt

@@ -1114,11 +1114,12 @@ The headers you pass to ``vary_on_headers`` are not case sensitive;
 You can also use a helper function, :func:`django.utils.cache.patch_vary_headers`,
 directly. This function sets, or adds to, the ``Vary header``. For example::
 
+    from django.shortcuts import render
     from django.utils.cache import patch_vary_headers
 
     def my_view(request):
         # ...
-        response = render_to_response('template_name', context)
+        response = render(request, 'template_name', context)
         patch_vary_headers(response, ['Cookie'])
         return response
 

docs/topics/forms/formsets.txt

@@ -582,7 +582,7 @@ The only thing you will want to be aware of is making sure to use the
 management form inside the template. Let's look at a sample view::
 
     from django.forms import formset_factory
-    from django.shortcuts import render_to_response
+    from django.shortcuts import render
     from myapp.forms import ArticleForm
 
     def manage_articles(request):
@@ -594,7 +594,7 @@ management form inside the template. Let's look at a sample view::
                 pass
         else:
             formset = ArticleFormSet()
-        return render_to_response('manage_articles.html', {'formset': formset})
+        return render(request, 'manage_articles.html', {'formset': formset})
 
 The ``manage_articles.html`` template might look like this:
 
@@ -659,7 +659,7 @@ more than one formset to be sent to a view without name clashing. Lets take
 a look at how this might be accomplished::
 
     from django.forms import formset_factory
-    from django.shortcuts import render_to_response
+    from django.shortcuts import render
     from myapp.forms import ArticleForm, BookForm
 
     def manage_articles(request):
@@ -674,7 +674,7 @@ a look at how this might be accomplished::
         else:
             article_formset = ArticleFormSet(prefix='articles')
             book_formset = BookFormSet(prefix='books')
-        return render_to_response('manage_articles.html', {
+        return render(request, 'manage_articles.html', {
             'article_formset': article_formset,
             'book_formset': book_formset,
         })

docs/topics/forms/modelforms.txt

@@ -954,7 +954,7 @@ Model formsets are very similar to formsets. Let's say we want to present a
 formset to edit ``Author`` model instances::
 
     from django.forms import modelformset_factory
-    from django.shortcuts import render_to_response
+    from django.shortcuts import render
     from myapp.models import Author
 
     def manage_authors(request):
@@ -966,9 +966,7 @@ formset to edit ``Author`` model instances::
                 # do something.
         else:
             formset = AuthorFormSet()
-        return render_to_response("manage_authors.html", {
+        return render(request, 'manage_authors.html', {'formset': formset})
-            "formset": formset,
-        })
 
 As you can see, the view logic of a model formset isn't drastically different
 than that of a "normal" formset. The only difference is that we call
@@ -1022,7 +1020,7 @@ As stated earlier, you can override the default queryset used by the model
 formset::
 
     from django.forms import modelformset_factory
-    from django.shortcuts import render_to_response
+    from django.shortcuts import render
     from myapp.models import Author
 
     def manage_authors(request):
@@ -1035,9 +1033,7 @@ formset::
                 # Do something.
         else:
             formset = AuthorFormSet(queryset=Author.objects.filter(name__startswith='O'))
-        return render_to_response("manage_authors.html", {
+        return render(request, 'manage_authors.html", {'formset': formset})
-            "formset": formset,
-        })
 
 Note that we pass the ``queryset`` argument in both the ``POST`` and ``GET``
 cases in this example.
@@ -1213,9 +1209,7 @@ of a model. Here's how you can do that::
                 return HttpResponseRedirect(author.get_absolute_url())
         else:
             formset = BookInlineFormSet(instance=author)
-        return render_to_response("manage_books.html", {
+        return render(request, 'manage_books.html', {'formset': formset})
-            "formset": formset,
-        })
 
 Notice how we pass ``instance`` in both the ``POST`` and ``GET`` cases.
 

docs/topics/http/file-uploads.txt

@@ -45,7 +45,7 @@ form as described in :ref:`binding-uploaded-files`. This would look
 something like::
 
     from django.http import HttpResponseRedirect
-    from django.shortcuts import render_to_response
+    from django.shortcuts import render
     from .forms import UploadFileForm
 
     # Imaginary function to handle an uploaded file.
@@ -59,7 +59,7 @@ something like::
                 return HttpResponseRedirect('/success/url/')
         else:
             form = UploadFileForm()
-        return render_to_response('upload.html', {'form': form})
+        return render(request, 'upload.html', {'form': form})
 
 Notice that we have to pass :attr:`request.FILES <django.http.HttpRequest.FILES>`
 into the form's constructor; this is how file data gets bound into a form.

docs/topics/http/sessions.txt

@@ -457,6 +457,9 @@ yourself. Do this after you've verified that the test cookie worked.
 
 Here's a typical usage example::
 
+    from django.http import HttpResponse
+    from django.shortcuts import render
+
     def login(request):
         if request.method == 'POST':
             if request.session.test_cookie_worked():
@@ -465,7 +468,7 @@ Here's a typical usage example::
             else:
                 return HttpResponse("Please enable cookies and try again.")
         request.session.set_test_cookie()
-        return render_to_response('foo/login_form.html')
+        return render(request, 'foo/login_form.html')
 
 Using sessions out of views
 ===========================

docs/topics/http/shortcuts.txt

@@ -20,10 +20,6 @@ introduce controlled coupling for convenience's sake.
    Combines a given template with a given context dictionary and returns an
    :class:`~django.http.HttpResponse` object with that rendered text.
 
-   :func:`render()` is the same as a call to
-   :func:`render_to_response()` with a ``context_instance`` argument that
-   forces the use of a :class:`~django.template.RequestContext`.
-
    Django does not provide a shortcut function which returns a
    :class:`~django.template.response.TemplateResponse` because the constructor
    of :class:`~django.template.response.TemplateResponse` offers the same level
@@ -36,7 +32,10 @@ Required arguments
     The request object used to generate this response.
 
 ``template_name``
-    The full name of a template to use or sequence of template names.
+    The full name of a template to use or sequence of template names. If a
+    sequence is given, the first template that exists will be used. See the
+    :ref:`template loading documentation <template-loading>` for more
+    information on how templates are found.
 
 Optional arguments
 ------------------
@@ -119,8 +118,9 @@ This example is equivalent to::
 
 .. function:: render_to_response(template_name, context=None, context_instance=_context_instance_undefined, content_type=None, status=None, dirs=_dirs_undefined, using=None)
 
-   Renders a given template with a given context dictionary and returns an
+   This function preceded the introduction of :func:`render` and works
-   :class:`~django.http.HttpResponse` object with that rendered text.
+   similarly except that it doesn't making the ``request`` available in the
+   response. It's not recommended and is likely to be deprecated in the future.
 
 Required arguments
 ------------------
@@ -180,31 +180,6 @@ Optional arguments
 
    The ``dirs`` parameter was deprecated.
 
-Example
--------
-
-The following example renders the template ``myapp/index.html`` with the
-MIME type :mimetype:`application/xhtml+xml`::
-
-    from django.shortcuts import render_to_response
-
-    def my_view(request):
-        # View code here...
-        return render_to_response('myapp/index.html', {"foo": "bar"},
-            content_type="application/xhtml+xml")
-
-This example is equivalent to::
-
-    from django.http import HttpResponse
-    from django.template import Context, loader
-
-    def my_view(request):
-        # View code here...
-        t = loader.get_template('myapp/index.html')
-        c = Context({'foo': 'bar'})
-        return HttpResponse(t.render(c),
-            content_type="application/xhtml+xml")
-
 ``redirect``
 ============
 

docs/topics/http/views.txt

@@ -112,7 +112,7 @@ standard error page for your application, along with an HTTP error code 404.
 Example usage::
 
     from django.http import Http404
-    from django.shortcuts import render_to_response
+    from django.shortcuts import render
     from polls.models import Poll
 
     def detail(request, poll_id):
@@ -120,7 +120,7 @@ Example usage::
             p = Poll.objects.get(pk=poll_id)
         except Poll.DoesNotExist:
             raise Http404("Poll does not exist")
-        return render_to_response('polls/detail.html', {'poll': p})
+        return render(request, 'polls/detail.html', {'poll': p})
 
 In order to show customized HTML when Django returns a 404, you can create an
 HTML template named ``404.html`` and place it in the top level of your

docs/topics/pagination.txt

@@ -86,6 +86,7 @@ show how you can display the results. This example assumes you have a
 The view function looks like this::
 
     from django.core.paginator import Paginator, EmptyPage, PageNotAnInteger
+    from django.shortcuts import render
 
     def listing(request):
         contact_list = Contacts.objects.all()
@@ -101,7 +102,7 @@ The view function looks like this::
             # If page is out of range (e.g. 9999), deliver last page of results.
             contacts = paginator.page(paginator.num_pages)
 
-        return render_to_response('list.html', {"contacts": contacts})
+        return render(request, 'list.html', {'contacts': contacts})
 
 In the template :file:`list.html`, you'll want to include navigation between
 pages along with any interesting information from the objects themselves::

docs/topics/templates.txt

@@ -309,9 +309,8 @@ templates, Django provides a shortcut function which automates the process.
 
             The ``request`` argument was added.
 
-See also the :func:`~django.shortcuts.render()` and
+See also the :func:`~django.shortcuts.render()` shortcut which calls
-:func:`~django.shortcuts.render_to_response()` shortcuts, which call
+:func:`render_to_string()` and feeds the result into an
-:func:`render_to_string()` and feed the result into an
 :class:`~django.http.HttpResponse` suitable for returning from a view.
 
 Finally, you can use configured engines directly: