Fixed #16470 -- Allowed FileResponse to auto-set some Content headers.

Thanks Simon Charette, Jon Dufresne, and Tim Graham for the reviews.

3 files changed, 66 insertions, 71 deletions

diff --git a/docs/howto/outputting-pdf.txt b/docs/howto/outputting-pdf.txt
index fa911df169..9950c4316c 100644
--- a/docs/howto/outputting-pdf.txt
+++ b/docs/howto/outputting-pdf.txt
@@ -41,21 +41,21 @@ Write your view
 ===============
 
 The key to generating PDFs dynamically with Django is that the ReportLab API
-acts on file-like objects, and Django's :class:`~django.http.HttpResponse`
-objects are file-like objects.
+acts on file-like objects, and Django's :class:`~django.http.FileResponse`
+objects accept file-like objects.
 
 Here's a "Hello World" example::
 
-    from django.http import HttpResponse
+    import io
+    from django.http import FileResponse
     from reportlab.pdfgen import canvas
 
     def some_view(request):
-        # Create the HttpResponse object with the appropriate PDF headers.
-        response = HttpResponse(content_type='application/pdf')
-        response['Content-Disposition'] = 'attachment; filename="somefilename.pdf"'
+        # Create a file-like buffer to receive PDF data.
+        buffer = io.BytesIO()
 
-        # Create the PDF object, using the response object as its "file."
-        p = canvas.Canvas(response)
+        # Create the PDF object, using the buffer as its "file."
+        p = canvas.Canvas(buffer)
 
         # Draw things on the PDF. Here's where the PDF generation happens.
         # See the ReportLab documentation for the full list of functionality.
@@ -64,37 +64,35 @@ Here's a "Hello World" example::
         # Close the PDF object cleanly, and we're done.
         p.showPage()
         p.save()
-        return response
+
+        # FileResponse sets the Content-Disposition header so that browsers
+        # present the option to save the file.
+        return FileResponse(buffer, as_attachment=True, filename='hello.pdf')
 
 The code and comments should be self-explanatory, but a few things deserve a
 mention:
 
-* The response gets a special MIME type, :mimetype:`application/pdf`. This
-  tells browsers that the document is a PDF file, rather than an HTML file.
-  If you leave this off, browsers will probably interpret the output as
-  HTML, which would result in ugly, scary gobbledygook in the browser
-  window.
-
-* The response gets an additional ``Content-Disposition`` header, which
-  contains the name of the PDF file. This filename is arbitrary: Call it
-  whatever you want. It'll be used by browsers in the "Save as..." dialog, etc.
+* The response will automatically set the MIME type :mimetype:`application/pdf`
+  based on the filename extension. This tells browsers that the document is a
+  PDF file, rather than an HTML file or a generic `application/octet-stream`
+  binary content.
 
-* The ``Content-Disposition`` header starts with ``'attachment; '`` in this
-  example. This forces Web browsers to pop-up a dialog box
-  prompting/confirming how to handle the document even if a default is set
-  on the machine. If you leave off ``'attachment;'``, browsers will handle
-  the PDF using whatever program/plugin they've been configured to use for
-  PDFs. Here's what that code would look like::
+* When ``as_attachment=True`` is passed to ``FileResponse``, it sets the
+  appropriate ``Content-Disposition`` header and that tells Web browsers to
+  pop-up a dialog box prompting/confirming how to handle the document even if a
+  default is set on the machine. If the ``as_attachment`` parameter is omitted,
+  browsers will handle the PDF using whatever program/plugin they've been
+  configured to use for PDFs.
 
-      response['Content-Disposition'] = 'filename="somefilename.pdf"'
+* You can provide an arbitrary ``filename`` parameter. It'll be used by browsers
+  in the "Save as..." dialog.
 
-* Hooking into the ReportLab API is easy: Just pass ``response`` as the
-  first argument to ``canvas.Canvas``. The ``Canvas`` class expects a
-  file-like object, and :class:`~django.http.HttpResponse` objects fit the
-  bill.
+* Hooking into the ReportLab API is easy: The same buffer passed as the first
+  argument to ``canvas.Canvas`` can be fed to the
+  :class:`~django.http.FileResponse` class.
 
 * Note that all subsequent PDF-generation methods are called on the PDF
-  object (in this case, ``p``) -- not on ``response``.
+  object (in this case, ``p``) -- not on ``buffer``.
 
 * Finally, it's important to call ``showPage()`` and ``save()`` on the PDF
   file.
