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

annotate Doc/lib/libcsv.tex @ 39940:dfd809dcf680 2.5

Bug #1446043: correctly raise a LookupError if an encoding name given to encodings.search_function() contains a dot. (backport from rev. 52075)

author	Georg Brandl <georg@python.org>
date	Sat, 30 Sep 2006 11:22:35 +0000
parents	910151524f5e
children	7c34944d4c80

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}
39290 805512cf14ef Follow TeX's conventions for hyphens Andrew M. Kuchling <amk@amk.ca> parents: 39288 diff changeset	58 method is called --- file objects and list objects are both suitable.
34412 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.
39286 d8888c8b872b Add a comment to the csv reader documentation that explains why the Skip Montanaro <skip@pobox.com> parents: 37477 diff changeset	73
d8888c8b872b Add a comment to the csv reader documentation that explains why the Skip Montanaro <skip@pobox.com> parents: 37477 diff changeset	74 \versionchanged[
39323 930bb1eb8dd5 Redo the comment about the 2.5 change in quoted-newline handling. Andrew McNamara <andrewm@object-craft.com.au> parents: 39292 diff changeset	75 The parser is now stricter with respect to multi-line quoted
930bb1eb8dd5 Redo the comment about the 2.5 change in quoted-newline handling. Andrew McNamara <andrewm@object-craft.com.au> parents: 39292 diff changeset	76 fields. Previously, if a line ended within a quoted field without a
930bb1eb8dd5 Redo the comment about the 2.5 change in quoted-newline handling. Andrew McNamara <andrewm@object-craft.com.au> parents: 39292 diff changeset	77 terminating newline character, a newline would be inserted into the
39326 7f04793fe135 minor tweaks Skip Montanaro <skip@pobox.com> parents: 39323 diff changeset	78 returned field. This behavior caused problems when reading files
39327 910151524f5e minor tweaks Skip Montanaro <skip@pobox.com> parents: 39326 diff changeset	79 which contained carriage return characters within fields. The
39326 7f04793fe135 minor tweaks Skip Montanaro <skip@pobox.com> parents: 39323 diff changeset	80 behavior was changed to return the field without inserting newlines. As
39323 930bb1eb8dd5 Redo the comment about the 2.5 change in quoted-newline handling. Andrew McNamara <andrewm@object-craft.com.au> parents: 39292 diff changeset	81 a consequence, if newlines embedded within fields are important, the
930bb1eb8dd5 Redo the comment about the 2.5 change in quoted-newline handling. Andrew McNamara <andrewm@object-craft.com.au> parents: 39292 diff changeset	82 input should be split into lines in a manner which preserves the newline
39326 7f04793fe135 minor tweaks Skip Montanaro <skip@pobox.com> parents: 39323 diff changeset	83 characters]{2.5}
39286 d8888c8b872b Add a comment to the csv reader documentation that explains why the Skip Montanaro <skip@pobox.com> parents: 37477 diff changeset	84
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	85 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	86
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	87 \begin{funcdesc}{writer}{csvfile\optional{,
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	88 dialect=\code{'excel'}}\optional{, fmtparam}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	89 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	90 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	91 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	92 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	93 difference. An optional
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	94 {}\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	95 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	96 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	97 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	98 {}\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	99 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	100 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	101 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	102 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	103 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	104 \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	105 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	106 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	107 \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	108 with \function{str()} before being written.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	109 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	110
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	111 \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	112 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	113 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	114 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	115 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	116 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	117 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	118 for details of these parameters.
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	119 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	120
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	121 \begin{funcdesc}{unregister_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	122 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	123 \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	124 name.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	125 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	126
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	127 \begin{funcdesc}{get_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	128 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	129 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	130 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	131
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	132 \begin{funcdesc}{list_dialects}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	133 Return the names of all registered dialects.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	134 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	135
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	136 \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	137 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	138 \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	139 \versionadded{2.5}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	140 \end{funcdesc}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	141
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	142
28835 98e31cfd26dc reflect csv's change back to a module. Document the new sniffer api. Skip Montanaro <skip@pobox.com> parents: 28797 diff changeset	143 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	144
30632 f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	145 \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	146 fieldnames=\constant{None},\optional{,
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	147 restkey=\constant{None}\optional{,
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	148 restval=\constant{None}\optional{,
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	149 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	150 args, *kwds}}}}}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	151 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	152 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	153 {} \var{fieldnames}
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	154 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	155 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	156 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	157 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	158 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	159 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	160 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	161 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	162 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	163 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	164
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	165
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	166 \begin{classdesc}{DictWriter}{csvfile, fieldnames\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	167 restval=""\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	168 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	169 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	170 args, *kwds}}}}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	171 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	172 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	173 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	174 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	175 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	176 \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	177 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	178 \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	179 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	180 \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	181 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	182 instance.
30632 f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	183
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	184 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	185 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	186 \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	187 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	188 \var{csvfile}.
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames Skip Montanaro <skip@pobox.com> parents: 30399 diff changeset	189
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	190 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	191
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	192 \begin{classdesc*}{Dialect}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	193 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	194 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	195 \class{reader} or \class{writer} instance.
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	196 \end{classdesc*}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	197
34326 06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	198 \begin{classdesc}{excel}{}
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	199 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	200 CSV file.
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	201 \end{classdesc}
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	202
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	203 \begin{classdesc}{excel_tab}{}
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	204 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	205 Excel-generated TAB-delimited file.
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	206 \end{classdesc}
06643f071335 add a couple missing items Skip Montanaro <skip@pobox.com> parents: 32993 diff changeset	207
29169 434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	208 \begin{classdesc}{Sniffer}{}
434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	209 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	210 \end{classdesc}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	211
36148 aa707041505d typo Skip Montanaro <skip@pobox.com> parents: 34770 diff changeset	212 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	213
29169 434ef174f478 * Correct Sniffer doc to correspond to the implementation. Skip Montanaro <skip@pobox.com> parents: 28848 diff changeset	214 \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	215 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	216 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	217 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	218 characters.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	219 \end{methoddesc}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	220
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	221 \begin{methoddesc}{has_header}{sample}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	222 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	223 \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	224 headers.
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	225 \end{methoddesc}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	226
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 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	229
29361 fdac9b4d3717 QUOTE_ALWAYS -> QUOTE_ALL Skip Montanaro <skip@pobox.com> parents: 29169 diff changeset	230 \begin{datadesc}{QUOTE_ALL}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	231 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	232 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	233
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	234 \begin{datadesc}{QUOTE_MINIMAL}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	235 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	236 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	237 characters in \var{lineterminator}.
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	238 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	239
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	240 \begin{datadesc}{QUOTE_NONNUMERIC}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	241 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	242 fields.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	243
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	244 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	245 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	246
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	247 \begin{datadesc}{QUOTE_NONE}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	248 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	249 \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	250 \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	251 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	252 are encountered.
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	253
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	254 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	255 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	256
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	257
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	258 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	259
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	260 \begin{excdesc}{Error}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	261 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	262 \end{excdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	263
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 \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	266
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	267 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	268 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	269 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	270 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	271 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	272 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	273 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	274 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	275 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	276
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	277 Dialects support the following attributes:
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	278
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	279 \begin{memberdesc}[Dialect]{delimiter}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	280 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	281 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	282
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	283 \begin{memberdesc}[Dialect]{doublequote}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	284 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	285 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	286 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	287 \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	288
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	289 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	290 \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	291 is found in a field.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	292 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	293
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	294 \begin{memberdesc}[Dialect]{escapechar}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	295 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	296 \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	297 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	298 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	299 to \constant{None}, which disables escaping.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	300 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	301
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	302 \begin{memberdesc}[Dialect]{lineterminator}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	303 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	304 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	305
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	306 \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	307 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	308 behavior may change in the future.}
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]{quotechar}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	312 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	313 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	314 characters. It defaults to \code{'"'}.
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	315 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	316
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	317 \begin{memberdesc}[Dialect]{quoting}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	318 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	319 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	320 (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	321 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	322
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	323 \begin{memberdesc}[Dialect]{skipinitialspace}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	324 When \constant{True}, whitespace immediately following the \var{delimiter}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	325 is ignored. The default is \constant{False}.
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	326 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	327
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	328
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	329 \subsection{Reader Objects}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	330
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	331 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	332 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	333
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	334 \begin{methoddesc}[csv reader]{next}{}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	335 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	336 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	337 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	338
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	339 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	340
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	341 \begin{memberdesc}[csv reader]{dialect}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	342 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	343 \end{memberdesc}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	344
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	345 \begin{memberdesc}[csv reader]{line_num}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	346 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	347 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	348 \end{memberdesc}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	349
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	350
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	351 \subsection{Writer Objects}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	352
31408 e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	353 \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	354 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	355 {}\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	356 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	357 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	358 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	359 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	360 (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	361
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	362 \begin{methoddesc}[csv writer]{writerow}{row}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	363 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	364 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	365 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	366
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	367 \begin{methoddesc}[csv writer]{writerows}{rows}
31408 e7124e26925f expand on notion of row object type Skip Montanaro <skip@pobox.com> parents: 31407 diff changeset	368 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	369 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	370 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	371 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	372
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	373 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	374
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	375 \begin{memberdesc}[csv writer]{dialect}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	376 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	377 \end{memberdesc}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	378
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	379
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	380
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	381 \subsection{Examples\label{csv-examples}}
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	382
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	383 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	384
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	385 \begin{verbatim}
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	386 import csv
32993 4e2c66021bf3 [Bug #998307] Use open() instead of file() in docs Andrew M. Kuchling <amk@amk.ca> parents: 32553 diff changeset	387 reader = csv.reader(open("some.csv", "rb"))
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	388 for row in reader:
1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	389 print row
28339 cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	390 \end{verbatim}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	391
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	392 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	393
c099aa767952 show how easy it is to manipulate individual columns - from a request on Skip Montanaro <skip@pobox.com> parents: 31918 diff changeset	394 \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	395 import csv
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	396 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	397 for row in reader:
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	398 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	399 \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	400
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	401 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	402
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	403 \begin{verbatim}
28848 1bef3eca20ce organizational and markup cleansing Fred Drake <fdrake@acm.org> parents: 28835 diff changeset	404 import csv
32993 4e2c66021bf3 [Bug #998307] Use open() instead of file() in docs Andrew M. Kuchling <amk@amk.ca> parents: 32553 diff changeset	405 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	406 writer.writerows(someiterable)
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	407 \end{verbatim}
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 Registering a new dialect:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	410
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	411 \begin{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	412 import csv
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	413
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	414 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	415
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	416 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	417 \end{verbatim}
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	418
39290 805512cf14ef Follow TeX's conventions for hyphens Andrew M. Kuchling <amk@amk.ca> parents: 39288 diff changeset	419 A slightly more advanced use of the reader --- catching and reporting errors:
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	420
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	421 \begin{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	422 import csv, sys
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	423 filename = "some.csv"
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	424 reader = csv.reader(open(filename, "rb"))
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	425 try:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	426 for row in reader:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	427 print row
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	428 except csv.Error, e:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	429 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	430 \end{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	431
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	432 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	433 easily be done:
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	434
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	435 \begin{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	436 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	437 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	438 print row
34412 b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	439 \end{verbatim}
b32ae0eecdee Many updates to csv module doco. Andrew McNamara <andrewm@object-craft.com.au> parents: 34326 diff changeset	440
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	441 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	442 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	443 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	444 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	445 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	446
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 \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	448 \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	449 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	450 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	451 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	452 \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	453 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	454
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 \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	456 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	457
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 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	459 # 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	460 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	461 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	462 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	463 # 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	464 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	465
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	466 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	467 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	468 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	469 \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	470
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	471 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	472 \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	473 \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	474 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	475
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	476 \begin{verbatim}
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	477 import csv, codecs, cStringIO
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	478
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	479 class UTF8Recoder:
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	480 """
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	481 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	482 """
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	483 def __init__(self, f, encoding):
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	484 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	485
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	486 def __iter__(self):
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	487 return self
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	488
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	489 def next(self):
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	490 return self.reader.next().encode("utf-8")
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	491
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	492 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	493 """
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	494 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	495 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	496 """
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	497
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	498 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	499 f = UTF8Recoder(f, encoding)
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	500 self.reader = csv.reader(f, dialect=dialect, **kwds)
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	501
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	502 def next(self):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	503 row = self.reader.next()
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	504 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	505
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	506 def __iter__(self):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	507 return self
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	508
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	509 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	510 """
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	511 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	512 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	513 """
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	514
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	515 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	516 # Redirect output to a queue
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	517 self.queue = cStringIO.StringIO()
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	518 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	519 self.stream = f
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	520 self.encoder = codecs.getincrementalencoder(encoding)()
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 writerow(self, row):
37477 903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	523 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	524 # 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	525 data = self.queue.getvalue()
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	526 data = data.decode("utf-8")
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	527 # ... 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	528 data = self.encoder.encode(data)
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	529 # write to the target stream
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	530 self.stream.write(data)
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	531 # empty queue
903e3162099e Change the example classes UnicodeReader and UnicodeWriter so Walter Dörwald <walter@livinglogic.de> parents: 37452 diff changeset	532 self.queue.truncate(0)
34770 719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	533
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	534 def writerows(self, rows):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	535 for row in rows:
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	536 self.writerow(row)
719eb102ea44 add UnicodeReader and UnicodeWriter example classes Skip Montanaro <skip@pobox.com> parents: 34412 diff changeset	537 \end{verbatim}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcsv.tex @ 39940:dfd809dcf680 2.5