mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-01 18:51:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 21

organizational and markup cleansing

Browse source
This commit is contained in:
Fred Drake 2003-04-25 18:02:34 +00:00
parent 9a90e70b32
commit 9635268ea9
1 changed files with 85 additions and 80 deletions
Download patch file Download diff file Expand all files Collapse all files

165
Doc/lib/libcsv.tex
View file

@ -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,53 +146,32 @@ 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}
\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{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}
\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{memberdesc}[boolean]{skipinitialspace}
When \constant{True}, whitespace immediately following the \var{delimiter}
is ignored. The default is \constant{False}.
\end{memberdesc}
\class{reader} or \class{writer} instance.
\end{classdesc*}
\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}
The \class{Sniffer} class provides a single method:
\begin{methoddesc}{sniff}{fileobj}
Analyze the next chunk of \var{fileobj} and return a \class{Dialect} subclass
reflecting the parameters found.
\end{methoddesc}
\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}
The \module{csv} module defines the following constants:
\begin{datadesc}{QUOTE_ALWAYS}
@ -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}