Debian Codegraph @

docs/howto/outputting-csv.txt

raw
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.