cpython-lru_cache-weakref: Doc/library/csv.rst annotate

annotate Doc/library/csv.rst @ 79675:c0a2294de787 2.7

Issue #16199: Backport 2to3 typo fix from 3.2.

author	Chris Jerdonek <chris.jerdonek@gmail.com>
date	Thu, 11 Oct 2012 16:15:46 -0700
parents	ade667076c14
children	4e9617d3c514

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 :mod:`csv` --- CSV File Reading and Writing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3 ===========================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 .. module:: csv
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 :synopsis: Write and read tabular data to and from delimited files.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 .. versionadded:: 2.3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13 single: csv
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 pair: data; tabular
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 The so-called CSV (Comma Separated Values) format is the most common import and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 export format for spreadsheets and databases. There is no "CSV standard", so
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 the format is operationally defined by the many applications which read and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 write it. The lack of a standard means that subtle differences often exist in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 the data produced and consumed by different applications. These differences can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 make it annoying to process CSV files from multiple sources. Still, while the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 delimiters and quoting characters vary, the overall format is similar enough
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 that it is possible to write a single module which can efficiently manipulate
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 such data, hiding the details of reading and writing the data from the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 programmer.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 The :mod:`csv` module implements classes to read and write tabular data in CSV
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 format. It allows programmers to say, "write this data in the format preferred
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 by Excel," or "read data from this file which was generated by Excel," without
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30 knowing the precise details of the CSV format used by Excel. Programmers can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31 also describe the CSV formats understood by other applications or define their
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 own special-purpose CSV formats.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 The :mod:`csv` module's :class:`reader` and :class:`writer` objects read and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 write sequences. Programmers can also read and write data in dictionary form
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36 using the :class:`DictReader` and :class:`DictWriter` classes.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	37
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	38 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	39
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40 This version of the :mod:`csv` module doesn't support Unicode input. Also,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 there are currently some issues regarding ASCII NUL characters. Accordingly,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 all input should be UTF-8 or printable ASCII to be safe; see the examples in
77923 c1945703c7cb Adapt mentions of future changes in doc Éric Araujo <merwok@netwok.org> parents: 77102 diff changeset	43 section :ref:`csv-examples`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46 .. seealso::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 :pep:`305` - CSV File API
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49 The Python Enhancement Proposal which proposed this addition to Python.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52 .. _csv-contents:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 Module Contents
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 ---------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 The :mod:`csv` module defines the following functions:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59
78782 dc080e19f7aa #14880: Fix kwargs notation in csv.reader, .writer & .register_dialect Hynek Schlawack <hs@ox.cx> parents: 77923 diff changeset	60 .. function:: reader(csvfile, dialect='excel', **fmtparams)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 Return a reader object which will iterate over lines in the given csvfile.
43630 6df985744d96 Add :term:s for iterator. Georg Brandl <georg@python.org> parents: 43629 diff changeset	63 csvfile can be any object which supports the :term:`iterator` protocol and returns a
56817 6b05d48cca28 Merged revisions 74207 via svnmerge from Georg Brandl <georg@python.org> parents: 56807 diff changeset	64 string each time its :meth:`!next` method is called --- file objects and list
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 objects are both suitable. If csvfile is a file object, it must be opened
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 with the 'b' flag on platforms where that makes a difference. An optional
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67 dialect parameter can be given which is used to define a set of parameters
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68 specific to a particular CSV dialect. It may be an instance of a subclass of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 the :class:`Dialect` class or one of the strings returned by the
78782 dc080e19f7aa #14880: Fix kwargs notation in csv.reader, .writer & .register_dialect Hynek Schlawack <hs@ox.cx> parents: 77923 diff changeset	70 :func:`list_dialects` function. The other optional fmtparams keyword arguments
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 can be given to override individual formatting parameters in the current
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 dialect. For full details about the dialect and formatting parameters, see
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73 section :ref:`csv-fmt-params`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74
56807 096b42ccb258 Merged revisions 70590,70650,70704,70768-70769,70776,71008,71010-71011 via svnmerge from Georg Brandl <georg@python.org> parents: 55695 diff changeset	75 Each row read from the csv file is returned as a list of strings. No
096b42ccb258 Merged revisions 70590,70650,70704,70768-70769,70776,71008,71010-71011 via svnmerge from Georg Brandl <georg@python.org> parents: 55695 diff changeset	76 automatic data type conversion is performed.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 43765 diff changeset	78 A short usage example::
50522 ee9ced92843a Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from Georg Brandl <georg@python.org> parents: 48198 diff changeset	79
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 43765 diff changeset	80 >>> import csv
79029 ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	81 >>> with open('eggs.csv', 'rb') as csvfile:
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	82 ... spamreader = csv.reader(csvfile, delimiter=' ', quotechar='\|')
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	83 ... for row in spamreader:
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	84 ... print ', '.join(row)
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 43765 diff changeset	85 Spam, Spam, Spam, Spam, Spam, Baked Beans
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 43765 diff changeset	86 Spam, Lovely Spam, Wonderful Spam
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 43765 diff changeset	87
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 .. versionchanged:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 The parser is now stricter with respect to multi-line quoted fields. Previously,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 if a line ended within a quoted field without a terminating newline character, a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 newline would be inserted into the returned field. This behavior caused problems
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 when reading files which contained carriage return characters within fields.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93 The behavior was changed to return the field without inserting newlines. As a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 consequence, if newlines embedded within fields are important, the input should
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 be split into lines in a manner which preserves the newline characters.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97
78782 dc080e19f7aa #14880: Fix kwargs notation in csv.reader, .writer & .register_dialect Hynek Schlawack <hs@ox.cx> parents: 77923 diff changeset	98 .. function:: writer(csvfile, dialect='excel', **fmtparams)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 Return a writer object responsible for converting the user's data into delimited
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 strings on the given file-like object. csvfile can be any object with a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 :func:`write` method. If csvfile is a file object, it must be opened with the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103 'b' flag on platforms where that makes a difference. An optional dialect
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 parameter can be given which is used to define a set of parameters specific to a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 particular CSV dialect. It may be an instance of a subclass of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 :class:`Dialect` class or one of the strings returned by the
78782 dc080e19f7aa #14880: Fix kwargs notation in csv.reader, .writer & .register_dialect Hynek Schlawack <hs@ox.cx> parents: 77923 diff changeset	107 :func:`list_dialects` function. The other optional fmtparams keyword arguments
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 can be given to override individual formatting parameters in the current
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 dialect. For full details about the dialect and formatting parameters, see
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 section :ref:`csv-fmt-params`. To make it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 as easy as possible to interface with modules which implement the DB API, the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 value :const:`None` is written as the empty string. While this isn't a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 reversible transformation, it makes it easier to dump SQL NULL data values to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114 CSV files without preprocessing the data returned from a ``cursor.fetch*`` call.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 All other non-string data are stringified with :func:`str` before being written.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 43765 diff changeset	117 A short usage example::
40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 43765 diff changeset	118
79029 ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	119 import csv
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	120 with open('eggs.csv', 'wb') as csvfile:
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	121 spamwriter = csv.writer(csvfile, delimiter=' ',
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	122 quotechar='\|', quoting=csv.QUOTE_MINIMAL)
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	123 spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	124 spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
44176 40fc840517fc Add examples to csv, pprint and traceback docs. Georg Brandl <georg@python.org> parents: 43765 diff changeset	125
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126
78782 dc080e19f7aa #14880: Fix kwargs notation in csv.reader, .writer & .register_dialect Hynek Schlawack <hs@ox.cx> parents: 77923 diff changeset	127 .. function:: register_dialect(name[, dialect], **fmtparams)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129 Associate dialect with name. name must be a string or Unicode object. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 dialect can be specified either by passing a sub-class of :class:`Dialect`, or
78782 dc080e19f7aa #14880: Fix kwargs notation in csv.reader, .writer & .register_dialect Hynek Schlawack <hs@ox.cx> parents: 77923 diff changeset	131 by fmtparams keyword arguments, or both, with keyword arguments overriding
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 parameters of the dialect. For full details about the dialect and formatting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133 parameters, see section :ref:`csv-fmt-params`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	134
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136 .. function:: unregister_dialect(name)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138 Delete the dialect associated with name from the dialect registry. An
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 :exc:`Error` is raised if name is not a registered dialect name.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 .. function:: get_dialect(name)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144 Return the dialect associated with name. An :exc:`Error` is raised if name
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 is not a registered dialect name.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146
43763 1891257dfd11 Note change to get_dialect semantics in 2.5. Will backport to 2.5. Skip Montanaro <skip@pobox.com> parents: 43630 diff changeset	147 .. versionchanged:: 2.5
43765 585ad7713efe Fix syntax for versionchanged markup. Georg Brandl <georg@python.org> parents: 43763 diff changeset	148 This function now returns an immutable :class:`Dialect`. Previously an
585ad7713efe Fix syntax for versionchanged markup. Georg Brandl <georg@python.org> parents: 43763 diff changeset	149 instance of the requested dialect was returned. Users could modify the
585ad7713efe Fix syntax for versionchanged markup. Georg Brandl <georg@python.org> parents: 43763 diff changeset	150 underlying class, changing the behavior of active readers and writers.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 .. function:: list_dialects()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 Return the names of all registered dialects.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 .. function:: field_size_limit([new_limit])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 Returns the current maximum field size allowed by the parser. If new_limit is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 given, this becomes the new limit.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 The :mod:`csv` module defines the following classes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166
77102 a36666c52115 #14804: Remove [] around optional arguments with default values Hynek Schlawack <hs@ox.cx> parents: 68419 diff changeset	167 .. class:: DictReader(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', args, *kwds)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 Create an object which operates like a regular reader but maps the information
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 read into a dict whose keys are given by the optional fieldnames parameter.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171 If the fieldnames parameter is omitted, the values in the first row of the
57150 f190315f185e Merged revisions 76163 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56817 diff changeset	172 csvfile will be used as the fieldnames. If the row read has more fields
f190315f185e Merged revisions 76163 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56817 diff changeset	173 than the fieldnames sequence, the remaining data is added as a sequence
f190315f185e Merged revisions 76163 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56817 diff changeset	174 keyed by the value of restkey. If the row read has fewer fields than the
f190315f185e Merged revisions 76163 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56817 diff changeset	175 fieldnames sequence, the remaining keys take the value of the optional
f190315f185e Merged revisions 76163 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56817 diff changeset	176 restval parameter. Any other optional or keyword arguments are passed to
f190315f185e Merged revisions 76163 via svnmerge from R. David Murray <rdmurray@bitdance.com> parents: 56817 diff changeset	177 the underlying :class:`reader` instance.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179
77102 a36666c52115 #14804: Remove [] around optional arguments with default values Hynek Schlawack <hs@ox.cx> parents: 68419 diff changeset	180 .. class:: DictWriter(csvfile, fieldnames, restval='', extrasaction='raise', dialect='excel', args, *kwds)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 Create an object which operates like a regular writer but maps dictionaries onto
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 output rows. The fieldnames parameter identifies the order in which values in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 the dictionary passed to the :meth:`writerow` method are written to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 csvfile. The optional restval parameter specifies the value to be written
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 if the dictionary is missing a key in fieldnames. If the dictionary passed to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 the :meth:`writerow` method contains a key not found in fieldnames, the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 optional extrasaction parameter indicates what action to take. If it is set
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 to ``'raise'`` a :exc:`ValueError` is raised. If it is set to ``'ignore'``,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190 extra values in the dictionary are ignored. Any other optional or keyword
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 arguments are passed to the underlying :class:`writer` instance.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 Note that unlike the :class:`DictReader` class, the fieldnames parameter of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 the :class:`DictWriter` is not optional. Since Python's :class:`dict` objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 are not ordered, there is not enough information available to deduce the order
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 in which the row should be written to the csvfile.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 .. class:: Dialect
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 The :class:`Dialect` class is a container class relied on primarily for its
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202 attributes, which are used to define the parameters for a specific
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 :class:`reader` or :class:`writer` instance.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206 .. class:: excel()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 The :class:`excel` class defines the usual properties of an Excel-generated CSV
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 file. It is registered with the dialect name ``'excel'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 .. class:: excel_tab()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 The :class:`excel_tab` class defines the usual properties of an Excel-generated
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 TAB-delimited file. It is registered with the dialect name ``'excel-tab'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 .. class:: Sniffer()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 The :class:`Sniffer` class is used to deduce the format of a CSV file.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 44530 diff changeset	222 The :class:`Sniffer` class provides two methods:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223
77102 a36666c52115 #14804: Remove [] around optional arguments with default values Hynek Schlawack <hs@ox.cx> parents: 68419 diff changeset	224 .. method:: sniff(sample, delimiters=None)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 44530 diff changeset	226 Analyze the given sample and return a :class:`Dialect` subclass
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 44530 diff changeset	227 reflecting the parameters found. If the optional delimiters parameter
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 44530 diff changeset	228 is given, it is interpreted as a string containing possible valid
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 44530 diff changeset	229 delimiter characters.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	231
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 44530 diff changeset	232 .. method:: has_header(sample)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	233
46555 66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 44530 diff changeset	234 Analyze the sample text (presumed to be in CSV format) and return
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive Benjamin Peterson <benjamin@python.org> parents: 44530 diff changeset	235 :const:`True` if the first row appears to be a series of column headers.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236
44530 6b3aae5c69bf #1686390: add example for csv.Sniffer use. Georg Brandl <georg@python.org> parents: 44176 diff changeset	237 An example for :class:`Sniffer` use::
6b3aae5c69bf #1686390: add example for csv.Sniffer use. Georg Brandl <georg@python.org> parents: 44176 diff changeset	238
79029 ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	239 with open('example.csv', 'rb') as csvfile:
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	240 dialect = csv.Sniffer().sniff(csvfile.read(1024))
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	241 csvfile.seek(0)
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	242 reader = csv.reader(csvfile, dialect)
ade667076c14 #15932: use with statement in csv doc examples. Ezio Melotti <ezio.melotti@gmail.com> parents: 78782 diff changeset	243 # ... process CSV file contents here ...
44530 6b3aae5c69bf #1686390: add example for csv.Sniffer use. Georg Brandl <georg@python.org> parents: 44176 diff changeset	244
6b3aae5c69bf #1686390: add example for csv.Sniffer use. Georg Brandl <georg@python.org> parents: 44176 diff changeset	245
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 The :mod:`csv` module defines the following constants:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 .. data:: QUOTE_ALL
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 Instructs :class:`writer` objects to quote all fields.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 .. data:: QUOTE_MINIMAL
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255 Instructs :class:`writer` objects to only quote those fields which contain
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 special characters such as delimiter, quotechar or any of the characters in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 lineterminator.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 .. data:: QUOTE_NONNUMERIC
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 Instructs :class:`writer` objects to quote all non-numeric fields.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 Instructs the reader to convert all non-quoted fields to type float.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267 .. data:: QUOTE_NONE
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	268
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	269 Instructs :class:`writer` objects to never quote fields. When the current
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	270 delimiter occurs in output data it is preceded by the current escapechar
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	271 character. If escapechar is not set, the writer will raise :exc:`Error` if
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	272 any characters that require escaping are encountered.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	273
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	274 Instructs :class:`reader` to perform no special processing of quote characters.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	275
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	276 The :mod:`csv` module defines the following exception:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	277
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	278
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	279 .. exception:: Error
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	280
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	281 Raised by any of the functions when an error is detected.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	282
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	283
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	284 .. _csv-fmt-params:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	285
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	286 Dialects and Formatting Parameters
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	287 ----------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	288
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	289 To make it easier to specify the format of input and output records, specific
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	290 formatting parameters are grouped together into dialects. A dialect is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	291 subclass of the :class:`Dialect` class having a set of specific methods and a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	292 single :meth:`validate` method. When creating :class:`reader` or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	293 :class:`writer` objects, the programmer can specify a string or a subclass of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	294 the :class:`Dialect` class as the dialect parameter. In addition to, or instead
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	295 of, the dialect parameter, the programmer can also specify individual
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	296 formatting parameters, which have the same names as the attributes defined below
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	297 for the :class:`Dialect` class.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	298
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	299 Dialects support the following attributes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	300
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	301
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	302 .. attribute:: Dialect.delimiter
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	303
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	304 A one-character string used to separate fields. It defaults to ``','``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	305
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	306
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	307 .. attribute:: Dialect.doublequote
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	308
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	309 Controls how instances of quotechar appearing inside a field should be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 themselves be quoted. When :const:`True`, the character is doubled. When
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311 :const:`False`, the escapechar is used as a prefix to the quotechar. It
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 defaults to :const:`True`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314 On output, if doublequote is :const:`False` and no escapechar is set,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	315 :exc:`Error` is raised if a quotechar is found in a field.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	316
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	317
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318 .. attribute:: Dialect.escapechar
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 A one-character string used by the writer to escape the delimiter if quoting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321 is set to :const:`QUOTE_NONE` and the quotechar if doublequote is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 :const:`False`. On reading, the escapechar removes any special meaning from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 the following character. It defaults to :const:`None`, which disables escaping.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 .. attribute:: Dialect.lineterminator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 The string used to terminate lines produced by the :class:`writer`. It defaults
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329 to ``'\r\n'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 The :class:`reader` is hard-coded to recognise either ``'\r'`` or ``'\n'`` as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 end-of-line, and ignores lineterminator. This behavior may change in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335 future.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	336
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	337
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	338 .. attribute:: Dialect.quotechar
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	339
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340 A one-character string used to quote fields containing special characters, such
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 as the delimiter or quotechar, or which contain new-line characters. It
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 defaults to ``'"'``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 .. attribute:: Dialect.quoting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 Controls when quotes should be generated by the writer and recognised by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348 reader. It can take on any of the :const:`QUOTE_\*` constants (see section
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 :ref:`csv-contents`) and defaults to :const:`QUOTE_MINIMAL`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352 .. attribute:: Dialect.skipinitialspace
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 When :const:`True`, whitespace immediately following the delimiter is ignored.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 The default is :const:`False`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 Reader Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359 --------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 Reader objects (:class:`DictReader` instances and objects returned by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362 :func:`reader` function) have the following public methods:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 .. method:: csvreader.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 Return the next row of the reader's iterable object as a list, parsed according
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 to the current dialect.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370 Reader objects have the following public attributes:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 .. attribute:: csvreader.dialect
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375 A read-only description of the dialect in use by the parser.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 .. attribute:: csvreader.line_num
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	379
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	380 The number of lines read from the source iterator. This is not the same as the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381 number of records returned, as records can span multiple lines.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 .. versionadded:: 2.5
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385
48198 47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	386 DictReader objects have the following public attribute:
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	387
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	388
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	389 .. attribute:: csvreader.fieldnames
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	390
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	391 If not passed as a parameter when creating the object, this attribute is
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	392 initialized upon first access or when the first record is read from the
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	393 file.
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	394
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	395 .. versionchanged:: 2.6
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	396
47967690b585 accept issue 3436 Skip Montanaro <skip@pobox.com> parents: 46555 diff changeset	397
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 Writer Objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399 --------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 :class:`Writer` objects (:class:`DictWriter` instances and objects returned by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 the :func:`writer` function) have the following public methods. A row must be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 a sequence of strings or numbers for :class:`Writer` objects and a dictionary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 mapping fieldnames to strings or numbers (by passing them through :func:`str`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405 first) for :class:`DictWriter` objects. Note that complex numbers are written
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 out surrounded by parens. This may cause some problems for other programs which
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 read CSV files (assuming they support complex numbers at all).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 .. method:: csvwriter.writerow(row)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 Write the row parameter to the writer's file object, formatted according to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 the current dialect.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 .. method:: csvwriter.writerows(rows)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 Write all the rows parameters (a list of row objects as described above) to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419 the writer's file object, formatted according to the current dialect.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421 Writer objects have the following public attribute:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424 .. attribute:: csvwriter.dialect
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 A read-only description of the dialect in use by the writer.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428
59078 dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	429 DictWriter objects have the following public method:
dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	430
dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	431
dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	432 .. method:: DictWriter.writeheader()
dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	433
dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	434 Write a row with the field names (as specified in the constructor).
dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	435
dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	436 .. versionadded:: 2.7
dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	437
dda5165a2374 Fix #1537721: add writeheader() method to csv.DictWriter. Dirkjan Ochtman <dirkjan@ochtman.nl> parents: 57149 diff changeset	438
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	439 .. _csv-examples:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 Examples
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 --------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 The simplest example of reading a CSV file::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446 import csv
68419 52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	447 with open('some.csv', 'rb') as f:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	448 reader = csv.reader(f)
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	449 for row in reader:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	450 print row
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 Reading a file with an alternate format::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 import csv
68419 52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	455 with open('passwd', 'rb') as f:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	456 reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	457 for row in reader:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	458 print row
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 The corresponding simplest possible writing example is::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462 import csv
68419 52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	463 with open('some.csv', 'wb') as f:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	464 writer = csv.writer(f)
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	465 writer.writerows(someiterable)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 Registering a new dialect::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469 import csv
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	470 csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
68419 52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	471 with open('passwd', 'rb') as f:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	472 reader = csv.reader(f, 'unixpwd')
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 A slightly more advanced use of the reader --- catching and reporting errors::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	476 import csv, sys
68419 52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	477 filename = 'some.csv'
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	478 with open(filename, 'rb') as f:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	479 reader = csv.reader(f)
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	480 try:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	481 for row in reader:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	482 print row
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	483 except csv.Error, e:
52e1ad467edd Issue #11426: use 'with' statements on open files in CSV examples Eli Bendersky <eliben@gmail.com> parents: 68256 diff changeset	484 sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 And while the module doesn't directly support parsing strings, it can easily be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 done::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 import csv
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 for row in csv.reader(['one,two,three']):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 print row
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 The :mod:`csv` module doesn't directly support reading and writing Unicode, but
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 it is 8-bit-clean save for some problems with ASCII NUL characters. So you can
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 write functions or classes that handle the encoding and decoding for you as long
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496 as you avoid encodings like UTF-16 that use NULs. UTF-8 is recommended.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497
43629 4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43581 diff changeset	498 :func:`unicode_csv_reader` below is a :term:`generator` that wraps :class:`csv.reader`
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 to handle Unicode CSV data (a list of Unicode strings). :func:`utf_8_encoder`
43629 4f662ba09f1f Add :term: for generators. Georg Brandl <georg@python.org> parents: 43581 diff changeset	500 is a :term:`generator` that encodes the Unicode strings as UTF-8, one string (or row) at
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501 a time. The encoded strings are parsed by the CSV reader, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 :func:`unicode_csv_reader` decodes the UTF-8-encoded cells back into Unicode::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504 import csv
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	506 def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	507 # csv.py doesn't do Unicode; encode temporarily as UTF-8:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	508 csv_reader = csv.reader(utf_8_encoder(unicode_csv_data),
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509 dialect=dialect, **kwargs)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 for row in csv_reader:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511 # decode UTF-8 back to Unicode, cell by cell:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512 yield [unicode(cell, 'utf-8') for cell in row]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514 def utf_8_encoder(unicode_csv_data):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 for line in unicode_csv_data:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 yield line.encode('utf-8')
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 For all other encodings the following :class:`UnicodeReader` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519 :class:`UnicodeWriter` classes can be used. They take an additional encoding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 parameter in their constructor and make sure that the data passes the real
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521 reader or writer encoded as UTF-8::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523 import csv, codecs, cStringIO
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 class UTF8Recoder:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526 """
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527 Iterator that reads an encoded stream and reencodes the input to UTF-8
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	528 """
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	529 def __init__(self, f, encoding):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	530 self.reader = codecs.getreader(encoding)(f)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	531
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532 def __iter__(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 return self
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535 def next(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 return self.reader.next().encode("utf-8")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 class UnicodeReader:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	539 """
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540 A CSV reader which will iterate over lines in the CSV file "f",
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541 which is encoded in the given encoding.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 """
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544 def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 f = UTF8Recoder(f, encoding)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 self.reader = csv.reader(f, dialect=dialect, **kwds)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548 def next(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549 row = self.reader.next()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 return [unicode(s, "utf-8") for s in row]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552 def __iter__(self):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 return self
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 class UnicodeWriter:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556 """
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557 A CSV writer which will write rows to CSV file "f",
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558 which is encoded in the given encoding.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 """
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562 # Redirect output to a queue
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 self.queue = cStringIO.StringIO()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564 self.writer = csv.writer(self.queue, dialect=dialect, **kwds)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 self.stream = f
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 self.encoder = codecs.getincrementalencoder(encoding)()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 def writerow(self, row):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 self.writer.writerow([s.encode("utf-8") for s in row])
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570 # Fetch UTF-8 output from the queue ...
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571 data = self.queue.getvalue()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 data = data.decode("utf-8")
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573 # ... and reencode it into the target encoding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574 data = self.encoder.encode(data)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 # write to the target stream
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576 self.stream.write(data)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	577 # empty queue
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	578 self.queue.truncate(0)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	579
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	580 def writerows(self, rows):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	581 for row in rows:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582 self.writerow(row)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/csv.rst @ 79675:c0a2294de787 2.7