Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcsv.tex @ 38664:7619216bbc19 2.4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Bug #1502728: Correctly link against librt library on HP-UX. (backport from rev. 46743)
author Georg Brandl <georg@python.org>
date Thu, 08 Jun 2006 12:54:16 +0000
parents 4e2c66021bf3
children 2dd197014612 06643f071335
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{,
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
53 dialect=\code{'excel'}\optional{, fmtparam}}}
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}
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
57 method is called. If \var{csvfile} is a file object, it must be opened with
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
58 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
59 {}\var{dialect} parameter can be given
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
60 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
61 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
62 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
63 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
64 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
65 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
66 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
67 Parameters'' for details of these parameters.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
68
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
69 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
70 conversion is performed.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
71 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
72
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
73 \begin{funcdesc}{writer}{csvfile\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
74 dialect=\code{'excel'}\optional{, fmtparam}}}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
75 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
76 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
77 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
78 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
79 difference. An optional
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
80 {}\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
81 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
82 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
83 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
84 {}\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
85 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
86 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
87 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
88 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
89 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
90 \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
91 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
92 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
93 \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
94 with \function{str()} before being written.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
95 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
96
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
97 \begin{funcdesc}{register_dialect}{name, dialect}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
98 Associate \var{dialect} with \var{name}. \var{dialect} must be a subclass
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
99 of \class{csv.Dialect}. \var{name} must be a string or Unicode object.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
100 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
101
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
102 \begin{funcdesc}{unregister_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
103 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
104 \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
105 name.
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}{get_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
109 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
110 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
111 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
112
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
113 \begin{funcdesc}{list_dialects}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
114 Return the names of all registered dialects.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
115 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
116
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
117
28835
98e31cfd26dc reflect csv's change back to a module. Document the new sniffer api.
Skip Montanaro <skip@pobox.com>
parents: 28797
diff changeset
118 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
119
30632
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
120 \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
121 fieldnames=\constant{None},\optional{,
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
122 restkey=\constant{None}\optional{,
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
123 restval=\constant{None}\optional{,
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
124 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
125 *args, **kwds}}}}}}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
126 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
127 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
128 {} \var{fieldnames}
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
129 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
130 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
131 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
132 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
133 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
134 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
135 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
136 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
137 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
138 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
139
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
140
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
141 \begin{classdesc}{DictWriter}{csvfile, fieldnames\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
142 restval=""\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
143 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
144 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
145 *args, **kwds}}}}}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
146 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
147 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
148 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
149 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
150 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
151 \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
152 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
153 \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
154 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
155 \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
156 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
157 instance.
30632
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
158
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
159 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
160 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
161 \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
162 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
163 \var{csvfile}.
f9dfdcb897bb Make the fieldnames argument optional in the DictReader. If self.fieldnames
Skip Montanaro <skip@pobox.com>
parents: 30399
diff changeset
164
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
165 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
166
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
167 \begin{classdesc*}{Dialect}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
168 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
169 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
170 \class{reader} or \class{writer} instance.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
171 \end{classdesc*}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
172
29169
434ef174f478 * Correct Sniffer doc to correspond to the implementation.
Skip Montanaro <skip@pobox.com>
parents: 28848
diff changeset
173 \begin{classdesc}{Sniffer}{}
434ef174f478 * Correct Sniffer doc to correspond to the implementation.
Skip Montanaro <skip@pobox.com>
parents: 28848
diff changeset
174 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
175 \end{classdesc}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
176
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
177 The \class{Sniffer} class provides a single method:
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
178
29169
434ef174f478 * Correct Sniffer doc to correspond to the implementation.
Skip Montanaro <skip@pobox.com>
parents: 28848
diff changeset
179 \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
180 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
181 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
182 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
183 characters.
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
184 \end{methoddesc}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
185
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
186 \begin{methoddesc}{has_header}{sample}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
187 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
188 \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
189 headers.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
190 \end{methoddesc}
28339
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
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
193 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
194
29361
fdac9b4d3717 QUOTE_ALWAYS -> QUOTE_ALL
Skip Montanaro <skip@pobox.com>
parents: 29169
diff changeset
195 \begin{datadesc}{QUOTE_ALL}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
196 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
197 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
198
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
199 \begin{datadesc}{QUOTE_MINIMAL}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
200 Instructs \class{writer} objects to only quote those fields which contain
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
201 the current \var{delimiter} or begin with the current \var{quotechar}.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
202 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
203
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
204 \begin{datadesc}{QUOTE_NONNUMERIC}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
205 Instructs \class{writer} objects to quote all non-numeric fields.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
206 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
207
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
208 \begin{datadesc}{QUOTE_NONE}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
209 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
210 \var{delimiter} occurs in output data it is preceded by the current
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
211 \var{escapechar} character. When \constant{QUOTE_NONE} is in effect, it
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
212 is an error not to have a single-character \var{escapechar} defined, even if
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
213 no data to be written contains the \var{delimiter} character.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
214 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
215
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
216
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
217 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
218
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
219 \begin{excdesc}{Error}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
220 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
221 \end{excdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
222
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
223
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
224 \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
225
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
226 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
227 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
228 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
229 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
230 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
231 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
232 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
233 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
234 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
235
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
236 Dialects support the following attributes:
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
237
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
238 \begin{memberdesc}[Dialect]{delimiter}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
239 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
240 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
241
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
242 \begin{memberdesc}[Dialect]{doublequote}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
243 Controls how instances of \var{quotechar} appearing inside a field should be
31407
Skip Montanaro <skip@pobox.com>
parents: 30632
diff changeset
244 themselves be quoted. When \constant{True}, the character is doubled.
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
245 When \constant{False}, the \var{escapechar} must be a one-character string
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
246 which is used as a prefix to the \var{quotechar}. It defaults to
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
247 \constant{True}.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
248 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
249
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
250 \begin{memberdesc}[Dialect]{escapechar}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
251 A one-character string used to escape the \var{delimiter} if \var{quoting}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
252 is set to \constant{QUOTE_NONE}. It defaults to \constant{None}.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
253 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
254
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
255 \begin{memberdesc}[Dialect]{lineterminator}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
256 The string used to terminate lines in the CSV file. It defaults to
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
257 \code{'\e r\e n'}.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
258 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
259
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
260 \begin{memberdesc}[Dialect]{quotechar}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
261 A one-character string used to quote elements containing the \var{delimiter}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
262 or which start with the \var{quotechar}. It defaults to \code{'"'}.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
263 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
264
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
265 \begin{memberdesc}[Dialect]{quoting}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
266 Controls when quotes should be generated by the writer. It can take on any
30262
7b577377d546 SF bug #797853: Small problems with the csv module's documentation
Raymond Hettinger <python@rcn.com>
parents: 29747
diff changeset
267 of the \constant{QUOTE_*} constants (see section~\ref{csv-contents})
7b577377d546 SF bug #797853: Small problems with the csv module's documentation
Raymond Hettinger <python@rcn.com>
parents: 29747
diff changeset
268 and defaults to \constant{QUOTE_MINIMAL}.
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
269 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
270
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
271 \begin{memberdesc}[Dialect]{skipinitialspace}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
272 When \constant{True}, whitespace immediately following the \var{delimiter}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
273 is ignored. The default is \constant{False}.
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
274 \end{memberdesc}
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
275
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
276
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
277 \subsection{Reader Objects}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
278
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
279 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
280 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
281
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
282 \begin{methoddesc}[csv reader]{next}{}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
283 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
284 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
285 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
286
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
287
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
288 \subsection{Writer Objects}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
289
31408
e7124e26925f expand on notion of row object type
Skip Montanaro <skip@pobox.com>
parents: 31407
diff changeset
290 \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
291 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
292 {}\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
293 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
294 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
295 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
296 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
297 (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
298
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
299 \begin{methoddesc}[csv writer]{writerow}{row}
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
300 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
301 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
302 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
303
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
304 \begin{methoddesc}[csv writer]{writerows}{rows}
31408
e7124e26925f expand on notion of row object type
Skip Montanaro <skip@pobox.com>
parents: 31407
diff changeset
305 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
306 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
307 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
308 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
309
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
310
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
311 \subsection{Examples}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
312
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
313 The ``Hello, world'' of csv reading is
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
314
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
315 \begin{verbatim}
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
316 import csv
32993
4e2c66021bf3 [Bug #998307] Use open() instead of file() in docs
Andrew M. Kuchling <amk@amk.ca>
parents: 32553
diff changeset
317 reader = csv.reader(open("some.csv", "rb"))
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
318 for row in reader:
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
319 print row
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
320 \end{verbatim}
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
321
32553
c099aa767952 show how easy it is to manipulate individual columns - from a request on
Skip Montanaro <skip@pobox.com>
parents: 31918
diff changeset
322 To print just the first and last columns of each row try
c099aa767952 show how easy it is to manipulate individual columns - from a request on
Skip Montanaro <skip@pobox.com>
parents: 31918
diff changeset
323
c099aa767952 show how easy it is to manipulate individual columns - from a request on
Skip Montanaro <skip@pobox.com>
parents: 31918
diff changeset
324 \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
325 import csv
32993
4e2c66021bf3 [Bug #998307] Use open() instead of file() in docs
Andrew M. Kuchling <amk@amk.ca>
parents: 32553
diff changeset
326 reader = csv.reader(open("some.csv", "rb"))
32553
c099aa767952 show how easy it is to manipulate individual columns - from a request on
Skip Montanaro <skip@pobox.com>
parents: 31918
diff changeset
327 for row in reader:
c099aa767952 show how easy it is to manipulate individual columns - from a request on
Skip Montanaro <skip@pobox.com>
parents: 31918
diff changeset
328 print row[0], row[-1]
c099aa767952 show how easy it is to manipulate individual columns - from a request on
Skip Montanaro <skip@pobox.com>
parents: 31918
diff changeset
329 \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
330
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
331 The corresponding simplest possible writing example is
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
332
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
333 \begin{verbatim}
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
334 import csv
32993
4e2c66021bf3 [Bug #998307] Use open() instead of file() in docs
Andrew M. Kuchling <amk@amk.ca>
parents: 32553
diff changeset
335 writer = csv.writer(open("some.csv", "wb"))
28848
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
336 for row in someiterable:
1bef3eca20ce organizational and markup cleansing
Fred Drake <fdrake@acm.org>
parents: 28835
diff changeset
337 writer.writerow(row)
28339
cc35ed2b26a8 new CSV file processing module - see PEP 305
Skip Montanaro <skip@pobox.com>
parents:
diff changeset
338 \end{verbatim}