Fixed #31789 -- Added a new headers interface to HttpResponse.

6 files changed, 42 insertions, 16 deletions

diff --git a/docs/howto/outputting-csv.txt b/docs/howto/outputting-csv.txt
index 2886a1b294..dc3cf57cfd 100644
--- a/docs/howto/outputting-csv.txt
+++ b/docs/howto/outputting-csv.txt
@@ -21,7 +21,7 @@ Here's an example::
     def some_view(request):
         # Create the HttpResponse object with the appropriate CSV header.
         response = HttpResponse(content_type='text/csv')
-        response['Content-Disposition'] = 'attachment; filename="somefilename.csv"'
+        response.headers['Content-Disposition'] = 'attachment; filename="somefilename.csv"'
 
         writer = csv.writer(response)
         writer.writerow(['First row', 'Foo', 'Bar', 'Baz'])
@@ -88,7 +88,7 @@ the assembly and transmission of a large CSV file::
         writer = csv.writer(pseudo_buffer)
         response = StreamingHttpResponse((writer.writerow(row) for row in rows),
                                          content_type="text/csv")
-        response['Content-Disposition'] = 'attachment; filename="somefilename.csv"'
+        response.headers['Content-Disposition'] = 'attachment; filename="somefilename.csv"'
         return response
 
 Using the template system
@@ -109,7 +109,7 @@ Here's an example, which generates the same CSV file as above::
     def some_view(request):
         # Create the HttpResponse object with the appropriate CSV header.
         response = HttpResponse(content_type='text/csv')
-        response['Content-Disposition'] = 'attachment; filename="somefilename.csv"'
+        response.headers['Content-Disposition'] = 'attachment; filename="somefilename.csv"'
 
         # The data is hard-coded here, but you could load it from a database or
         # some other source.
diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt
index 6b3ec54dd5..40063becc9 100644
--- a/docs/ref/request-response.txt
+++ b/docs/ref/request-response.txt
@@ -700,17 +700,29 @@ generators are immediately closed.
 If you need the response to be streamed from the iterator to the client, you
 must use the :class:`StreamingHttpResponse` class instead.
 
+.. _setting-header-fields:
+
 Setting header fields
 ~~~~~~~~~~~~~~~~~~~~~
 
-To set or remove a header field in your response, treat it like a dictionary::
+To set or remove a header field in your response, use
+:attr:`HttpResponse.headers`::
+
+    >>> response = HttpResponse()
+    >>> response.headers['Age'] = 120
+    >>> del response.headers['Age']
+
+You can also manipulate headers by treating your response like a dictionary::
 
     >>> response = HttpResponse()
     >>> response['Age'] = 120
     >>> del response['Age']
 
-Note that unlike a dictionary, ``del`` doesn't raise ``KeyError`` if the header
-field doesn't exist.
+This proxies to ``HttpResponse.headers``, and is the original interface offered
+by ``HttpResponse``.
+
+When using this interface, unlike a dictionary, ``del`` doesn't raise
+``KeyError`` if the header field doesn't exist.
 
 For setting the ``Cache-Control`` and ``Vary`` header fields, it is recommended
 to use the :func:`~django.utils.cache.patch_cache_control` and
@@ -722,6 +734,10 @@ middleware, are not removed.
 HTTP header fields cannot contain newlines. An attempt to set a header field
 containing a newline character (CR or LF) will raise ``BadHeaderError``
 
+.. versionchanged:: 3.2
+
+    The :attr:`HttpResponse.headers` interface was added.
+
 Telling the browser to treat the response as a file attachment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -730,7 +746,7 @@ To tell the browser to treat the response as a file attachment, use the
 this is how you might return a Microsoft Excel spreadsheet::
 
     >>> response = HttpResponse(my_data, content_type='application/vnd.ms-excel')
-    >>> response['Content-Disposition'] = 'attachment; filename="foo.xls"'
+    >>> response.headers['Content-Disposition'] = 'attachment; filename="foo.xls"'
 
 There's nothing Django-specific about the ``Content-Disposition`` header, but
 it's easy to forget the syntax, so we've included it here.
@@ -742,6 +758,13 @@ Attributes
 
     A bytestring representing the content, encoded from a string if necessary.
 
+.. attribute:: HttpResponse.headers
+
+    .. versionadded:: 3.2
+
+    A case insensitive, dict-like object that provides an interface to all
+    HTTP headers on the response. See :ref:`setting-header-fields`.
+
 .. attribute:: HttpResponse.charset
 
     A string denoting the charset in which the response will be encoded. If not
diff --git a/docs/releases/3.2.txt b/docs/releases/3.2.txt
index 9000b170eb..30cc6a401a 100644
--- a/docs/releases/3.2.txt
+++ b/docs/releases/3.2.txt
@@ -309,7 +309,10 @@ Pagination
 Requests and Responses
 ~~~~~~~~~~~~~~~~~~~~~~
 
-* ...
+* Response headers are now stored in :attr:`.HttpResponse.headers`. This can be
+  used instead of the original dict-like interface of ``HttpResponse`` objects.
+  Both interfaces will continue to be supported. See
+  :ref:`setting-header-fields` for details.
 
 Security
 ~~~~~~~~
diff --git a/docs/topics/cache.txt b/docs/topics/cache.txt
index ccaa82277f..4e1b2546ad 100644
--- a/docs/topics/cache.txt
+++ b/docs/topics/cache.txt
@@ -1159,10 +1159,10 @@ In this case, a caching mechanism (such as Django's own cache middleware) will
 cache a separate version of the page for each unique user-agent.
 
 The advantage to using the ``vary_on_headers`` decorator rather than manually
-setting the ``Vary`` header (using something like
-``response['Vary'] = 'user-agent'``) is that the decorator *adds* to the
-``Vary`` header (which may already exist), rather than setting it from scratch
-and potentially overriding anything that was already in there.
+setting the ``Vary`` header (using something like ``response.headers['Vary'] =
+'user-agent'``) is that the decorator *adds* to the ``Vary`` header (which may
+already exist), rather than setting it from scratch and potentially overriding
+anything that was already in there.
 
 You can pass multiple headers to ``vary_on_headers()``::
 
diff --git a/docs/topics/class-based-views/index.txt b/docs/topics/class-based-views/index.txt
index 3ec00f7361..8874545469 100644
--- a/docs/topics/class-based-views/index.txt
+++ b/docs/topics/class-based-views/index.txt
@@ -119,7 +119,7 @@ And the view::
             last_book = self.get_queryset().latest('publication_date')
             response = HttpResponse()
             # RFC 1123 date format
-            response['Last-Modified'] = last_book.publication_date.strftime('%a, %d %b %Y %H:%M:%S GMT')
+            response.headers['Last-Modified'] = last_book.publication_date.strftime('%a, %d %b %Y %H:%M:%S GMT')
             return response
 
 If the view is accessed from a ``GET`` request, an object list is returned in
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index 741acd604c..6d96731c79 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -551,9 +551,9 @@ Specifically, a ``Response`` object has the following attributes:
         If the given URL is not found, accessing this attribute will raise a
         :exc:`~django.urls.Resolver404` exception.
 
-You can also use dictionary syntax on the response object to query the value
-of any settings in the HTTP headers. For example, you could determine the
-content type of a response using ``response['Content-Type']``.
+As with a normal response, you can also access the headers through
+:attr:`.HttpResponse.headers`. For example, you could determine the content
+type of a response using ``response.headers['Content-Type']``.
 
 Exceptions
 ----------