organizational and markup cleansing

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}