organizational and markup cleansing
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 @@
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 @@
\subsection{Module Contents}
-
The \module{csv} module defines the following functions:
\begin{funcdesc}{reader}{csvfile\optional{,
@@ -112,8 +113,8 @@
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 @@
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 @@
\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 @@
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 @@
\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}