| 1 |
======================== |
| 2 |
How to create CSV output |
| 3 |
======================== |
| 4 |
|
| 5 |
This document explains how to output CSV (Comma Separated Values) dynamically |
| 6 |
using Django views. To do this, you can either use the Python CSV library or the |
| 7 |
Django template system. |
| 8 |
|
| 9 |
Using the Python CSV library |
| 10 |
============================ |
| 11 |
|
| 12 |
Python comes with a CSV library, :mod:`csv`. The key to using it with Django is |
| 13 |
that the :mod:`csv` module's CSV-creation capability acts on file-like objects, |
| 14 |
and Django's :class:`~django.http.HttpResponse` objects are file-like objects. |
| 15 |
|
| 16 |
Here's an example:: |
| 17 |
|
| 18 |
import csv |
| 19 |
from django.http import HttpResponse |
| 20 |
|
| 21 |
|
| 22 |
def some_view(request): |
| 23 |
# Create the HttpResponse object with the appropriate CSV header. |
| 24 |
response = HttpResponse( |
| 25 |
content_type="text/csv", |
| 26 |
headers={"Content-Disposition": 'attachment; filename="somefilename.csv"'}, |
| 27 |
) |
| 28 |
|
| 29 |
writer = csv.writer(response) |
| 30 |
writer.writerow(["First row", "Foo", "Bar", "Baz"]) |
| 31 |
writer.writerow(["Second row", "A", "B", "C", '"Testing"', "Here's a quote"]) |
| 32 |
|
| 33 |
return response |
| 34 |
|
| 35 |
The code and comments should be self-explanatory, but a few things deserve a |
| 36 |
mention: |
| 37 |
|
| 38 |
* The response gets a special MIME type, :mimetype:`text/csv`. This tells |
| 39 |
browsers that the document is a CSV file, rather than an HTML file. If |
| 40 |
you leave this off, browsers will probably interpret the output as HTML, |
| 41 |
which will result in ugly, scary gobbledygook in the browser window. |
| 42 |
|
| 43 |
* The response gets an additional ``Content-Disposition`` header, which |
| 44 |
contains the name of the CSV file. This filename is arbitrary; call it |
| 45 |
whatever you want. It'll be used by browsers in the "Save as..." dialog, etc. |
| 46 |
|
| 47 |
* You can hook into the CSV-generation API by passing ``response`` as the first |
| 48 |
argument to ``csv.writer``. The ``csv.writer`` function expects a file-like |
| 49 |
object, and :class:`~django.http.HttpResponse` objects fit the bill. |
| 50 |
|
| 51 |
* For each row in your CSV file, call ``writer.writerow``, passing it an |
| 52 |
:term:`iterable`. |
| 53 |
|
| 54 |
* The CSV module takes care of quoting for you, so you don't have to worry |
| 55 |
about escaping strings with quotes or commas in them. Pass ``writerow()`` |
| 56 |
your raw strings, and it'll do the right thing. |
| 57 |
|
| 58 |
.. _streaming-csv-files: |
| 59 |
|
| 60 |
Streaming large CSV files |
| 61 |
------------------------- |
| 62 |
|
| 63 |
When dealing with views that generate very large responses, you might want to |
| 64 |
consider using Django's :class:`~django.http.StreamingHttpResponse` instead. |
| 65 |
For example, by streaming a file that takes a long time to generate you can |
| 66 |
avoid a load balancer dropping a connection that might have otherwise timed out |
| 67 |
while the server was generating the response. |
| 68 |
|
| 69 |
In this example, we make full use of Python generators to efficiently handle |
| 70 |
the assembly and transmission of a large CSV file:: |
| 71 |
|
| 72 |
import csv |
| 73 |
|
| 74 |
from django.http import StreamingHttpResponse |
| 75 |
|
| 76 |
|
| 77 |
class Echo: |
| 78 |
"""An object that implements just the write method of the file-like |
| 79 |
interface. |
| 80 |
""" |
| 81 |
|
| 82 |
def write(self, value): |
| 83 |
"""Write the value by returning it, instead of storing in a buffer.""" |
| 84 |
return value |
| 85 |
|
| 86 |
|
| 87 |
def some_streaming_csv_view(request): |
| 88 |
"""A view that streams a large CSV file.""" |
| 89 |
# Generate a sequence of rows. The range is based on the maximum number of |
| 90 |
# rows that can be handled by a single sheet in most spreadsheet |
| 91 |
# applications. |
| 92 |
rows = (["Row {}".format(idx), str(idx)] for idx in range(65536)) |
| 93 |
pseudo_buffer = Echo() |
| 94 |
writer = csv.writer(pseudo_buffer) |
| 95 |
return StreamingHttpResponse( |
| 96 |
(writer.writerow(row) for row in rows), |
| 97 |
content_type="text/csv", |
| 98 |
headers={"Content-Disposition": 'attachment; filename="somefilename.csv"'}, |
| 99 |
) |
| 100 |
|
| 101 |
Using the template system |
| 102 |
========================= |
| 103 |
|
| 104 |
Alternatively, you can use the :doc:`Django template system </topics/templates>` |
| 105 |
to generate CSV. This is lower-level than using the convenient Python :mod:`csv` |
| 106 |
module, but the solution is presented here for completeness. |
| 107 |
|
| 108 |
The idea here is to pass a list of items to your template, and have the |
| 109 |
template output the commas in a :ttag:`for` loop. |
| 110 |
|
| 111 |
Here's an example, which generates the same CSV file as above:: |
| 112 |
|
| 113 |
from django.http import HttpResponse |
| 114 |
from django.template import loader |
| 115 |
|
| 116 |
|
| 117 |
def some_view(request): |
| 118 |
# Create the HttpResponse object with the appropriate CSV header. |
| 119 |
response = HttpResponse( |
| 120 |
content_type="text/csv", |
| 121 |
headers={"Content-Disposition": 'attachment; filename="somefilename.csv"'}, |
| 122 |
) |
| 123 |
|
| 124 |
# The data is hard-coded here, but you could load it from a database or |
| 125 |
# some other source. |
| 126 |
csv_data = ( |
| 127 |
("First row", "Foo", "Bar", "Baz"), |
| 128 |
("Second row", "A", "B", "C", '"Testing"', "Here's a quote"), |
| 129 |
) |
| 130 |
|
| 131 |
t = loader.get_template("my_template_name.txt") |
| 132 |
c = {"data": csv_data} |
| 133 |
response.write(t.render(c)) |
| 134 |
return response |
| 135 |
|
| 136 |
The only difference between this example and the previous example is that this |
| 137 |
one uses template loading instead of the CSV module. The rest of the code -- |
| 138 |
such as the ``content_type='text/csv'`` -- is the same. |
| 139 |
|
| 140 |
Then, create the template ``my_template_name.txt``, with this template code: |
| 141 |
|
| 142 |
.. code-block:: html+django |
| 143 |
|
| 144 |
{% for row in data %}"{{ row.0|addslashes }}", "{{ row.1|addslashes }}", "{{ row.2|addslashes }}", "{{ row.3|addslashes }}", "{{ row.4|addslashes }}" |
| 145 |
{% endfor %} |
| 146 |
|
| 147 |
This short template iterates over the given data and displays a line of CSV for |
| 148 |
each row. It uses the :tfilter:`addslashes` template filter to ensure there |
| 149 |
aren't any problems with quotes. |
| 150 |
|
| 151 |
Other text-based formats |
| 152 |
======================== |
| 153 |
|
| 154 |
Notice that there isn't very much specific to CSV here -- just the specific |
| 155 |
output format. You can use either of these techniques to output any text-based |
| 156 |
format you can dream of. You can also use a similar technique to generate |
| 157 |
arbitrary binary data; see :doc:`/howto/outputting-pdf` for an example. |