@@ -105,42 +103,6 @@ mention:
     with building PDF-generating Django views that are accessed by many people
     at the same time.
 
-Complex PDFs
-============
-
-If you're creating a complex PDF document with ReportLab, consider using the
-:mod:`io` library as a temporary holding place for your PDF file. This
-library provides a file-like object interface that is particularly efficient.
-Here's the above "Hello World" example rewritten to use :mod:`io`::
-
-    from io import BytesIO
-    from reportlab.pdfgen import canvas
-    from django.http import HttpResponse
-
-    def some_view(request):
-        # Create the HttpResponse object with the appropriate PDF headers.
-        response = HttpResponse(content_type='application/pdf')
-        response['Content-Disposition'] = 'attachment; filename="somefilename.pdf"'
-
-        buffer = BytesIO()
-
-        # Create the PDF object, using the BytesIO object as its "file."
-        p = canvas.Canvas(buffer)
-
-        # Draw things on the PDF. Here's where the PDF generation happens.
-        # See the ReportLab documentation for the full list of functionality.
-        p.drawString(100, 100, "Hello world.")
-
-        # Close the PDF object cleanly.
-        p.showPage()
-        p.save()
-
-        # Get the value of the BytesIO buffer and write it to the response.
-        pdf = buffer.getvalue()
-        buffer.close()
-        response.write(pdf)
-        return response
-
 Other formats
 =============
 
diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt
index 0caf37bc99..05cb24f3b1 100644
--- a/docs/ref/request-response.txt
+++ b/docs/ref/request-response.txt
@@ -1054,17 +1054,45 @@ Attributes
 ``FileResponse`` objects
 ========================
 
-.. class:: FileResponse
+.. class:: FileResponse(open_file, as_attachment=False, filename='', **kwargs)
 
-:class:`FileResponse` is a subclass of :class:`StreamingHttpResponse` optimized
-for binary files. It uses `wsgi.file_wrapper`_ if provided by the wsgi server,
-otherwise it streams the file out in small chunks.
+    :class:`FileResponse` is a subclass of :class:`StreamingHttpResponse`
+    optimized for binary files. It uses `wsgi.file_wrapper`_ if provided by the
+    wsgi server, otherwise it streams the file out in small chunks.
+
+    If ``as_attachment=True``, the ``Content-Disposition`` header is set, which
+    asks the browser to offer the file to the user as a download.
+
+    If ``open_file`` doesn't have a name or if the name of ``open_file`` isn't
+    appropriate, provide a custom file name using the ``filename``  parameter.
+
+    The ``Content-Length``, ``Content-Type``, and ``Content-Disposition``
+    headers are automatically set when they can be guessed from contents of
+    ``open_file``.
+
+    .. versionadded:: 2.1
+
+        The ``as_attachment`` and ``filename`` keywords argument were added.
+        Also, ``FileResponse`` sets the ``Content`` headers if it can guess
+        them.
 
 .. _wsgi.file_wrapper: https://www.python.org/dev/peps/pep-3333/#optional-platform-specific-file-handling
 
-``FileResponse`` expects a file open in binary mode like so::
+``FileResponse`` accepts any file-like object with binary content, for example
+a file open in binary mode like so::
 
     >>> from django.http import FileResponse
     >>> response = FileResponse(open('myfile.png', 'rb'))
 
 The file will be closed automatically, so don't open it with a context manager.
+
+Methods
+-------
+
+.. method:: FileResponse.set_headers(open_file)
+
+    .. versionadded:: 2.1
+
+    This method is automatically called during the response initialization and
+    set various headers (``Content-Length``, ``Content-Type``, and
+    ``Content-Disposition``) depending on ``open_file``.
diff --git a/docs/releases/2.1.txt b/docs/releases/2.1.txt
index bc565d51b1..083488491c 100644
--- a/docs/releases/2.1.txt
+++ b/docs/releases/2.1.txt
@@ -255,6 +255,11 @@ Requests and Responses
 * Added the ``samesite`` argument to :meth:`.HttpResponse.set_cookie` to allow
   setting the ``SameSite`` cookie flag.
 
+* The new ``as_attachment`` argument for :class:`~django.http.FileResponse`
+  sets the ``Content-Disposition`` header to make the browser ask if the user
+  wants to download the file. ``FileResponse`` also tries to set the
+  ``Content-Type`` and ``Content-Length`` headers where appropriate.
+
 Serialization
 ~~~~~~~~~~~~~