Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcsv.tex @ 37850:ebe59cd18273

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use explicit relative import for an, ehm, relative import.
author Thomas Wouters <thomas@python.org>
date Tue, 18 Apr 2006 21:41:36 +0000
parents 455672a8f877
children f731859e9b3b 49dbedfb1d74
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
36 characters. Accordingly, all input should generally be printable
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
37 \ASCII{} to be safe. These restrictions will be removed in the future.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
38 \end{notice}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
39
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
40 \begin{seealso}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
41 % \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
42 \seepep{305}{CSV File API}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
43 {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
44 to Python.}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
45 \end{seealso}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
46
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
47
30262
7b577377d546 SF bug #797853: Small problems with the csv module's documentation
Raymond Hettinger <python@rcn.com>
parents: 29747
diff changeset
48 \subsection{Module Contents \label{csv-contents}}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
49
28835
98e31cfd26dc reflect csv's change back to a module. Document the new sniffer api.
Skip Montanaro <skip@pobox.com>
parents: 28797
diff changeset
50 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
51
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
52 \begin{funcdesc}{reader}{csvfile\optional{,
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
53 dialect=\code{'excel'}}\optional{, fmtparam}}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
54 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
55 {}\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
56 iterator protocol and returns a string each time its \method{next}
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
57 method is called - file objects and list objects are both suitable.
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
58 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
59 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
60 {}\var{dialect} parameter can be given
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
61 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
62 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
63 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
64 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
65 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
66 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
67 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
68 Parameters'' for details of these parameters.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
69
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
70 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
71 conversion is performed.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
72 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
73
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
74 \begin{funcdesc}{writer}{csvfile\optional{,
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
75 dialect=\code{'excel'}}\optional{, fmtparam}}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
76 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
77 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
78 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
79 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
80 difference. An optional
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
81 {}\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
82 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
83 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
84 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
85 {}\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
86 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
87 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
88 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
89 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
90 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
91 \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
92 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
93 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
94 \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
95 with \function{str()} before being written.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
96 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
97
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
98 \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
99 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
100 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
101 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
102 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
103 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
104 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
105 for details of these parameters.
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
106 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
107
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
108 \begin{funcdesc}{unregister_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
109 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
110 \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
111 name.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
112 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
113
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
114 \begin{funcdesc}{get_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
115 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
116 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
117 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
118
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
119 \begin{funcdesc}{list_dialects}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
120 Return the names of all registered dialects.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
121 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
122
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
123 \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
124 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
125 \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
126 \versionadded{2.5}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
127 \end{funcdesc}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
128
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
129
28835
98e31cfd26dc reflect csv's change back to a module. Document the new sniffer api.
Skip Montanaro <skip@pobox.com>
parents: 28797
diff changeset
130 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
131
30632
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
132 \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
133 fieldnames=\constant{None},\optional{,
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
134 restkey=\constant{None}\optional{,
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
135 restval=\constant{None}\optional{,
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
136 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
137 *args, **kwds}}}}}}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
138 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
139 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
140 {} \var{fieldnames}
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
141 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
142 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
143 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
144 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
145 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
146 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
147 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
148 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
149 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
150 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
151
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
152
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
153 \begin{classdesc}{DictWriter}{csvfile, fieldnames\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
154 restval=""\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
155 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
156 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
157 *args, **kwds}}}}}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
158 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
159 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
160 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
161 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
162 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
163 \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
164 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
165 \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
166 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
167 \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
168 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
169 instance.
30632
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
170
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
171 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
172 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
173 \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
174 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
175 \var{csvfile}.
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
176
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
177 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
178
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
179 \begin{classdesc*}{Dialect}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
180 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
181 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
182 \class{reader} or \class{writer} instance.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
183 \end{classdesc*}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
184
34326
06643f071335 add a couple missing items
Skip Montanaro <skip@pobox.com>
parents: 32993
diff changeset
185 \begin{classdesc}{excel}{}
06643f071335 add a couple missing items
Skip Montanaro <skip@pobox.com>
parents: 32993
diff changeset
186 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
187 CSV file.
06643f071335 add a couple missing items
Skip Montanaro <skip@pobox.com>
parents: 32993
diff changeset
188 \end{classdesc}
06643f071335 add a couple missing items
Skip Montanaro <skip@pobox.com>
parents: 32993
diff changeset
189
06643f071335 add a couple missing items
Skip Montanaro <skip@pobox.com>
parents: 32993
diff changeset
190 \begin{classdesc}{excel_tab}{}
06643f071335 add a couple missing items
Skip Montanaro <skip@pobox.com>
parents: 32993
diff changeset
191 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
192 Excel-generated TAB-delimited file.
06643f071335 add a couple missing items
Skip Montanaro <skip@pobox.com>
parents: 32993
diff changeset
193 \end{classdesc}
06643f071335 add a couple missing items
Skip Montanaro <skip@pobox.com>
parents: 32993
diff changeset
194
29169
434ef174f478 * Correct Sniffer doc to correspond to the implementation.
Skip Montanaro <skip@pobox.com>
parents: 28848
diff changeset
195 \begin{classdesc}{Sniffer}{}
434ef174f478 * Correct Sniffer doc to correspond to the implementation.
Skip Montanaro <skip@pobox.com>
parents: 28848
diff changeset
196 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
197 \end{classdesc}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
198
36148
Skip Montanaro <skip@pobox.com>
parents: 34770
diff changeset
199 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
200
29169
434ef174f478 * Correct Sniffer doc to correspond to the implementation.
Skip Montanaro <skip@pobox.com>
parents: 28848
diff changeset
201 \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
202 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
203 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
204 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
205 characters.
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
206 \end{methoddesc}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
207
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
208 \begin{methoddesc}{has_header}{sample}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
209 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
210 \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
211 headers.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
212 \end{methoddesc}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
213
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
214
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
215 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
216
29361
fdac9b4d3717 QUOTE_ALWAYS -> QUOTE_ALL
Skip Montanaro <skip@pobox.com>
parents: 29169
diff changeset
217 \begin{datadesc}{QUOTE_ALL}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
218 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
219 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
220
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
221 \begin{datadesc}{QUOTE_MINIMAL}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
222 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
223 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
224 characters in \var{lineterminator}.
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
225 \end{datadesc}
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 \begin{datadesc}{QUOTE_NONNUMERIC}
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
228 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
229 fields.
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
230
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
231 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
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_NONE}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
235 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
236 \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
237 \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
238 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
239 are encountered.
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
240
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
241 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
242 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
243
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
244
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
245 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
246
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
247 \begin{excdesc}{Error}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
248 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
249 \end{excdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
250
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
251
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
252 \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
253
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
254 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
255 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
256 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
257 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
258 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
259 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
260 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
261 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
262 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
263
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
264 Dialects support the following attributes:
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
265
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
266 \begin{memberdesc}[Dialect]{delimiter}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
267 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
268 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
269
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
270 \begin{memberdesc}[Dialect]{doublequote}
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
271 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
272 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
273 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
274 \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
275
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
276 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
277 \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
278 is found in a field.
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
279 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
280
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
281 \begin{memberdesc}[Dialect]{escapechar}
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
282 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
283 \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
284 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
285 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
286 to \constant{None}, which disables escaping.
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
287 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
288
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
289 \begin{memberdesc}[Dialect]{lineterminator}
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
290 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
291 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
292
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
293 \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
294 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
295 behavior may change in the future.}
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
296 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
297
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
298 \begin{memberdesc}[Dialect]{quotechar}
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
299 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
300 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
301 characters. It defaults to \code{'"'}.
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
302 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
303
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
304 \begin{memberdesc}[Dialect]{quoting}
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
305 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
306 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
307 (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
308 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
309
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
310 \begin{memberdesc}[Dialect]{skipinitialspace}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
311 When \constant{True}, whitespace immediately following the \var{delimiter}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
312 is ignored. The default is \constant{False}.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
313 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
314
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
315
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
316 \subsection{Reader Objects}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
317
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
318 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
319 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
320
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
321 \begin{methoddesc}[csv reader]{next}{}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
322 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
323 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
324 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
325
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
326 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
327
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
328 \begin{memberdesc}[csv reader]{dialect}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
329 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
330 \end{memberdesc}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
331
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
332 \begin{memberdesc}[csv reader]{line_num}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
333 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
334 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
335 \end{memberdesc}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
336
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
337
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
338 \subsection{Writer Objects}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
339
31408
e7124e26925f expand on notion of row object type
Skip Montanaro <skip@pobox.com>
parents: 31407
diff changeset
340 \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
341 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
342 {}\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
343 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
344 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
345 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
346 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
347 (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
348
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
349 \begin{methoddesc}[csv writer]{writerow}{row}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
350 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
351 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
352 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
353
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
354 \begin{methoddesc}[csv writer]{writerows}{rows}
31408
e7124e26925f expand on notion of row object type
Skip Montanaro <skip@pobox.com>
parents: 31407
diff changeset
355 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
356 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
357 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
358 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
359
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
360 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
361
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
362 \begin{memberdesc}[csv writer]{dialect}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
363 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
364 \end{memberdesc}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
365
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
366
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
367
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
368 \subsection{Examples}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
369
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
370 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
371
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
372 \begin{verbatim}
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
373 import csv
32993
4e2c66021bf3 [Bug #998307] Use open() instead of file() in docs
Andrew M. Kuchling <amk@amk.ca>
parents: 32553
diff changeset
374 reader = csv.reader(open("some.csv", "rb"))
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
375 for row in reader:
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
376 print row
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
377 \end{verbatim}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
378
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
379 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
380
c099aa767952 show how easy it is to manipulate individual columns - from a request on
Skip Montanaro <skip@pobox.com>
parents: 31918
diff changeset
381 \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
382 import csv
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
383 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
384 for row in reader:
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
385 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
386 \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
387
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
388 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
389
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
390 \begin{verbatim}
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
391 import csv
32993
4e2c66021bf3 [Bug #998307] Use open() instead of file() in docs
Andrew M. Kuchling <amk@amk.ca>
parents: 32553
diff changeset
392 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
393 writer.writerows(someiterable)
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
394 \end{verbatim}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
395
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
396 Registering a new dialect:
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
397
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
398 \begin{verbatim}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
399 import csv
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
400
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
401 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
402
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
403 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
404 \end{verbatim}
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
405
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
406 A slightly more advanced use of the reader - catching and reporting errors:
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
407
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
408 \begin{verbatim}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
409 import csv, sys
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
410 filename = "some.csv"
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
411 reader = csv.reader(open(filename, "rb"))
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
412 try:
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
413 for row in reader:
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
414 print row
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
415 except csv.Error, e:
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
416 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
417 \end{verbatim}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
418
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
419 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
420 easily be done:
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
421
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
422 \begin{verbatim}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
423 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
424 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
425 print row
34412
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
426 \end{verbatim}
b32ae0eecdee Many updates to csv module doco.
Andrew McNamara <andrewm@object-craft.com.au>
parents: 34326
diff changeset
427
34770
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
428 The \module{csv} module doesn't directly support reading and writing
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
429 Unicode, but it is 8-bit clean save for some problems with \ASCII{} NUL
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
430 characters, so you can write classes that handle the encoding and decoding
36870
455672a8f877 Bug #1440831: fix csv UnicodeWriter example
Georg Brandl <georg@python.org>
parents: 36525
diff changeset
431 for you as long as you avoid encodings like utf-16 that use NULs:
34770
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
432
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
433 \begin{verbatim}
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
434 import csv
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
435
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
436 class UnicodeReader:
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
437 def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
438 self.reader = csv.reader(f, dialect=dialect, **kwds)
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
439 self.encoding = encoding
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
440
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
441 def next(self):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
442 row = self.reader.next()
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
443 return [unicode(s, self.encoding) for s in row]
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
444
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
445 def __iter__(self):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
446 return self
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
447
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
448 class UnicodeWriter:
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
449 def __init__(self, f, dialect=csv.excel, encoding="utf-8", **kwds):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
450 self.writer = csv.writer(f, dialect=dialect, **kwds)
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
451 self.encoding = encoding
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
452
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
453 def writerow(self, row):
36870
455672a8f877 Bug #1440831: fix csv UnicodeWriter example
Georg Brandl <georg@python.org>
parents: 36525
diff changeset
454 self.writer.writerow([s.encode(self.encoding) for s in row])
34770
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
455
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
456 def writerows(self, rows):
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
457 for row in rows:
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
458 self.writerow(row)
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
459 \end{verbatim}
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
460
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
461 They should work just like the \class{csv.reader} and \class{csv.writer}
719eb102ea44 add UnicodeReader and UnicodeWriter example classes
Skip Montanaro <skip@pobox.com>
parents: 34412
diff changeset
462 classes but add an \var{encoding} parameter.