2 :mod:`csv` --- CSV File Reading and Writing
3 ===========================================
6 :synopsis: Write and read tabular data to and from delimited files.
7 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
16 The so-called CSV (Comma Separated Values) format is the most common import and
17 export format for spreadsheets and databases. There is no "CSV standard", so
18 the format is operationally defined by the many applications which read and
19 write it. The lack of a standard means that subtle differences often exist in
20 the data produced and consumed by different applications. These differences can
21 make it annoying to process CSV files from multiple sources. Still, while the
22 delimiters and quoting characters vary, the overall format is similar enough
23 that it is possible to write a single module which can efficiently manipulate
24 such data, hiding the details of reading and writing the data from the
27 The :mod:`csv` module implements classes to read and write tabular data in CSV
28 format. It allows programmers to say, "write this data in the format preferred
29 by Excel," or "read data from this file which was generated by Excel," without
30 knowing the precise details of the CSV format used by Excel. Programmers can
31 also describe the CSV formats understood by other applications or define their
32 own special-purpose CSV formats.
34 The :mod:`csv` module's :class:`reader` and :class:`writer` objects read and
35 write sequences. Programmers can also read and write data in dictionary form
36 using the :class:`DictReader` and :class:`DictWriter` classes.
40 This version of the :mod:`csv` module doesn't support Unicode input. Also,
41 there are currently some issues regarding ASCII NUL characters. Accordingly,
42 all input should be UTF-8 or printable ASCII to be safe; see the examples in
43 section :ref:`csv-examples`. These restrictions will be removed in the future.
48 :pep:`305` - CSV File API
49 The Python Enhancement Proposal which proposed this addition to Python.
57 The :mod:`csv` module defines the following functions:
60 .. function:: reader(csvfile[, dialect='excel'][, fmtparam])
62 Return a reader object which will iterate over lines in the given *csvfile*.
63 *csvfile* can be any object which supports the :term:`iterator` protocol and returns a
64 string each time its :meth:`next` method is called --- file objects and list
65 objects are both suitable. If *csvfile* is a file object, it must be opened
66 with the 'b' flag on platforms where that makes a difference. An optional
67 *dialect* parameter can be given which is used to define a set of parameters
68 specific to a particular CSV dialect. It may be an instance of a subclass of
69 the :class:`Dialect` class or one of the strings returned by the
70 :func:`list_dialects` function. The other optional *fmtparam* keyword arguments
71 can be given to override individual formatting parameters in the current
72 dialect. For full details about the dialect and formatting parameters, see
73 section :ref:`csv-fmt-params`.
75 All data read are returned as strings. No automatic data type conversion is
78 A short usage example::
81 >>> spamReader = csv.reader(open('eggs.csv'), delimiter=' ', quotechar='|')
82 >>> for row in spamReader:
83 ... print ', '.join(row)
84 Spam, Spam, Spam, Spam, Spam, Baked Beans
85 Spam, Lovely Spam, Wonderful Spam
87 .. versionchanged:: 2.5
88 The parser is now stricter with respect to multi-line quoted fields. Previously,
89 if a line ended within a quoted field without a terminating newline character, a
90 newline would be inserted into the returned field. This behavior caused problems
91 when reading files which contained carriage return characters within fields.
92 The behavior was changed to return the field without inserting newlines. As a
93 consequence, if newlines embedded within fields are important, the input should
94 be split into lines in a manner which preserves the newline characters.
97 .. function:: writer(csvfile[, dialect='excel'][, fmtparam])
99 Return a writer object responsible for converting the user's data into delimited
100 strings on the given file-like object. *csvfile* can be any object with a
101 :func:`write` method. If *csvfile* is a file object, it must be opened with the
102 'b' flag on platforms where that makes a difference. An optional *dialect*
103 parameter can be given which is used to define a set of parameters specific to a
104 particular CSV dialect. It may be an instance of a subclass of the
105 :class:`Dialect` class or one of the strings returned by the
106 :func:`list_dialects` function. The other optional *fmtparam* keyword arguments
107 can be given to override individual formatting parameters in the current
108 dialect. For full details about the dialect and formatting parameters, see
109 section :ref:`csv-fmt-params`. To make it
110 as easy as possible to interface with modules which implement the DB API, the
111 value :const:`None` is written as the empty string. While this isn't a
112 reversible transformation, it makes it easier to dump SQL NULL data values to
113 CSV files without preprocessing the data returned from a ``cursor.fetch*`` call.
114 All other non-string data are stringified with :func:`str` before being written.
116 A short usage example::
119 >>> spamWriter = csv.writer(open('eggs.csv', 'w'), delimiter=' ',
120 ... quotechar='|', quoting=QUOTE_MINIMAL)
121 >>> spamWriter.writerow(['Spam'] * 5 + ['Baked Beans'])
122 >>> spamWriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
125 .. function:: register_dialect(name[, dialect][, fmtparam])
127 Associate *dialect* with *name*. *name* must be a string or Unicode object. The
128 dialect can be specified either by passing a sub-class of :class:`Dialect`, or
129 by *fmtparam* keyword arguments, or both, with keyword arguments overriding
130 parameters of the dialect. For full details about the dialect and formatting
131 parameters, see section :ref:`csv-fmt-params`.
134 .. function:: unregister_dialect(name)
136 Delete the dialect associated with *name* from the dialect registry. An
137 :exc:`Error` is raised if *name* is not a registered dialect name.
140 .. function:: get_dialect(name)
142 Return the dialect associated with *name*. An :exc:`Error` is raised if *name*
143 is not a registered dialect name.
145 .. versionchanged:: 2.5
146 This function now returns an immutable :class:`Dialect`. Previously an
147 instance of the requested dialect was returned. Users could modify the
148 underlying class, changing the behavior of active readers and writers.
150 .. function:: list_dialects()
152 Return the names of all registered dialects.
155 .. function:: field_size_limit([new_limit])
157 Returns the current maximum field size allowed by the parser. If *new_limit* is
158 given, this becomes the new limit.
160 .. versionadded:: 2.5
162 The :mod:`csv` module defines the following classes:
165 .. class:: DictReader(csvfile[, fieldnames=None[, restkey=None[, restval=None[, dialect='excel'[, *args, **kwds]]]]])
167 Create an object which operates like a regular reader but maps the information
168 read into a dict whose keys are given by the optional *fieldnames* parameter.
169 If the *fieldnames* parameter is omitted, the values in the first row of the
170 *csvfile* will be used as the fieldnames. If the row read has fewer fields than
171 the fieldnames sequence, the value of *restval* will be used as the default
172 value. If the row read has more fields than the fieldnames sequence, the
173 remaining data is added as a sequence keyed by the value of *restkey*. If the
174 row read has fewer fields than the fieldnames sequence, the remaining keys take
175 the value of the optional *restval* parameter. Any other optional or keyword
176 arguments are passed to the underlying :class:`reader` instance.
179 .. class:: DictWriter(csvfile, fieldnames[, restval=''[, extrasaction='raise'[, dialect='excel'[, *args, **kwds]]]])
181 Create an object which operates like a regular writer but maps dictionaries onto
182 output rows. The *fieldnames* parameter identifies the order in which values in
183 the dictionary passed to the :meth:`writerow` method are written to the
184 *csvfile*. The optional *restval* parameter specifies the value to be written
185 if the dictionary is missing a key in *fieldnames*. If the dictionary passed to
186 the :meth:`writerow` method contains a key not found in *fieldnames*, the
187 optional *extrasaction* parameter indicates what action to take. If it is set
188 to ``'raise'`` a :exc:`ValueError` is raised. If it is set to ``'ignore'``,
189 extra values in the dictionary are ignored. Any other optional or keyword
190 arguments are passed to the underlying :class:`writer` instance.
192 Note that unlike the :class:`DictReader` class, the *fieldnames* parameter of
193 the :class:`DictWriter` is not optional. Since Python's :class:`dict` objects
194 are not ordered, there is not enough information available to deduce the order
195 in which the row should be written to the *csvfile*.
200 The :class:`Dialect` class is a container class relied on primarily for its
201 attributes, which are used to define the parameters for a specific
202 :class:`reader` or :class:`writer` instance.
207 The :class:`excel` class defines the usual properties of an Excel-generated CSV
208 file. It is registered with the dialect name ``'excel'``.
211 .. class:: excel_tab()
213 The :class:`excel_tab` class defines the usual properties of an Excel-generated
214 TAB-delimited file. It is registered with the dialect name ``'excel-tab'``.
219 The :class:`Sniffer` class is used to deduce the format of a CSV file.
221 The :class:`Sniffer` class provides two methods:
223 .. method:: Sniffer.sniff(sample[, delimiters=None])
225 Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the
226 parameters found. If the optional *delimiters* parameter is given, it is
227 interpreted as a string containing possible valid delimiter characters.
230 .. method:: Sniffer.has_header(sample)
232 Analyze the sample text (presumed to be in CSV format) and return :const:`True`
233 if the first row appears to be a series of column headers.
235 An example for :class:`Sniffer` use::
237 csvfile = open("example.csv")
238 dialect = csv.Sniffer().sniff(csvfile.read(1024))
240 reader = csv.reader(csvfile, dialect)
241 # ... process CSV file contents here ...
244 The :mod:`csv` module defines the following constants:
248 Instructs :class:`writer` objects to quote all fields.
251 .. data:: QUOTE_MINIMAL
253 Instructs :class:`writer` objects to only quote those fields which contain
254 special characters such as *delimiter*, *quotechar* or any of the characters in
258 .. data:: QUOTE_NONNUMERIC
260 Instructs :class:`writer` objects to quote all non-numeric fields.
262 Instructs the reader to convert all non-quoted fields to type *float*.
267 Instructs :class:`writer` objects to never quote fields. When the current
268 *delimiter* occurs in output data it is preceded by the current *escapechar*
269 character. If *escapechar* is not set, the writer will raise :exc:`Error` if
270 any characters that require escaping are encountered.
272 Instructs :class:`reader` to perform no special processing of quote characters.
274 The :mod:`csv` module defines the following exception:
279 Raised by any of the functions when an error is detected.
284 Dialects and Formatting Parameters
285 ----------------------------------
287 To make it easier to specify the format of input and output records, specific
288 formatting parameters are grouped together into dialects. A dialect is a
289 subclass of the :class:`Dialect` class having a set of specific methods and a
290 single :meth:`validate` method. When creating :class:`reader` or
291 :class:`writer` objects, the programmer can specify a string or a subclass of
292 the :class:`Dialect` class as the dialect parameter. In addition to, or instead
293 of, the *dialect* parameter, the programmer can also specify individual
294 formatting parameters, which have the same names as the attributes defined below
295 for the :class:`Dialect` class.
297 Dialects support the following attributes:
300 .. attribute:: Dialect.delimiter
302 A one-character string used to separate fields. It defaults to ``','``.
305 .. attribute:: Dialect.doublequote
307 Controls how instances of *quotechar* appearing inside a field should be
308 themselves be quoted. When :const:`True`, the character is doubled. When
309 :const:`False`, the *escapechar* is used as a prefix to the *quotechar*. It
310 defaults to :const:`True`.
312 On output, if *doublequote* is :const:`False` and no *escapechar* is set,
313 :exc:`Error` is raised if a *quotechar* is found in a field.
316 .. attribute:: Dialect.escapechar
318 A one-character string used by the writer to escape the *delimiter* if *quoting*
319 is set to :const:`QUOTE_NONE` and the *quotechar* if *doublequote* is
320 :const:`False`. On reading, the *escapechar* removes any special meaning from
321 the following character. It defaults to :const:`None`, which disables escaping.
324 .. attribute:: Dialect.lineterminator
326 The string used to terminate lines produced by the :class:`writer`. It defaults
331 The :class:`reader` is hard-coded to recognise either ``'\r'`` or ``'\n'`` as
332 end-of-line, and ignores *lineterminator*. This behavior may change in the
336 .. attribute:: Dialect.quotechar
338 A one-character string used to quote fields containing special characters, such
339 as the *delimiter* or *quotechar*, or which contain new-line characters. It
343 .. attribute:: Dialect.quoting
345 Controls when quotes should be generated by the writer and recognised by the
346 reader. It can take on any of the :const:`QUOTE_\*` constants (see section
347 :ref:`csv-contents`) and defaults to :const:`QUOTE_MINIMAL`.
350 .. attribute:: Dialect.skipinitialspace
352 When :const:`True`, whitespace immediately following the *delimiter* is ignored.
353 The default is :const:`False`.
359 Reader objects (:class:`DictReader` instances and objects returned by the
360 :func:`reader` function) have the following public methods:
363 .. method:: csvreader.next()
365 Return the next row of the reader's iterable object as a list, parsed according
366 to the current dialect.
368 Reader objects have the following public attributes:
371 .. attribute:: csvreader.dialect
373 A read-only description of the dialect in use by the parser.
376 .. attribute:: csvreader.line_num
378 The number of lines read from the source iterator. This is not the same as the
379 number of records returned, as records can span multiple lines.
381 .. versionadded:: 2.5
387 :class:`Writer` objects (:class:`DictWriter` instances and objects returned by
388 the :func:`writer` function) have the following public methods. A *row* must be
389 a sequence of strings or numbers for :class:`Writer` objects and a dictionary
390 mapping fieldnames to strings or numbers (by passing them through :func:`str`
391 first) for :class:`DictWriter` objects. Note that complex numbers are written
392 out surrounded by parens. This may cause some problems for other programs which
393 read CSV files (assuming they support complex numbers at all).
396 .. method:: csvwriter.writerow(row)
398 Write the *row* parameter to the writer's file object, formatted according to
402 .. method:: csvwriter.writerows(rows)
404 Write all the *rows* parameters (a list of *row* objects as described above) to
405 the writer's file object, formatted according to the current dialect.
407 Writer objects have the following public attribute:
410 .. attribute:: csvwriter.dialect
412 A read-only description of the dialect in use by the writer.
420 The simplest example of reading a CSV file::
423 reader = csv.reader(open("some.csv", "rb"))
427 Reading a file with an alternate format::
430 reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
434 The corresponding simplest possible writing example is::
437 writer = csv.writer(open("some.csv", "wb"))
438 writer.writerows(someiterable)
440 Registering a new dialect::
444 csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
446 reader = csv.reader(open("passwd", "rb"), 'unixpwd')
448 A slightly more advanced use of the reader --- catching and reporting errors::
451 filename = "some.csv"
452 reader = csv.reader(open(filename, "rb"))
457 sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
459 And while the module doesn't directly support parsing strings, it can easily be
463 for row in csv.reader(['one,two,three']):
466 The :mod:`csv` module doesn't directly support reading and writing Unicode, but
467 it is 8-bit-clean save for some problems with ASCII NUL characters. So you can
468 write functions or classes that handle the encoding and decoding for you as long
469 as you avoid encodings like UTF-16 that use NULs. UTF-8 is recommended.
471 :func:`unicode_csv_reader` below is a :term:`generator` that wraps :class:`csv.reader`
472 to handle Unicode CSV data (a list of Unicode strings). :func:`utf_8_encoder`
473 is a :term:`generator` that encodes the Unicode strings as UTF-8, one string (or row) at
474 a time. The encoded strings are parsed by the CSV reader, and
475 :func:`unicode_csv_reader` decodes the UTF-8-encoded cells back into Unicode::
479 def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs):
480 # csv.py doesn't do Unicode; encode temporarily as UTF-8:
481 csv_reader = csv.reader(utf_8_encoder(unicode_csv_data),
482 dialect=dialect, **kwargs)
483 for row in csv_reader:
484 # decode UTF-8 back to Unicode, cell by cell:
485 yield [unicode(cell, 'utf-8') for cell in row]
487 def utf_8_encoder(unicode_csv_data):
488 for line in unicode_csv_data:
489 yield line.encode('utf-8')
491 For all other encodings the following :class:`UnicodeReader` and
492 :class:`UnicodeWriter` classes can be used. They take an additional *encoding*
493 parameter in their constructor and make sure that the data passes the real
494 reader or writer encoded as UTF-8::
496 import csv, codecs, cStringIO
500 Iterator that reads an encoded stream and reencodes the input to UTF-8
502 def __init__(self, f, encoding):
503 self.reader = codecs.getreader(encoding)(f)
509 return self.reader.next().encode("utf-8")
513 A CSV reader which will iterate over lines in the CSV file "f",
514 which is encoded in the given encoding.
517 def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
518 f = UTF8Recoder(f, encoding)
519 self.reader = csv.reader(f, dialect=dialect, **kwds)
522 row = self.reader.next()
523 return [unicode(s, "utf-8") for s in row]
530 A CSV writer which will write rows to CSV file "f",
531 which is encoded in the given encoding.
534 def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
535 # Redirect output to a queue
536 self.queue = cStringIO.StringIO()
537 self.writer = csv.writer(self.queue, dialect=dialect, **kwds)
539 self.encoder = codecs.getincrementalencoder(encoding)()
541 def writerow(self, row):
542 self.writer.writerow([s.encode("utf-8") for s in row])
543 # Fetch UTF-8 output from the queue ...
544 data = self.queue.getvalue()
545 data = data.decode("utf-8")
546 # ... and reencode it into the target encoding
547 data = self.encoder.encode(data)
548 # write to the target stream
549 self.stream.write(data)
551 self.queue.truncate(0)
553 def writerows(self, rows):