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

annotate Doc/lib/libcsv.tex @ 28646:193b8aec00ce legacy-trunk

Changes from Jonathan Riehl to allow his pgen extension (PEP 269) to work. This includes some more code that used to be part of pgen in the main parser; I'm okay with that. I'll see if the Windows build needs work next.

author	Guido van Rossum <guido@python.org>
date	Thu, 17 Apr 2003 14:55:42 +0000
parents	cc35ed2b26a8
children	21633e9df8cc

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.}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	5
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	6 \versionadded{2.3}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	7 \index{csv}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	8 \indexii{data}{tabular}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	9
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	10 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	11 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	12 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	13 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	14 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	15 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	16 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	17 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	18 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	19 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	20
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	21 The \module{csv} module implements classes to read and write tabular data in
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	22 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	23 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	24 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	25 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	26 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	27
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	28 The \module{csv} module's \class{reader} and \class{writer} objects read and
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	29 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	30 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	31
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	32 \note{The first version of the \module{csv} module doesn't support Unicode
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	33 input. Also, there are currently some issues regarding \ASCII{} NUL
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	34 characters. Accordingly, all input should generally be plain \ASCII{} to be
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	35 safe. These restrictions will be removed in the future.}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	36
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	37 \begin{seealso}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	38 % \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	39 \seepep{305}{CSV File API}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	40 {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	41 to Python.}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	42 \end{seealso}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	43
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	44
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	45 \subsection{Module Contents}
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
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	48 The \module{csv} module defines the following functions:
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	49
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	50 \begin{funcdesc}{reader}{csvfile\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	51 dialect=\code{'excel'}\optional{, fmtparam}}}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	52 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	53 {}\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	54 iterator protocol and returns a string each time its \method{next}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	55 method is called. An optional \var{dialect} parameter can be given
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	56 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	57 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	58 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	59 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	60 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	61 dialect. For more information about the dialect and formatting
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	62 parameters, see section~\ref{fmt-params}, ``Dialects and Formatting
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	63 Parameters'' for details of these parameters.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	64
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	65 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	66 conversion is performed.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	67 \end{funcdesc}
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 \begin{funcdesc}{writer}{csvfile\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	70 dialect=\code{'excel'}\optional{, fmtparam}}}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	71 Return a writer object responsible for converting the user's data into
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	72 delimited strings on the given file-like object. An optional
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	73 {}\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	74 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	75 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	76 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	77 {}\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	78 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	79 about the dialect and formatting parameters, see
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	80 section~\ref{fmt-params}, ``Dialects and Formatting Parameters'' for
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	81 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	82 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	83 \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	84 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	85 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	86 \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	87 with \function{str()} before being written.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	88 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	89
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	90 \begin{funcdesc}{register_dialect}{name, dialect}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	91 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	92 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	93 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	94
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	95 \begin{funcdesc}{unregister_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	96 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	97 \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	98 name.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	99 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	100
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	101 \begin{funcdesc}{get_dialect}{name}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	102 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	103 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	104 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	105
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	106 \begin{funcdesc}{list_dialects}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	107 Return the names of all registered dialects.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	108 \end{funcdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	109
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	110
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	111 The \module{csv} module defines the following classes:
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{classdesc}{DictReader}{csvfile, fieldnames\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	114 restkey=\code{None}\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	115 restval=\code{None}\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	116 dialect=\code{'excel'}\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	117 fmtparam}}}}}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	118 Create an object which operates like a regular reader but maps the
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	119 information read into a dict whose keys are given by the \var{fieldnames}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	120 parameter. If the row read has fewer fields than the fieldnames sequence,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	121 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	122 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	123 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	124 has fewer fields than the fieldnames sequence, the remaining keys take the
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	125 value of the optiona \var{restval} parameter. All other parameters are
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	126 interpreted as for regular readers.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	127 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	128
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	129
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	130 \begin{classdesc}{DictWriter}{csvfile, fieldnames\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	131 restval=""\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	132 extrasaction=\code{'raise'}\optional{,
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	133 dialect=\code{'excel'}\optional{, fmtparam}}}}}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	134 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	135 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	136 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	137 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	138 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	139 \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	140 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	141 \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	142 to \code{'raise'} a \exception{ValueError} is raised. If it is set to
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	143 \code{'ignore'}, extra values in the dictionary are ignored. All other
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	144 parameters are interpreted as for regular writers.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	145 \end{classdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	146
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	147
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	148 \begin{classdesc*}{Dialect}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	149 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	150 attributes, which are used to define the parameters for a specific
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	151 \class{reader} or \class{writer} instance. Dialect objects support the
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	152 following data attributes:
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	153
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	154 \begin{memberdesc}[string]{delimiter}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	155 A one-character string used to separate fields. It defaults to \code{","}.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	156 \end{memberdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	157
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	158 \begin{memberdesc}[boolean]{doublequote}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	159 Controls how instances of \var{quotechar} appearing inside a field should be
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	160 themselves be quoted. When \constant{True}, the character is doubledd.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	161 When \constant{False}, the \var{escapechar} must be a one-character string
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	162 which is used as a prefix to the \var{quotechar}. It defaults to
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	163 \constant{True}.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	164 \end{memberdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	165
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	166 \begin{memberdesc}{escapechar}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	167 A one-character string used to escape the \var{delimiter} if \var{quoting}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	168 is set to \constant{QUOTE_NONE}. It defaults to \constant{None}.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	169 \end{memberdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	170
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	171 \begin{memberdesc}[string]{lineterminator}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	172 The string used to terminate lines in the CSV file. It defaults to
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	173 \code{"\e r\e n"}.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	174 \end{memberdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	175
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	176 \begin{memberdesc}[string]{quotechar}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	177 A one-character string used to quote elements containing the \var{delimiter}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	178 or which start with the \var{quotechar}. It defaults to \code{'"'}.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	179 \end{memberdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	180
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	181 \begin{memberdesc}[integer]{quoting}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	182 Controls when quotes should be generated by the writer. It can take on any
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	183 of the \code{QUOTE_*} constants defined below and defaults to
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	184 \constant{QUOTE_MINIMAL}.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	185 \end{memberdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	186
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	187 \begin{memberdesc}[boolean]{skipinitialspace}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	188 When \constant{True}, whitespace immediately following the \var{delimiter}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	189 is ignored. The default is \constant{False}.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	190 \end{memberdesc}
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 \end{classdesc*}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	193
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	194 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	195
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	196 \begin{datadesc}{QUOTE_ALWAYS}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	197 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	198 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	199
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	200 \begin{datadesc}{QUOTE_MINIMAL}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	201 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	202 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	203 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	204
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	205 \begin{datadesc}{QUOTE_NONNUMERIC}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	206 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	207 \end{datadesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	208
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	209 \begin{datadesc}{QUOTE_NONE}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	210 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	211 \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	212 \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	213 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	214 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	215 \end{datadesc}
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
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	218 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	219
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	220 \begin{excdesc}{Error}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	221 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	222 \end{excdesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	223
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	224
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	225 \subsection{Dialects and Formatting Parameters\label{fmt-params}}
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 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	228 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	229 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	230 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	231 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	232 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	233 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	234 individual formatting parameters, which have the same names as the
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	235 attributes defined above for the \class{Dialect} class.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	236
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	237
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	238 \subsection{Reader Objects}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	239
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	240 \class{DictReader} and \var{reader} objects have the following public
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	241 methods:
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	242
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	243 \begin{methoddesc}{next}{}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	244 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	245 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	246 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	247
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	248
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	249 \subsection{Writer Objects}
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 \class{DictWriter} and \var{writer} objects have the following public
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	252 methods:
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 \begin{methoddesc}{writerow}{row}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	255 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	256 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	257 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	258
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	259 \begin{methoddesc}{writerows}{rows}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	260 Write all the \var{rows} parameters to the writer's file object, formatted
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	261 according to the current dialect.
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	262 \end{methoddesc}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	263
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	264
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	265 \subsection{Examples}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	266
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	267 The ``Hello, world'' of csv reading is
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	268
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	269 \begin{verbatim}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	270 reader = csv.reader(file("some.csv"))
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	271 for row in reader:
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	272 print row
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	273 \end{verbatim}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	274
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	275 The corresponding simplest possible writing example is
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 \begin{verbatim}
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	278 writer = csv.writer(file("some.csv", "w"))
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	279 for row in someiterable:
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	280 writer.writerow(row)
cc35ed2b26a8 new CSV file processing module - see PEP 305 Skip Montanaro <skip@pobox.com> parents: diff changeset	281 \end{verbatim}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libcsv.tex @ 28646:193b8aec00ce legacy-trunk