Added section on passing contextual information to logging and documentation for...
[python.git] / Doc / library / csv.rst
blob89c9bf101441de2c37c214dbfa471d18c10899c4
2 :mod:`csv` --- CSV File Reading and Writing
3 ===========================================
5 .. module:: csv
6    :synopsis: Write and read tabular data to and from delimited files.
7 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
10 .. versionadded:: 2.3
12 .. index::
13    single: csv
14    pair: data; tabular
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
25 programmer.
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.
38 .. note::
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.
46 .. seealso::
48    :pep:`305` - CSV File API
49       The Python Enhancement Proposal which proposed this addition to Python.
52 .. _csv-contents:
54 Module Contents
55 ---------------
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
76    performed.
78    A short usage example::
80       >>> import csv
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::
118       >>> import csv
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*.
198 .. class:: Dialect
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.
205 .. class:: excel()
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'``.
217 .. class:: Sniffer()
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))
239    csvfile.seek(0)
240    reader = csv.reader(csvfile, dialect)
241    # ... process CSV file contents here ...
244 The :mod:`csv` module defines the following constants:
246 .. data:: QUOTE_ALL
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
255    *lineterminator*.
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*.
265 .. data:: QUOTE_NONE
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:
277 .. exception:: Error
279    Raised by any of the functions when an error is detected.
282 .. _csv-fmt-params:
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
327    to ``'\r\n'``.
329    .. note::
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
333       future.
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
340    defaults to ``'"'``.
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`.
356 Reader Objects
357 --------------
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
384 Writer Objects
385 --------------
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
399    the current dialect.
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.
415 .. _csv-examples:
417 Examples
418 --------
420 The simplest example of reading a CSV file::
422    import csv
423    reader = csv.reader(open("some.csv", "rb"))
424    for row in reader:
425        print row
427 Reading a file with an alternate format::
429    import csv
430    reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
431    for row in reader:
432        print row
434 The corresponding simplest possible writing example is::
436    import csv
437    writer = csv.writer(open("some.csv", "wb"))
438    writer.writerows(someiterable)
440 Registering a new dialect::
442    import csv
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::
450    import csv, sys
451    filename = "some.csv"
452    reader = csv.reader(open(filename, "rb"))
453    try:
454        for row in reader:
455            print row
456    except csv.Error, e:
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
460 done::
462    import csv
463    for row in csv.reader(['one,two,three']):
464        print row
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::
477    import csv
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
498    class UTF8Recoder:
499        """
500        Iterator that reads an encoded stream and reencodes the input to UTF-8
501        """
502        def __init__(self, f, encoding):
503            self.reader = codecs.getreader(encoding)(f)
505        def __iter__(self):
506            return self
508        def next(self):
509            return self.reader.next().encode("utf-8")
511    class UnicodeReader:
512        """
513        A CSV reader which will iterate over lines in the CSV file "f",
514        which is encoded in the given encoding.
515        """
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)
521        def next(self):
522            row = self.reader.next()
523            return [unicode(s, "utf-8") for s in row]
525        def __iter__(self):
526            return self
528    class UnicodeWriter:
529        """
530        A CSV writer which will write rows to CSV file "f",
531        which is encoded in the given encoding.
532        """
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)
538            self.stream = f
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)
550            # empty queue
551            self.queue.truncate(0)
553        def writerows(self, rows):
554            for row in rows:
555                self.writerow(row)