UserString.MutableString has been removed in Python 3.0.
[python.git] / Doc / library / csv.rst
blobeef3cfd25a7fc3200f58903fbdb49be2321a1d2c
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:: sniff(sample[, delimiters=None])
225       Analyze the given *sample* and return a :class:`Dialect` subclass
226       reflecting the parameters found.  If the optional *delimiters* parameter
227       is given, it is interpreted as a string containing possible valid
228       delimiter characters.
231    .. method:: has_header(sample)
233       Analyze the sample text (presumed to be in CSV format) and return
234       :const:`True` if the first row appears to be a series of column headers.
236 An example for :class:`Sniffer` use::
238    csvfile = open("example.csv")
239    dialect = csv.Sniffer().sniff(csvfile.read(1024))
240    csvfile.seek(0)
241    reader = csv.reader(csvfile, dialect)
242    # ... process CSV file contents here ...
245 The :mod:`csv` module defines the following constants:
247 .. data:: QUOTE_ALL
249    Instructs :class:`writer` objects to quote all fields.
252 .. data:: QUOTE_MINIMAL
254    Instructs :class:`writer` objects to only quote those fields which contain
255    special characters such as *delimiter*, *quotechar* or any of the characters in
256    *lineterminator*.
259 .. data:: QUOTE_NONNUMERIC
261    Instructs :class:`writer` objects to quote all non-numeric fields.
263    Instructs the reader to convert all non-quoted fields to type *float*.
266 .. data:: QUOTE_NONE
268    Instructs :class:`writer` objects to never quote fields.  When the current
269    *delimiter* occurs in output data it is preceded by the current *escapechar*
270    character.  If *escapechar* is not set, the writer will raise :exc:`Error` if
271    any characters that require escaping are encountered.
273    Instructs :class:`reader` to perform no special processing of quote characters.
275 The :mod:`csv` module defines the following exception:
278 .. exception:: Error
280    Raised by any of the functions when an error is detected.
283 .. _csv-fmt-params:
285 Dialects and Formatting Parameters
286 ----------------------------------
288 To make it easier to specify the format of input and output records, specific
289 formatting parameters are grouped together into dialects.  A dialect is a
290 subclass of the :class:`Dialect` class having a set of specific methods and a
291 single :meth:`validate` method.  When creating :class:`reader` or
292 :class:`writer` objects, the programmer can specify a string or a subclass of
293 the :class:`Dialect` class as the dialect parameter.  In addition to, or instead
294 of, the *dialect* parameter, the programmer can also specify individual
295 formatting parameters, which have the same names as the attributes defined below
296 for the :class:`Dialect` class.
298 Dialects support the following attributes:
301 .. attribute:: Dialect.delimiter
303    A one-character string used to separate fields.  It defaults to ``','``.
306 .. attribute:: Dialect.doublequote
308    Controls how instances of *quotechar* appearing inside a field should be
309    themselves be quoted.  When :const:`True`, the character is doubled. When
310    :const:`False`, the *escapechar* is used as a prefix to the *quotechar*.  It
311    defaults to :const:`True`.
313    On output, if *doublequote* is :const:`False` and no *escapechar* is set,
314    :exc:`Error` is raised if a *quotechar* is found in a field.
317 .. attribute:: Dialect.escapechar
319    A one-character string used by the writer to escape the *delimiter* if *quoting*
320    is set to :const:`QUOTE_NONE` and the *quotechar* if *doublequote* is
321    :const:`False`. On reading, the *escapechar* removes any special meaning from
322    the following character. It defaults to :const:`None`, which disables escaping.
325 .. attribute:: Dialect.lineterminator
327    The string used to terminate lines produced by the :class:`writer`. It defaults
328    to ``'\r\n'``.
330    .. note::
332       The :class:`reader` is hard-coded to recognise either ``'\r'`` or ``'\n'`` as
333       end-of-line, and ignores *lineterminator*. This behavior may change in the
334       future.
337 .. attribute:: Dialect.quotechar
339    A one-character string used to quote fields containing special characters, such
340    as the *delimiter* or *quotechar*, or which contain new-line characters.  It
341    defaults to ``'"'``.
344 .. attribute:: Dialect.quoting
346    Controls when quotes should be generated by the writer and recognised by the
347    reader.  It can take on any of the :const:`QUOTE_\*` constants (see section
348    :ref:`csv-contents`) and defaults to :const:`QUOTE_MINIMAL`.
351 .. attribute:: Dialect.skipinitialspace
353    When :const:`True`, whitespace immediately following the *delimiter* is ignored.
354    The default is :const:`False`.
357 Reader Objects
358 --------------
360 Reader objects (:class:`DictReader` instances and objects returned by the
361 :func:`reader` function) have the following public methods:
364 .. method:: csvreader.next()
366    Return the next row of the reader's iterable object as a list, parsed according
367    to the current dialect.
369 Reader objects have the following public attributes:
372 .. attribute:: csvreader.dialect
374    A read-only description of the dialect in use by the parser.
377 .. attribute:: csvreader.line_num
379    The number of lines read from the source iterator. This is not the same as the
380    number of records returned, as records can span multiple lines.
382    .. versionadded:: 2.5
385 Writer Objects
386 --------------
388 :class:`Writer` objects (:class:`DictWriter` instances and objects returned by
389 the :func:`writer` function) have the following public methods.  A *row* must be
390 a sequence of strings or numbers for :class:`Writer` objects and a dictionary
391 mapping fieldnames to strings or numbers (by passing them through :func:`str`
392 first) for :class:`DictWriter` objects.  Note that complex numbers are written
393 out surrounded by parens. This may cause some problems for other programs which
394 read CSV files (assuming they support complex numbers at all).
397 .. method:: csvwriter.writerow(row)
399    Write the *row* parameter to the writer's file object, formatted according to
400    the current dialect.
403 .. method:: csvwriter.writerows(rows)
405    Write all the *rows* parameters (a list of *row* objects as described above) to
406    the writer's file object, formatted according to the current dialect.
408 Writer objects have the following public attribute:
411 .. attribute:: csvwriter.dialect
413    A read-only description of the dialect in use by the writer.
416 .. _csv-examples:
418 Examples
419 --------
421 The simplest example of reading a CSV file::
423    import csv
424    reader = csv.reader(open("some.csv", "rb"))
425    for row in reader:
426        print row
428 Reading a file with an alternate format::
430    import csv
431    reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
432    for row in reader:
433        print row
435 The corresponding simplest possible writing example is::
437    import csv
438    writer = csv.writer(open("some.csv", "wb"))
439    writer.writerows(someiterable)
441 Registering a new dialect::
443    import csv
445    csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
447    reader = csv.reader(open("passwd", "rb"), 'unixpwd')
449 A slightly more advanced use of the reader --- catching and reporting errors::
451    import csv, sys
452    filename = "some.csv"
453    reader = csv.reader(open(filename, "rb"))
454    try:
455        for row in reader:
456            print row
457    except csv.Error, e:
458        sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
460 And while the module doesn't directly support parsing strings, it can easily be
461 done::
463    import csv
464    for row in csv.reader(['one,two,three']):
465        print row
467 The :mod:`csv` module doesn't directly support reading and writing Unicode, but
468 it is 8-bit-clean save for some problems with ASCII NUL characters.  So you can
469 write functions or classes that handle the encoding and decoding for you as long
470 as you avoid encodings like UTF-16 that use NULs.  UTF-8 is recommended.
472 :func:`unicode_csv_reader` below is a :term:`generator` that wraps :class:`csv.reader`
473 to handle Unicode CSV data (a list of Unicode strings).  :func:`utf_8_encoder`
474 is a :term:`generator` that encodes the Unicode strings as UTF-8, one string (or row) at
475 a time.  The encoded strings are parsed by the CSV reader, and
476 :func:`unicode_csv_reader` decodes the UTF-8-encoded cells back into Unicode::
478    import csv
480    def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs):
481        # csv.py doesn't do Unicode; encode temporarily as UTF-8:
482        csv_reader = csv.reader(utf_8_encoder(unicode_csv_data),
483                                dialect=dialect, **kwargs)
484        for row in csv_reader:
485            # decode UTF-8 back to Unicode, cell by cell:
486            yield [unicode(cell, 'utf-8') for cell in row]
488    def utf_8_encoder(unicode_csv_data):
489        for line in unicode_csv_data:
490            yield line.encode('utf-8')
492 For all other encodings the following :class:`UnicodeReader` and
493 :class:`UnicodeWriter` classes can be used. They take an additional *encoding*
494 parameter in their constructor and make sure that the data passes the real
495 reader or writer encoded as UTF-8::
497    import csv, codecs, cStringIO
499    class UTF8Recoder:
500        """
501        Iterator that reads an encoded stream and reencodes the input to UTF-8
502        """
503        def __init__(self, f, encoding):
504            self.reader = codecs.getreader(encoding)(f)
506        def __iter__(self):
507            return self
509        def next(self):
510            return self.reader.next().encode("utf-8")
512    class UnicodeReader:
513        """
514        A CSV reader which will iterate over lines in the CSV file "f",
515        which is encoded in the given encoding.
516        """
518        def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
519            f = UTF8Recoder(f, encoding)
520            self.reader = csv.reader(f, dialect=dialect, **kwds)
522        def next(self):
523            row = self.reader.next()
524            return [unicode(s, "utf-8") for s in row]
526        def __iter__(self):
527            return self
529    class UnicodeWriter:
530        """
531        A CSV writer which will write rows to CSV file "f",
532        which is encoded in the given encoding.
533        """
535        def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
536            # Redirect output to a queue
537            self.queue = cStringIO.StringIO()
538            self.writer = csv.writer(self.queue, dialect=dialect, **kwds)
539            self.stream = f
540            self.encoder = codecs.getincrementalencoder(encoding)()
542        def writerow(self, row):
543            self.writer.writerow([s.encode("utf-8") for s in row])
544            # Fetch UTF-8 output from the queue ...
545            data = self.queue.getvalue()
546            data = data.decode("utf-8")
547            # ... and reencode it into the target encoding
548            data = self.encoder.encode(data)
549            # write to the target stream
550            self.stream.write(data)
551            # empty queue
552            self.queue.truncate(0)
554        def writerows(self, rows):
555            for row in rows:
556                self.writerow(row)