Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="csv-fmt-params.html" /> | |
13 | <link rel="prev" href="module-csv.html" /> | |
14 | <link rel="parent" href="module-csv.html" /> | |
15 | <link rel="next" href="csv-fmt-params.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>12.20.1 Module Contents </title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="12.20 csv " | |
25 | href="module-csv.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="12.20 csv " | |
28 | href="module-csv.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="12.20.2 Dialects and Formatting" | |
31 | href="csv-fmt-params.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="module-csv.html">12.20 csv </A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="module-csv.html">12.20 csv </A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="csv-fmt-params.html">12.20.2 Dialects and Formatting</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H2><A NAME="SECTION00142010000000000000000"></A><A NAME="csv-contents"></A> | |
56 | <BR> | |
57 | 12.20.1 Module Contents | |
58 | </H2> | |
59 | ||
60 | <P> | |
61 | The <tt class="module">csv</tt> module defines the following functions: | |
62 | ||
63 | <P> | |
64 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
65 | <td><nobr><b><tt id='l2h-4213' xml:id='l2h-4213' class="function">reader</tt></b>(</nobr></td> | |
66 | <td><var>csvfile</var><big>[</big><var>, | |
67 | dialect=<code>'excel'</code></var><big>[</big><var>, fmtparam</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
68 | <dd> | |
69 | Return a reader object which will iterate over lines in the given | |
70 | <var>csvfile</var>. <var>csvfile</var> can be any object which supports the | |
71 | iterator protocol and returns a string each time its <tt class="method">next</tt> | |
72 | method is called. If <var>csvfile</var> is a file object, it must be opened with | |
73 | the 'b' flag on platforms where that makes a difference. An optional | |
74 | <var>dialect</var> parameter can be given | |
75 | which is used to define a set of parameters specific to a particular CSV | |
76 | dialect. It may be an instance of a subclass of the <tt class="class">Dialect</tt> | |
77 | class or one of the strings returned by the <tt class="function">list_dialects</tt> | |
78 | function. The other optional <var>fmtparam</var> keyword arguments can be | |
79 | given to override individual formatting parameters in the current | |
80 | dialect. For more information about the dialect and formatting | |
81 | parameters, see section <A href="csv-fmt-params.html#csv-fmt-params">12.20.2</A>, ``Dialects and Formatting | |
82 | Parameters'' for details of these parameters. | |
83 | ||
84 | <P> | |
85 | All data read are returned as strings. No automatic data type | |
86 | conversion is performed. | |
87 | </dl> | |
88 | ||
89 | <P> | |
90 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
91 | <td><nobr><b><tt id='l2h-4214' xml:id='l2h-4214' class="function">writer</tt></b>(</nobr></td> | |
92 | <td><var>csvfile</var><big>[</big><var>, | |
93 | dialect=<code>'excel'</code></var><big>[</big><var>, fmtparam</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
94 | <dd> | |
95 | Return a writer object responsible for converting the user's data into | |
96 | delimited strings on the given file-like object. <var>csvfile</var> can be any | |
97 | object with a <tt class="function">write</tt> method. If <var>csvfile</var> is a file object, | |
98 | it must be opened with the 'b' flag on platforms where that makes a | |
99 | difference. An optional | |
100 | <var>dialect</var> parameter can be given which is used to define a set of | |
101 | parameters specific to a particular CSV dialect. It may be an instance | |
102 | of a subclass of the <tt class="class">Dialect</tt> class or one of the strings | |
103 | returned by the <tt class="function">list_dialects</tt> function. The other optional | |
104 | <var>fmtparam</var> keyword arguments can be given to override individual | |
105 | formatting parameters in the current dialect. For more information | |
106 | about the dialect and formatting parameters, see | |
107 | section <A href="csv-fmt-params.html#csv-fmt-params">12.20.2</A>, ``Dialects and Formatting Parameters'' for | |
108 | details of these parameters. To make it as easy as possible to | |
109 | interface with modules which implement the DB API, the value | |
110 | <tt class="constant">None</tt> is written as the empty string. While this isn't a | |
111 | reversible transformation, it makes it easier to dump SQL NULL data values | |
112 | to CSV files without preprocessing the data returned from a | |
113 | <code>cursor.fetch*()</code> call. All other non-string data are stringified | |
114 | with <tt class="function">str()</tt> before being written. | |
115 | </dl> | |
116 | ||
117 | <P> | |
118 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
119 | <td><nobr><b><tt id='l2h-4215' xml:id='l2h-4215' class="function">register_dialect</tt></b>(</nobr></td> | |
120 | <td><var>name, dialect</var>)</td></tr></table></dt> | |
121 | <dd> | |
122 | Associate <var>dialect</var> with <var>name</var>. <var>dialect</var> must be a subclass | |
123 | of <tt class="class">csv.Dialect</tt>. <var>name</var> must be a string or Unicode object. | |
124 | </dl> | |
125 | ||
126 | <P> | |
127 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
128 | <td><nobr><b><tt id='l2h-4216' xml:id='l2h-4216' class="function">unregister_dialect</tt></b>(</nobr></td> | |
129 | <td><var>name</var>)</td></tr></table></dt> | |
130 | <dd> | |
131 | Delete the dialect associated with <var>name</var> from the dialect registry. An | |
132 | <tt class="exception">Error</tt> is raised if <var>name</var> is not a registered dialect | |
133 | name. | |
134 | </dl> | |
135 | ||
136 | <P> | |
137 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
138 | <td><nobr><b><tt id='l2h-4217' xml:id='l2h-4217' class="function">get_dialect</tt></b>(</nobr></td> | |
139 | <td><var>name</var>)</td></tr></table></dt> | |
140 | <dd> | |
141 | Return the dialect associated with <var>name</var>. An <tt class="exception">Error</tt> is | |
142 | raised if <var>name</var> is not a registered dialect name. | |
143 | </dl> | |
144 | ||
145 | <P> | |
146 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
147 | <td><nobr><b><tt id='l2h-4218' xml:id='l2h-4218' class="function">list_dialects</tt></b>(</nobr></td> | |
148 | <td><var></var>)</td></tr></table></dt> | |
149 | <dd> | |
150 | Return the names of all registered dialects. | |
151 | </dl> | |
152 | ||
153 | <P> | |
154 | The <tt class="module">csv</tt> module defines the following classes: | |
155 | ||
156 | <P> | |
157 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
158 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-4219' xml:id='l2h-4219' class="class">DictReader</tt></b>(</nobr></td> | |
159 | <td><var>csvfile</var><big>[</big><var>, | |
160 | fieldnames=<tt class="constant">None</tt>,</var><big>[</big><var>, | |
161 | restkey=<tt class="constant">None</tt></var><big>[</big><var>, | |
162 | restval=<tt class="constant">None</tt></var><big>[</big><var>, | |
163 | dialect=<code>'excel'</code></var><big>[</big><var>, | |
164 | *args, **kwds</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
165 | <dd> | |
166 | Create an object which operates like a regular reader but maps the | |
167 | information read into a dict whose keys are given by the optional | |
168 | <var>fieldnames</var> | |
169 | parameter. If the <var>fieldnames</var> parameter is omitted, the values in | |
170 | the first row of the <var>csvfile</var> will be used as the fieldnames. | |
171 | If the row read has fewer fields than the fieldnames sequence, | |
172 | the value of <var>restval</var> will be used as the default value. If the row | |
173 | read has more fields than the fieldnames sequence, the remaining data is | |
174 | added as a sequence keyed by the value of <var>restkey</var>. If the row read | |
175 | has fewer fields than the fieldnames sequence, the remaining keys take the | |
176 | value of the optional <var>restval</var> parameter. Any other optional or | |
177 | keyword arguments are passed to the underlying <tt class="class">reader</tt> instance. | |
178 | </dl> | |
179 | ||
180 | <P> | |
181 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
182 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-4220' xml:id='l2h-4220' class="class">DictWriter</tt></b>(</nobr></td> | |
183 | <td><var>csvfile, fieldnames</var><big>[</big><var>, | |
184 | restval=""</var><big>[</big><var>, | |
185 | extrasaction=<code>'raise'</code></var><big>[</big><var>, | |
186 | dialect=<code>'excel'</code></var><big>[</big><var>, | |
187 | *args, **kwds</var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
188 | <dd> | |
189 | Create an object which operates like a regular writer but maps dictionaries | |
190 | onto output rows. The <var>fieldnames</var> parameter identifies the order in | |
191 | which values in the dictionary passed to the <tt class="method">writerow()</tt> method are | |
192 | written to the <var>csvfile</var>. The optional <var>restval</var> parameter | |
193 | specifies the value to be written if the dictionary is missing a key in | |
194 | <var>fieldnames</var>. If the dictionary passed to the <tt class="method">writerow()</tt> | |
195 | method contains a key not found in <var>fieldnames</var>, the optional | |
196 | <var>extrasaction</var> parameter indicates what action to take. If it is set | |
197 | to <code>'raise'</code> a <tt class="exception">ValueError</tt> is raised. If it is set to | |
198 | <code>'ignore'</code>, extra values in the dictionary are ignored. Any other | |
199 | optional or keyword arguments are passed to the underlying <tt class="class">writer</tt> | |
200 | instance. | |
201 | ||
202 | <P> | |
203 | Note that unlike the <tt class="class">DictReader</tt> class, the <var>fieldnames</var> | |
204 | parameter of the <tt class="class">DictWriter</tt> is not optional. Since Python's | |
205 | <tt class="class">dict</tt> objects are not ordered, there is not enough information | |
206 | available to deduce the order in which the row should be written to the | |
207 | <var>csvfile</var>. | |
208 | ||
209 | <P> | |
210 | </dl> | |
211 | ||
212 | <P> | |
213 | <dl><dt><b><span class="typelabel">class</span> <tt id='l2h-4221' xml:id='l2h-4221' class="class">Dialect</tt></b> | |
214 | <dd> | |
215 | The <tt class="class">Dialect</tt> class is a container class relied on primarily for its | |
216 | attributes, which are used to define the parameters for a specific | |
217 | <tt class="class">reader</tt> or <tt class="class">writer</tt> instance. | |
218 | </dl> | |
219 | ||
220 | <P> | |
221 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
222 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-4222' xml:id='l2h-4222' class="class">Sniffer</tt></b>(</nobr></td> | |
223 | <td><var></var>)</td></tr></table></dt> | |
224 | <dd> | |
225 | The <tt class="class">Sniffer</tt> class is used to deduce the format of a CSV file. | |
226 | </dl> | |
227 | ||
228 | <P> | |
229 | The <tt class="class">Sniffer</tt> class provides a single method: | |
230 | ||
231 | <P> | |
232 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
233 | <td><nobr><b><tt id='l2h-4223' xml:id='l2h-4223' class="method">sniff</tt></b>(</nobr></td> | |
234 | <td><var>sample</var><big>[</big><var>,delimiters=None</var><big>]</big><var></var>)</td></tr></table></dt> | |
235 | <dd> | |
236 | Analyze the given <var>sample</var> and return a <tt class="class">Dialect</tt> subclass | |
237 | reflecting the parameters found. If the optional <var>delimiters</var> parameter | |
238 | is given, it is interpreted as a string containing possible valid delimiter | |
239 | characters. | |
240 | </dl> | |
241 | ||
242 | <P> | |
243 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
244 | <td><nobr><b><tt id='l2h-4224' xml:id='l2h-4224' class="method">has_header</tt></b>(</nobr></td> | |
245 | <td><var>sample</var>)</td></tr></table></dt> | |
246 | <dd> | |
247 | Analyze the sample text (presumed to be in CSV format) and return | |
248 | <tt class="constant">True</tt> if the first row appears to be a series of column | |
249 | headers. | |
250 | </dl> | |
251 | ||
252 | <P> | |
253 | The <tt class="module">csv</tt> module defines the following constants: | |
254 | ||
255 | <P> | |
256 | <dl><dt><b><tt id='l2h-4225' xml:id='l2h-4225'>QUOTE_ALL</tt></b></dt> | |
257 | <dd> | |
258 | Instructs <tt class="class">writer</tt> objects to quote all fields. | |
259 | </dd></dl> | |
260 | ||
261 | <P> | |
262 | <dl><dt><b><tt id='l2h-4226' xml:id='l2h-4226'>QUOTE_MINIMAL</tt></b></dt> | |
263 | <dd> | |
264 | Instructs <tt class="class">writer</tt> objects to only quote those fields which contain | |
265 | the current <var>delimiter</var> or begin with the current <var>quotechar</var>. | |
266 | </dd></dl> | |
267 | ||
268 | <P> | |
269 | <dl><dt><b><tt id='l2h-4227' xml:id='l2h-4227'>QUOTE_NONNUMERIC</tt></b></dt> | |
270 | <dd> | |
271 | Instructs <tt class="class">writer</tt> objects to quote all non-numeric fields. | |
272 | </dd></dl> | |
273 | ||
274 | <P> | |
275 | <dl><dt><b><tt id='l2h-4228' xml:id='l2h-4228'>QUOTE_NONE</tt></b></dt> | |
276 | <dd> | |
277 | Instructs <tt class="class">writer</tt> objects to never quote fields. When the current | |
278 | <var>delimiter</var> occurs in output data it is preceded by the current | |
279 | <var>escapechar</var> character. When <tt class="constant">QUOTE_NONE</tt> is in effect, it | |
280 | is an error not to have a single-character <var>escapechar</var> defined, even if | |
281 | no data to be written contains the <var>delimiter</var> character. | |
282 | </dd></dl> | |
283 | ||
284 | <P> | |
285 | The <tt class="module">csv</tt> module defines the following exception: | |
286 | ||
287 | <P> | |
288 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-4229' xml:id='l2h-4229' class="exception">Error</tt></b></dt> | |
289 | <dd> | |
290 | Raised by any of the functions when an error is detected. | |
291 | </dd></dl> | |
292 | ||
293 | <P> | |
294 | ||
295 | <DIV CLASS="navigation"> | |
296 | <div class='online-navigation'> | |
297 | <p></p><hr /> | |
298 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
299 | <tr> | |
300 | <td class='online-navigation'><a rel="prev" title="12.20 csv " | |
301 | href="module-csv.html"><img src='../icons/previous.png' | |
302 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
303 | <td class='online-navigation'><a rel="parent" title="12.20 csv " | |
304 | href="module-csv.html"><img src='../icons/up.png' | |
305 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
306 | <td class='online-navigation'><a rel="next" title="12.20.2 Dialects and Formatting" | |
307 | href="csv-fmt-params.html"><img src='../icons/next.png' | |
308 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
309 | <td align="center" width="100%">Python Library Reference</td> | |
310 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
311 | href="contents.html"><img src='../icons/contents.png' | |
312 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
313 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
314 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
315 | <td class='online-navigation'><a rel="index" title="Index" | |
316 | href="genindex.html"><img src='../icons/index.png' | |
317 | border='0' height='32' alt='Index' width='32' /></A></td> | |
318 | </tr></table> | |
319 | <div class='online-navigation'> | |
320 | <b class="navlabel">Previous:</b> | |
321 | <a class="sectref" rel="prev" href="module-csv.html">12.20 csv </A> | |
322 | <b class="navlabel">Up:</b> | |
323 | <a class="sectref" rel="parent" href="module-csv.html">12.20 csv </A> | |
324 | <b class="navlabel">Next:</b> | |
325 | <a class="sectref" rel="next" href="csv-fmt-params.html">12.20.2 Dialects and Formatting</A> | |
326 | </div> | |
327 | </div> | |
328 | <hr /> | |
329 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
330 | </DIV> | |
331 | <!--End of Navigation Panel--> | |
332 | <ADDRESS> | |
333 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
334 | </ADDRESS> | |
335 | </BODY> | |
336 | </HTML> |