diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/lib/libcsv.tex | 157 |
1 files changed, 81 insertions, 76 deletions
diff --git a/Doc/lib/libcsv.tex b/Doc/lib/libcsv.tex index 7de9056..f30aefe 100644 --- a/Doc/lib/libcsv.tex +++ b/Doc/lib/libcsv.tex @@ -30,10 +30,12 @@ The \module{csv} module's \class{reader} and \class{writer} objects read and write sequences. Programmers can also read and write data in dictionary form using the \class{DictReader} and \class{DictWriter} classes. -\note{The first version of the \module{csv} module doesn't support Unicode -input. Also, there are currently some issues regarding \ASCII{} NUL -characters. Accordingly, all input should generally be printable \ASCII{} -to be safe. These restrictions will be removed in the future.} +\begin{notice} + This version of the \module{csv} module doesn't support Unicode + input. Also, there are currently some issues regarding \ASCII{} NUL + characters. Accordingly, all input should generally be printable + \ASCII{} to be safe. These restrictions will be removed in the future. +\end{notice} \begin{seealso} % \seemodule{array}{Arrays of uniformly types numeric values.} @@ -45,7 +47,6 @@ to be safe. These restrictions will be removed in the future.} \subsection{Module Contents} - The \module{csv} module defines the following functions: \begin{funcdesc}{reader}{csvfile\optional{, @@ -112,8 +113,8 @@ Return the names of all registered dialects. The \module{csv} module defines the following classes: \begin{classdesc}{DictReader}{csvfile, fieldnames\optional{, - restkey=\code{None}\optional{, - restval=\code{None}\optional{, + restkey=\constant{None}\optional{, + restval=\constant{None}\optional{, dialect=\code{'excel'}\optional{, fmtparam}}}}} Create an object which operates like a regular reader but maps the @@ -145,52 +146,31 @@ to \code{'raise'} a \exception{ValueError} is raised. If it is set to parameters are interpreted as for regular writers. \end{classdesc} - \begin{classdesc*}{Dialect}{} The \class{Dialect} class is a container class relied on primarily for its attributes, which are used to define the parameters for a specific -\class{reader} or \class{writer} instance. Dialect objects support the -following data attributes: - -\begin{memberdesc}[string]{delimiter} -A one-character string used to separate fields. It defaults to \code{","}. -\end{memberdesc} - -\begin{memberdesc}[boolean]{doublequote} -Controls how instances of \var{quotechar} appearing inside a field should be -themselves be quoted. When \constant{True}, the character is doubledd. -When \constant{False}, the \var{escapechar} must be a one-character string -which is used as a prefix to the \var{quotechar}. It defaults to -\constant{True}. -\end{memberdesc} - -\begin{memberdesc}{escapechar} -A one-character string used to escape the \var{delimiter} if \var{quoting} -is set to \constant{QUOTE_NONE}. It defaults to \constant{None}. -\end{memberdesc} +\class{reader} or \class{writer} instance. +\end{classdesc*} -\begin{memberdesc}[string]{lineterminator} -The string used to terminate lines in the CSV file. It defaults to -\code{"\e r\e n"}. -\end{memberdesc} +\begin{classdesc}{Sniffer}{\optional{sample=16384}} +The \class{Sniffer} class is used to deduce the format of a CSV file. The +optional \var{sample} argument to the constructor specifies the number of +bytes to use when determining Dialect parameters. +\end{classdesc} -\begin{memberdesc}[string]{quotechar} -A one-character string used to quote elements containing the \var{delimiter} -or which start with the \var{quotechar}. It defaults to \code{'"'}. -\end{memberdesc} +The \class{Sniffer} class provides a single method: -\begin{memberdesc}[integer]{quoting} -Controls when quotes should be generated by the writer. It can take on any -of the \code{QUOTE_*} constants defined below and defaults to -\constant{QUOTE_MINIMAL}. -\end{memberdesc} +\begin{methoddesc}{sniff}{fileobj} +Analyze the next chunk of \var{fileobj} and return a \class{Dialect} subclass +reflecting the parameters found. +\end{methoddesc} -\begin{memberdesc}[boolean]{skipinitialspace} -When \constant{True}, whitespace immediately following the \var{delimiter} -is ignored. The default is \constant{False}. -\end{memberdesc} +\begin{methoddesc}{has_header}{sample} +Analyze the sample text (presumed to be in CSV format) and return +\constant{True} if the first row appears to be a series of column +headers. +\end{methoddesc} -\end{classdesc*} The \module{csv} module defines the following constants: @@ -223,7 +203,7 @@ Raised by any of the functions when an error is detected. \end{excdesc} -\subsection{Dialects and Formatting Parameters\label{fmt-params}} +\subsection{Dialects and Formatting Parameters\label{csv-fmt-params}} To make it easier to specify the format of input and output records, specific formatting parameters are grouped together into dialects. A @@ -235,13 +215,53 @@ instead of, the \var{dialect} parameter, the programmer can also specify individual formatting parameters, which have the same names as the attributes defined above for the \class{Dialect} class. +Dialects support the following attributes: + +\begin{memberdesc}[Dialect]{delimiter} +A one-character string used to separate fields. It defaults to \code{','}. +\end{memberdesc} + +\begin{memberdesc}[Dialect]{doublequote} +Controls how instances of \var{quotechar} appearing inside a field should be +themselves be quoted. When \constant{True}, the character is doubledd. +When \constant{False}, the \var{escapechar} must be a one-character string +which is used as a prefix to the \var{quotechar}. It defaults to +\constant{True}. +\end{memberdesc} + +\begin{memberdesc}[Dialect]{escapechar} +A one-character string used to escape the \var{delimiter} if \var{quoting} +is set to \constant{QUOTE_NONE}. It defaults to \constant{None}. +\end{memberdesc} + +\begin{memberdesc}[Dialect]{lineterminator} +The string used to terminate lines in the CSV file. It defaults to +\code{'\e r\e n'}. +\end{memberdesc} + +\begin{memberdesc}[Dialect]{quotechar} +A one-character string used to quote elements containing the \var{delimiter} +or which start with the \var{quotechar}. It defaults to \code{'"'}. +\end{memberdesc} + +\begin{memberdesc}[Dialect]{quoting} +Controls when quotes should be generated by the writer. It can take on any +of the \constant{QUOTE_*} constants defined below and defaults to +\constant{QUOTE_MINIMAL}. +\end{memberdesc} + +\begin{memberdesc}[Dialect]{skipinitialspace} +When \constant{True}, whitespace immediately following the \var{delimiter} +is ignored. The default is \constant{False}. +\end{memberdesc} + \subsection{Reader Objects} -\class{DictReader} and \var{reader} objects have the following public -methods: +Reader objects (\class{DictReader} instances and objects returned by +the \function{reader()}function) have the following public methods: -\begin{methoddesc}{next}{} +\begin{methoddesc}[csv reader]{next}{} Return the next row of the reader's iterable object as a list, parsed according to the current dialect. \end{methoddesc} @@ -249,51 +269,36 @@ according to the current dialect. \subsection{Writer Objects} -\class{DictWriter} and \var{writer} objects have the following public -methods: +Writer objects (\class{DictWriter} instances and objects returned by +the \function{writer()} function) have the following public methods: -\begin{methoddesc}{writerow}{row} +\begin{methoddesc}[csv writer]{writerow}{row} Write the \var{row} parameter to the writer's file object, formatted according to the current dialect. \end{methoddesc} -\begin{methoddesc}{writerows}{rows} +\begin{methoddesc}[csv writer]{writerows}{rows} Write all the \var{rows} parameters to the writer's file object, formatted according to the current dialect. \end{methoddesc} -\begin{classdesc}{Sniffer}{} - -The \class{Sniffer} class is used to deduce the format of a CSV file. - -\begin{methoddesc}{sniff}{sample} -Analyze the sample text (presumed to be in CSV format) and return a -{}\class{Dialect} class reflecting the parameters found. -\end{methoddesc} - -\begin{methoddesc}{has_header}{sample} -Analyze the sample text (presumed to be in CSV format) and return -{}\code{True} if the first row appears to be a series of column headers. -\end{methoddesc} -\end{classdesc} - \subsection{Examples} The ``Hello, world'' of csv reading is \begin{verbatim} - import csv - reader = csv.reader(file("some.csv")) - for row in reader: - print row +import csv +reader = csv.reader(file("some.csv")) +for row in reader: + print row \end{verbatim} The corresponding simplest possible writing example is \begin{verbatim} - import csv - writer = csv.writer(file("some.csv", "w")) - for row in someiterable: - writer.writerow(row) +import csv +writer = csv.writer(file("some.csv", "w")) +for row in someiterable: + writer.writerow(row) \end{verbatim} |