cpython-lru_cache-weakref: Doc/lib/libcsv.tex annotate

annotate Doc/lib/libcsv.tex @ 39042:c02fa187e0f4 legacy-trunk

Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.

author	Neal Norwitz <nnorwitz@gmail.com>
date	Mon, 10 Jul 2006 00:23:17 +0000
parents	903e3162099e
children	d8888c8b872b

rev	line source
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	1 \section{\module{csv} --- CSV File Reading and Writing}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	2
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	3 \declaremodule{standard}{csv}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	4 \modulesynopsis{Write and read tabular data to and from delimited files.}
28797 21633e9df8cc * minor tweaks relating to the package nature of the beast Skip Montanaro <skip@pobox.com> parents: 28339 diff changeset	5 \sectionauthor{Skip Montanaro}{skip@pobox.com}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	6
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	7 \versionadded{2.3}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	8 \index{csv}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	9 \indexii{data}{tabular}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	10
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	11 The so-called CSV (Comma Separated Values) format is the most common import
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	12 and export format for spreadsheets and databases. There is no ``CSV
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	13 standard'', so the format is operationally defined by the many applications
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	14 which read and write it. The lack of a standard means that subtle
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	15 differences often exist in the data produced and consumed by different
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	16 applications. These differences can make it annoying to process CSV files
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	17 from multiple sources. Still, while the delimiters and quoting characters
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	18 vary, the overall format is similar enough that it is possible to write a
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	19 single module which can efficiently manipulate such data, hiding the details
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	20 of reading and writing the data from the programmer.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	21
28835 98e31cfd26dc reflect csv's change back to a module. Document the new sniffer api. Skip Montanaro <skip@pobox.com> parents: 28797 diff changeset	22 The \module{csv} module implements classes to read and write tabular data in
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	23 CSV format. It allows programmers to say, ``write this data in the format
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	24 preferred by Excel,'' or ``read data from this file which was generated by
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	25 Excel,'' without knowing the precise details of the CSV format used by
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	26 Excel. Programmers can also describe the CSV formats understood by other
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	27 applications or define their own special-purpose CSV formats.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	28
28835 98e31cfd26dc reflect csv's change back to a module. Document the new sniffer api. Skip Montanaro <skip@pobox.com> parents: 28797 diff changeset	29 The \module{csv} module's \class{reader} and \class{writer} objects read and
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	30 write sequences. Programmers can also read and write data in dictionary
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	31 form using the \class{DictReader} and \class{DictWriter} classes.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	32
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	33 \begin{notice}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	34 This version of the \module{csv} module doesn't support Unicode
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	35 input. Also, there are currently some issues regarding \ASCII{} NUL
37452 49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	36 characters. Accordingly, all input should be UTF-8 or printable
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	37 \ASCII{} to be safe; see the examples in section~\ref{csv-examples}.
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	38 These restrictions will be removed in the future.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	39 \end{notice}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	40
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	41 \begin{seealso}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	42 % \seemodule{array}{Arrays of uniformly types numeric values.}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	43 \seepep{305}{CSV File API}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	44 {The Python Enhancement Proposal which proposed this addition
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	45 to Python.}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	46 \end{seealso}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	47
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	48
30262 7b577377d546 SF bug #797853: Small problems with the csv module's documentation Raymond Hettinger <python@rcn.com> parents: 29747 diff changeset	49 \subsection{Module Contents \label{csv-contents}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	50
28835 98e31cfd26dc reflect csv's change back to a module. Document the new sniffer api. Skip Montanaro <skip@pobox.com> parents: 28797 diff changeset	51 The \module{csv} module defines the following functions:
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	52
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	53 \begin{funcdesc}{reader}{csvfile\optional{,
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	54 dialect=\code{'excel'}}\optional{, fmtparam}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	55 Return a reader object which will iterate over lines in the given
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	56 {}\var{csvfile}. \var{csvfile} can be any object which supports the
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	57 iterator protocol and returns a string each time its \method{next}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	58 method is called - file objects and list objects are both suitable.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	59 If \var{csvfile} is a file object, it must be opened with
29747 eb828c64fcc7 Note that csv files (when they are actual files) must be opened in 'b'inary Skip Montanaro <skip@pobox.com> parents: 29361 diff changeset	60 the 'b' flag on platforms where that makes a difference. An optional
eb828c64fcc7 Note that csv files (when they are actual files) must be opened in 'b'inary Skip Montanaro <skip@pobox.com> parents: 29361 diff changeset	61 {}\var{dialect} parameter can be given
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	62 which is used to define a set of parameters specific to a particular CSV
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	63 dialect. It may be an instance of a subclass of the \class{Dialect}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	64 class or one of the strings returned by the \function{list_dialects}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	65 function. The other optional {}\var{fmtparam} keyword arguments can be
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	66 given to override individual formatting parameters in the current
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	67 dialect. For more information about the dialect and formatting
30399 fd16018407e7 SF bug #803679: Missing section number in csv module documentation Raymond Hettinger <python@rcn.com> parents: 30262 diff changeset	68 parameters, see section~\ref{csv-fmt-params}, ``Dialects and Formatting
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	69 Parameters'' for details of these parameters.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	70
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	71 All data read are returned as strings. No automatic data type
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	72 conversion is performed.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	73 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	74
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	75 \begin{funcdesc}{writer}{csvfile\optional{,
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	76 dialect=\code{'excel'}}\optional{, fmtparam}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	77 Return a writer object responsible for converting the user's data into
29747 eb828c64fcc7 Note that csv files (when they are actual files) must be opened in 'b'inary Skip Montanaro <skip@pobox.com> parents: 29361 diff changeset	78 delimited strings on the given file-like object. \var{csvfile} can be any
eb828c64fcc7 Note that csv files (when they are actual files) must be opened in 'b'inary Skip Montanaro <skip@pobox.com> parents: 29361 diff changeset	79 object with a \function{write} method. If \var{csvfile} is a file object,
eb828c64fcc7 Note that csv files (when they are actual files) must be opened in 'b'inary Skip Montanaro <skip@pobox.com> parents: 29361 diff changeset	80 it must be opened with the 'b' flag on platforms where that makes a
eb828c64fcc7 Note that csv files (when they are actual files) must be opened in 'b'inary Skip Montanaro <skip@pobox.com> parents: 29361 diff changeset	81 difference. An optional
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	82 {}\var{dialect} parameter can be given which is used to define a set of
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	83 parameters specific to a particular CSV dialect. It may be an instance
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	84 of a subclass of the \class{Dialect} class or one of the strings
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	85 returned by the \function{list_dialects} function. The other optional
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	86 {}\var{fmtparam} keyword arguments can be given to override individual
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	87 formatting parameters in the current dialect. For more information
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	88 about the dialect and formatting parameters, see
30399 fd16018407e7 SF bug #803679: Missing section number in csv module documentation Raymond Hettinger <python@rcn.com> parents: 30262 diff changeset	89 section~\ref{csv-fmt-params}, ``Dialects and Formatting Parameters'' for
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	90 details of these parameters. To make it as easy as possible to
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	91 interface with modules which implement the DB API, the value
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	92 \constant{None} is written as the empty string. While this isn't a
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	93 reversible transformation, it makes it easier to dump SQL NULL data values
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	94 to CSV files without preprocessing the data returned from a
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	95 \code{cursor.fetch*()} call. All other non-string data are stringified
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	96 with \function{str()} before being written.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	97 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	98
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	99 \begin{funcdesc}{register_dialect}{name\optional{, dialect}\optional{, fmtparam}}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	100 Associate \var{dialect} with \var{name}. \var{name} must be a string
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	101 or Unicode object. The dialect can be specified either by passing a
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	102 sub-class of \class{Dialect}, or by \var{fmtparam} keyword arguments,
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	103 or both, with keyword arguments overriding parameters of the dialect.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	104 For more information about the dialect and formatting parameters, see
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	105 section~\ref{csv-fmt-params}, ``Dialects and Formatting Parameters''
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	106 for details of these parameters.
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	107 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	108
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	109 \begin{funcdesc}{unregister_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	110 Delete the dialect associated with \var{name} from the dialect registry. An
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	111 \exception{Error} is raised if \var{name} is not a registered dialect
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	112 name.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	113 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	114
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	115 \begin{funcdesc}{get_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	116 Return the dialect associated with \var{name}. An \exception{Error} is
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	117 raised if \var{name} is not a registered dialect name.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	118 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	119
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	120 \begin{funcdesc}{list_dialects}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	121 Return the names of all registered dialects.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	122 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	123
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	124 \begin{funcdesc}{field_size_limit}{\optional{new_limit}}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	125 Returns the current maximum field size allowed by the parser. If
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	126 \var{new_limit} is given, this becomes the new limit.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	127 \versionadded{2.5}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	128 \end{funcdesc}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	129
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	130
28835 98e31cfd26dc reflect csv's change back to a module. Document the new sniffer api. Skip Montanaro <skip@pobox.com> parents: 28797 diff changeset	131 The \module{csv} module defines the following classes:
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	132
30632 f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	133 \begin{classdesc}{DictReader}{csvfile\optional{,
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	134 fieldnames=\constant{None},\optional{,
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	135 restkey=\constant{None}\optional{,
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	136 restval=\constant{None}\optional{,
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	137 dialect=\code{'excel'}\optional{,
31918 3c796413f05e bring description of optional and keyword args for DictReader and DictWriter Skip Montanaro <skip@pobox.com> parents: 31674 diff changeset	138 args, *kwds}}}}}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	139 Create an object which operates like a regular reader but maps the
30632 f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	140 information read into a dict whose keys are given by the optional
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	141 {} \var{fieldnames}
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	142 parameter. If the \var{fieldnames} parameter is omitted, the values in
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	143 the first row of the \var{csvfile} will be used as the fieldnames.
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	144 If the row read has fewer fields than the fieldnames sequence,
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	145 the value of \var{restval} will be used as the default value. If the row
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	146 read has more fields than the fieldnames sequence, the remaining data is
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	147 added as a sequence keyed by the value of \var{restkey}. If the row read
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	148 has fewer fields than the fieldnames sequence, the remaining keys take the
31918 3c796413f05e bring description of optional and keyword args for DictReader and DictWriter Skip Montanaro <skip@pobox.com> parents: 31674 diff changeset	149 value of the optional \var{restval} parameter. Any other optional or
3c796413f05e bring description of optional and keyword args for DictReader and DictWriter Skip Montanaro <skip@pobox.com> parents: 31674 diff changeset	150 keyword arguments are passed to the underlying \class{reader} instance.
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	151 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	152
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	153
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	154 \begin{classdesc}{DictWriter}{csvfile, fieldnames\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	155 restval=""\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	156 extrasaction=\code{'raise'}\optional{,
31918 3c796413f05e bring description of optional and keyword args for DictReader and DictWriter Skip Montanaro <skip@pobox.com> parents: 31674 diff changeset	157 dialect=\code{'excel'}\optional{,
3c796413f05e bring description of optional and keyword args for DictReader and DictWriter Skip Montanaro <skip@pobox.com> parents: 31674 diff changeset	158 args, *kwds}}}}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	159 Create an object which operates like a regular writer but maps dictionaries
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	160 onto output rows. The \var{fieldnames} parameter identifies the order in
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	161 which values in the dictionary passed to the \method{writerow()} method are
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	162 written to the \var{csvfile}. The optional \var{restval} parameter
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	163 specifies the value to be written if the dictionary is missing a key in
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	164 \var{fieldnames}. If the dictionary passed to the \method{writerow()}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	165 method contains a key not found in \var{fieldnames}, the optional
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	166 \var{extrasaction} parameter indicates what action to take. If it is set
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	167 to \code{'raise'} a \exception{ValueError} is raised. If it is set to
31918 3c796413f05e bring description of optional and keyword args for DictReader and DictWriter Skip Montanaro <skip@pobox.com> parents: 31674 diff changeset	168 \code{'ignore'}, extra values in the dictionary are ignored. Any other
3c796413f05e bring description of optional and keyword args for DictReader and DictWriter Skip Montanaro <skip@pobox.com> parents: 31674 diff changeset	169 optional or keyword arguments are passed to the underlying \class{writer}
3c796413f05e bring description of optional and keyword args for DictReader and DictWriter Skip Montanaro <skip@pobox.com> parents: 31674 diff changeset	170 instance.
30632 f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	171
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	172 Note that unlike the \class{DictReader} class, the \var{fieldnames}
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	173 parameter of the \class{DictWriter} is not optional. Since Python's
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	174 \class{dict} objects are not ordered, there is not enough information
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	175 available to deduce the order in which the row should be written to the
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	176 \var{csvfile}.
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	177
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	178 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	179
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	180 \begin{classdesc*}{Dialect}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	181 The \class{Dialect} class is a container class relied on primarily for its
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	182 attributes, which are used to define the parameters for a specific
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	183 \class{reader} or \class{writer} instance.
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	184 \end{classdesc*}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	185
34326 06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	186 \begin{classdesc}{excel}{}
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	187 The \class{excel} class defines the usual properties of an Excel-generated
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	188 CSV file.
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	189 \end{classdesc}
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	190
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	191 \begin{classdesc}{excel_tab}{}
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	192 The \class{excel_tab} class defines the usual properties of an
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	193 Excel-generated TAB-delimited file.
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	194 \end{classdesc}
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	195
29169 434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	196 \begin{classdesc}{Sniffer}{}
434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	197 The \class{Sniffer} class is used to deduce the format of a CSV file.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	198 \end{classdesc}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	199
36148 aa707041505d typo Skip Montanaro <skip@pobox.com> parents: 34770 diff changeset	200 The \class{Sniffer} class provides two methods:
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	201
29169 434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	202 \begin{methoddesc}{sniff}{sample\optional{,delimiters=None}}
434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	203 Analyze the given \var{sample} and return a \class{Dialect} subclass
434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	204 reflecting the parameters found. If the optional \var{delimiters} parameter
434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	205 is given, it is interpreted as a string containing possible valid delimiter
434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	206 characters.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	207 \end{methoddesc}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	208
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	209 \begin{methoddesc}{has_header}{sample}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	210 Analyze the sample text (presumed to be in CSV format) and return
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	211 \constant{True} if the first row appears to be a series of column
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	212 headers.
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	213 \end{methoddesc}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	214
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	215
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	216 The \module{csv} module defines the following constants:
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	217
29361 fdac9b4d3717 QUOTE_ALWAYS -> QUOTE_ALL Skip Montanaro <skip@pobox.com> parents: 29169 diff changeset	218 \begin{datadesc}{QUOTE_ALL}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	219 Instructs \class{writer} objects to quote all fields.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	220 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	221
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	222 \begin{datadesc}{QUOTE_MINIMAL}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	223 Instructs \class{writer} objects to only quote those fields which contain
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	224 special characters such as \var{delimiter}, \var{quotechar} or any of the
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	225 characters in \var{lineterminator}.
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	226 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	227
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	228 \begin{datadesc}{QUOTE_NONNUMERIC}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	229 Instructs \class{writer} objects to quote all non-numeric
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	230 fields.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	231
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	232 Instructs the reader to convert all non-quoted fields to type \var{float}.
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	233 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	234
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	235 \begin{datadesc}{QUOTE_NONE}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	236 Instructs \class{writer} objects to never quote fields. When the current
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	237 \var{delimiter} occurs in output data it is preceded by the current
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	238 \var{escapechar} character. If \var{escapechar} is not set, the writer
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	239 will raise \exception{Error} if any characters that require escaping
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	240 are encountered.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	241
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	242 Instructs \class{reader} to perform no special processing of quote characters.
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	243 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	244
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	245
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	246 The \module{csv} module defines the following exception:
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	247
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	248 \begin{excdesc}{Error}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	249 Raised by any of the functions when an error is detected.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	250 \end{excdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	251
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	252
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	253 \subsection{Dialects and Formatting Parameters\label{csv-fmt-params}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	254
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	255 To make it easier to specify the format of input and output records,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	256 specific formatting parameters are grouped together into dialects. A
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	257 dialect is a subclass of the \class{Dialect} class having a set of specific
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	258 methods and a single \method{validate()} method. When creating \class{reader}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	259 or \class{writer} objects, the programmer can specify a string or a subclass
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	260 of the \class{Dialect} class as the dialect parameter. In addition to, or
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	261 instead of, the \var{dialect} parameter, the programmer can also specify
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	262 individual formatting parameters, which have the same names as the
30262 7b577377d546 SF bug #797853: Small problems with the csv module's documentation Raymond Hettinger <python@rcn.com> parents: 29747 diff changeset	263 attributes defined below for the \class{Dialect} class.
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	264
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	265 Dialects support the following attributes:
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	266
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	267 \begin{memberdesc}[Dialect]{delimiter}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	268 A one-character string used to separate fields. It defaults to \code{','}.
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	269 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	270
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	271 \begin{memberdesc}[Dialect]{doublequote}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	272 Controls how instances of \var{quotechar} appearing inside a field should
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	273 be themselves be quoted. When \constant{True}, the character is doubled.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	274 When \constant{False}, the \var{escapechar} is used as a prefix to the
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	275 \var{quotechar}. It defaults to \constant{True}.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	276
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	277 On output, if \var{doublequote} is \constant{False} and no
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	278 \var{escapechar} is set, \exception{Error} is raised if a \var{quotechar}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	279 is found in a field.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	280 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	281
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	282 \begin{memberdesc}[Dialect]{escapechar}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	283 A one-character string used by the writer to escape the \var{delimiter} if
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	284 \var{quoting} is set to \constant{QUOTE_NONE} and the \var{quotechar}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	285 if \var{doublequote} is \constant{False}. On reading, the \var{escapechar}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	286 removes any special meaning from the following character. It defaults
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	287 to \constant{None}, which disables escaping.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	288 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	289
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	290 \begin{memberdesc}[Dialect]{lineterminator}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	291 The string used to terminate lines produced by the \class{writer}.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	292 It defaults to \code{'\e r\e n'}.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	293
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	294 \note{The \class{reader} is hard-coded to recognise either \code{'\e r'}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	295 or \code{'\e n'} as end-of-line, and ignores \var{lineterminator}. This
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	296 behavior may change in the future.}
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	297 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	298
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	299 \begin{memberdesc}[Dialect]{quotechar}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	300 A one-character string used to quote fields containing special characters,
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	301 such as the \var{delimiter} or \var{quotechar}, or which contain new-line
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	302 characters. It defaults to \code{'"'}.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	303 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	304
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	305 \begin{memberdesc}[Dialect]{quoting}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	306 Controls when quotes should be generated by the writer and recognised
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	307 by the reader. It can take on any of the \constant{QUOTE_*} constants
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	308 (see section~\ref{csv-contents}) and defaults to \constant{QUOTE_MINIMAL}.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	309 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	310
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	311 \begin{memberdesc}[Dialect]{skipinitialspace}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	312 When \constant{True}, whitespace immediately following the \var{delimiter}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	313 is ignored. The default is \constant{False}.
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	314 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	315
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	316
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	317 \subsection{Reader Objects}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	318
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	319 Reader objects (\class{DictReader} instances and objects returned by
30262 7b577377d546 SF bug #797853: Small problems with the csv module's documentation Raymond Hettinger <python@rcn.com> parents: 29747 diff changeset	320 the \function{reader()} function) have the following public methods:
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	321
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	322 \begin{methoddesc}[csv reader]{next}{}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	323 Return the next row of the reader's iterable object as a list, parsed
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	324 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	325 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	326
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	327 Reader objects have the following public attributes:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	328
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	329 \begin{memberdesc}[csv reader]{dialect}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	330 A read-only description of the dialect in use by the parser.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	331 \end{memberdesc}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	332
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	333 \begin{memberdesc}[csv reader]{line_num}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	334 The number of lines read from the source iterator. This is not the same
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	335 as the number of records returned, as records can span multiple lines.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	336 \end{memberdesc}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	337
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	338
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	339 \subsection{Writer Objects}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	340
31408 e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	341 \class{Writer} objects (\class{DictWriter} instances and objects returned by
e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	342 the \function{writer()} function) have the following public methods. A
e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	343 {}\var{row} must be a sequence of strings or numbers for \class{Writer}
e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	344 objects and a dictionary mapping fieldnames to strings or numbers (by
e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	345 passing them through \function{str()} first) for {}\class{DictWriter}
e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	346 objects. Note that complex numbers are written out surrounded by parens.
e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	347 This may cause some problems for other programs which read CSV files
e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	348 (assuming they support complex numbers at all).
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	349
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	350 \begin{methoddesc}[csv writer]{writerow}{row}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	351 Write the \var{row} parameter to the writer's file object, formatted
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	352 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	353 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	354
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	355 \begin{methoddesc}[csv writer]{writerows}{rows}
31408 e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	356 Write all the \var{rows} parameters (a list of \var{row} objects as
e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	357 described above) to the writer's file object, formatted
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	358 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	359 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	360
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	361 Writer objects have the following public attribute:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	362
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	363 \begin{memberdesc}[csv writer]{dialect}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	364 A read-only description of the dialect in use by the writer.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	365 \end{memberdesc}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	366
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	367
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	368
37452 49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	369 \subsection{Examples\label{csv-examples}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	370
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	371 The simplest example of reading a CSV file:
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	372
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	373 \begin{verbatim}
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	374 import csv
32993 4e2c66021bf3 [Bug #998307] Use open() instead of file() in docs Andrew M. Kuchling <amk@amk.ca> parents: 32553 diff changeset	375 reader = csv.reader(open("some.csv", "rb"))
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	376 for row in reader:
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	377 print row
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	378 \end{verbatim}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	379
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	380 Reading a file with an alternate format:
32553 c099aa767952 show how easy it is to manipulate individual columns - from a request on Skip Montanaro <skip@pobox.com> parents: 31918 diff changeset	381
c099aa767952 show how easy it is to manipulate individual columns - from a request on Skip Montanaro <skip@pobox.com> parents: 31918 diff changeset	382 \begin{verbatim}
c099aa767952 show how easy it is to manipulate individual columns - from a request on Skip Montanaro <skip@pobox.com> parents: 31918 diff changeset	383 import csv
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	384 reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
32553 c099aa767952 show how easy it is to manipulate individual columns - from a request on Skip Montanaro <skip@pobox.com> parents: 31918 diff changeset	385 for row in reader:
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	386 print row
32553 c099aa767952 show how easy it is to manipulate individual columns - from a request on Skip Montanaro <skip@pobox.com> parents: 31918 diff changeset	387 \end{verbatim}
c099aa767952 show how easy it is to manipulate individual columns - from a request on Skip Montanaro <skip@pobox.com> parents: 31918 diff changeset	388
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	389 The corresponding simplest possible writing example is:
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	390
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	391 \begin{verbatim}
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	392 import csv
32993 4e2c66021bf3 [Bug #998307] Use open() instead of file() in docs Andrew M. Kuchling <amk@amk.ca> parents: 32553 diff changeset	393 writer = csv.writer(open("some.csv", "wb"))
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	394 writer.writerows(someiterable)
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	395 \end{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	396
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	397 Registering a new dialect:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	398
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	399 \begin{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	400 import csv
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	401
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	402 csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	403
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	404 reader = csv.reader(open("passwd", "rb"), 'unixpwd')
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	405 \end{verbatim}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	406
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	407 A slightly more advanced use of the reader - catching and reporting errors:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	408
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	409 \begin{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	410 import csv, sys
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	411 filename = "some.csv"
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	412 reader = csv.reader(open(filename, "rb"))
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	413 try:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	414 for row in reader:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	415 print row
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	416 except csv.Error, e:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	417 sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	418 \end{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	419
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	420 And while the module doesn't directly support parsing strings, it can
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	421 easily be done:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	422
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	423 \begin{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	424 import csv
36525 2297b270fcf6 Fix broken example of csv.reader use (it returns an iterator, which isn't Thomas Wouters <thomas@python.org> parents: 36148 diff changeset	425 for row in csv.reader(['one,two,three']):
2297b270fcf6 Fix broken example of csv.reader use (it returns an iterator, which isn't Thomas Wouters <thomas@python.org> parents: 36148 diff changeset	426 print row
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	427 \end{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	428
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	429 The \module{csv} module doesn't directly support reading and writing
37452 49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	430 Unicode, but it is 8-bit-clean save for some problems with \ASCII{} NUL
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	431 characters. So you can write functions or classes that handle the
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	432 encoding and decoding for you as long as you avoid encodings like
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	433 UTF-16 that use NULs. UTF-8 is recommended.
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	434
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	435 \function{unicode_csv_reader} below is a generator that wraps
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	436 \class{csv.reader} to handle Unicode CSV data (a list of Unicode
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	437 strings). \function{utf_8_encoder} is a generator that encodes the
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	438 Unicode strings as UTF-8, one string (or row) at a time. The encoded
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	439 strings are parsed by the CSV reader, and
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	440 \function{unicode_csv_reader} decodes the UTF-8-encoded cells back
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	441 into Unicode:
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	442
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	443 \begin{verbatim}
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	444 import csv
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	445
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	446 def unicode_csv_reader(unicode_csv_data, dialect=csv.excel, **kwargs):
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	447 # csv.py doesn't do Unicode; encode temporarily as UTF-8:
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	448 csv_reader = csv.reader(utf_8_encoder(unicode_csv_data),
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	449 dialect=dialect, **kwargs)
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	450 for row in csv_reader:
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	451 # decode UTF-8 back to Unicode, cell by cell:
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	452 yield [unicode(cell, 'utf-8') for cell in row]
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	453
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	454 def utf_8_encoder(unicode_csv_data):
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	455 for line in unicode_csv_data:
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	456 yield line.encode('utf-8')
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	457 \end{verbatim}
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	458
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	459 For all other encodings the following \class{UnicodeReader} and
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	460 \class{UnicodeWriter} classes can be used. They take an additional
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	461 \var{encoding} parameter in their constructor and make sure that the data
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	462 passes the real reader or writer encoded as UTF-8:
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	463
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	464 \begin{verbatim}
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	465 import csv, codecs, cStringIO
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	466
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	467 class UTF8Recoder:
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	468 """
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	469 Iterator that reads an encoded stream and reencodes the input to UTF-8
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	470 """
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	471 def __init__(self, f, encoding):
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	472 self.reader = codecs.getreader(encoding)(f)
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	473
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	474 def __iter__(self):
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	475 return self
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	476
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	477 def next(self):
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	478 return self.reader.next().encode("utf-8")
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	479
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	480 class UnicodeReader:
37452 49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	481 """
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	482 A CSV reader which will iterate over lines in the CSV file "f",
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	483 which is encoded in the given encoding.
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	484 """
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	485
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	486 def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	487 f = UTF8Recoder(f, encoding)
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	488 self.reader = csv.reader(f, dialect=dialect, **kwds)
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	489
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	490 def next(self):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	491 row = self.reader.next()
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	492 return [unicode(s, "utf-8") for s in row]
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	493
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	494 def __iter__(self):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	495 return self
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	496
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	497 class UnicodeWriter:
37452 49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	498 """
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	499 A CSV writer which will write rows to CSV file "f",
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	500 which is encoded in the given encoding.
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	501 """
49dbedfb1d74 added another example of Unicode CSV parsing; reworked the example text a bit; corrected notice in the intro and added a link to the examples David Goodger <goodger@python.org> parents: 36870 diff changeset	502
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	503 def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	504 # Redirect output to a queue
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	505 self.queue = cStringIO.StringIO()
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	506 self.writer = csv.writer(self.queue, dialect=dialect, **kwds)
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	507 self.stream = f
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	508 self.encoder = codecs.getincrementalencoder(encoding)()
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	509
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	510 def writerow(self, row):
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	511 self.writer.writerow([s.encode("utf-8") for s in row])
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	512 # Fetch UTF-8 output from the queue ...
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	513 data = self.queue.getvalue()
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	514 data = data.decode("utf-8")
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	515 # ... and reencode it into the target encoding
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	516 data = self.encoder.encode(data)
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	517 # write to the target stream
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	518 self.stream.write(data)
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	519 # empty queue
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	520 self.queue.truncate(0)
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	521
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	522 def writerows(self, rows):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	523 for row in rows:
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	524 self.writerow(row)
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	525 \end{verbatim}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcsv.tex @ 39042:c02fa187e0f4 legacy-trunk