[Python-checkins] python/nondist/sandbox/csv libcsv.tex,1.4,1.5
montanaro@users.sourceforge.net
montanaro@users.sourceforge.net
Mon, 10 Feb 2003 14:43:15 -0800
Update of /cvsroot/python/python/nondist/sandbox/csv
In directory sc8-pr-cvs1:/tmp/cvs-serv31575
Modified Files:
libcsv.tex
Log Message:
* correct a number of Latex errors
* add blurbs about the DictReader and DictWriter classes
Index: libcsv.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/csv/libcsv.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** libcsv.tex 6 Feb 2003 04:50:10 -0000 1.4
--- libcsv.tex 10 Feb 2003 22:43:12 -0000 1.5
***************
*** 16,44 ****
many applications which read and write it. The lack of a standard means
there can be subtle differences in the data produced and consumed by
! different applications. These differences can be maddeningly subtle.
! The \module{csv} allows programmers to say, ``write this data in the format
! preferred by Excel (tm),'' without knowing all the fiddly little details of
! the CSV format used by Excel. Programmers can also easily define their own
! CSV formats.
\subsection{Relationship to other Python modules}
! The csv module reads and writes sequences. It can also read data and return
! the rows as dicts. Sequence types other than lists and tuples
! (e.g. \code{array} objects) can be written. To make it as easy as possible
! to interface with modules which implement the DB API, the value None is
! written as the empty string. While this isn't a reversible transformation,
! it makes it easier to dump SQL NULL data values to CSV files without
! preprocessing the data returned from a {}\code{cursor.fetch*()} call.
\subsection{Module Contents}
! The \module{csv} module defines the following classes.
! \begin{classdesc}{reader}{iterable\optional{, dialect="excel"}
\optional{, fmtparam}}
! Create a reader object which will iterate over lines in the given
{}\var{csvfile}. An optional \var{dialect} parameter can be given which is
used to define a set of parameters specific to a particular CSV dialect.
--- 16,46 ----
many applications which read and write it. The lack of a standard means
there can be subtle differences in the data produced and consumed by
! different applications. These differences can it annoying to process CSV
! files from multiple sources.
! The \module{csv} module allows programmers to say, ``write this data in the
! format preferred by Excel (tm),'' without knowing all the fiddly little
! details of the CSV format used by Excel. Programmers can also easily define
! their own CSV formats.
\subsection{Relationship to other Python modules}
! The csv module reads and writes sequences. It can also read and write data
! in dictionary form using the \class{DictReader} and \class{DictWriter}
! classes. Sequence types other than lists and tuples (e.g. \code{array}
! objects) can be written. To make it as easy as possible to interface with
! modules which implement the DB API, the value None is written as the empty
! string. While this isn't a reversible transformation, it makes it easier to
! dump SQL NULL data values to CSV files without preprocessing the data
! returned from a {}\code{cursor.fetch*()} call.
\subsection{Module Contents}
! The \module{csv} module defines the following functions.
! \begin{funcdesc}{reader}{iterable\optional{, dialect="excel"}
\optional{, fmtparam}}
! Return a reader object which will iterate over lines in the given
{}\var{csvfile}. An optional \var{dialect} parameter can be given which is
used to define a set of parameters specific to a particular CSV dialect.
***************
*** 48,71 ****
{}\ref{fmt-params}, ``Dialects and Formatting Parameters'' for details of
these parameters.
! \end{classdesc}
! \begin{classdesc}{writer}{fileobj\optional{, dialect="excel"}
! \optional{, fieldnames}
\optional{, fmtparam}}
! Create a writer object responsible for converting the user's data into
delimited strings on the given file-like object. An optional \var{dialect}
parameter can be given which is used to define a set of parameters specific
! to a particular CSV dialect. If a sequence of strings is given as the
! optional \var{fieldnames} parameter, the writer will use them to properly
! order mapping objects passed to the object's \method{write} methods. The
! other optional \var{fmtparam} keyword arguments can be given to override
! individual formatting parameters in the current dialect. For more
! information about the dialect and formatting parameters, see section
! {}\ref{fmt-params}, ``Dialects and Formatting Parameters'' for details of
! these parameters.
! \end{classdesc}
!
! The \module{csv} module defines the following functions.
\begin{funcdesc}{register_dialect}{name, dialect}
--- 50,67 ----
{}\ref{fmt-params}, ``Dialects and Formatting Parameters'' for details of
these parameters.
! \end{funcdesc}
! \begin{funcdesc}{writer}{fileobj\optional{, dialect="excel"}
\optional{, fmtparam}}
! Return a writer object responsible for converting the user's data into
delimited strings on the given file-like object. An optional \var{dialect}
parameter can be given which is used to define a set of parameters specific
! to a particular CSV dialect. The other optional \var{fmtparam} keyword
! arguments can be given to override individual formatting parameters in the
! current dialect. For more information about the dialect and formatting
! parameters, see section {}\ref{fmt-params}, ``Dialects and Formatting
! Parameters'' for details of these parameters.
! \end{funcdesc}
\begin{funcdesc}{register_dialect}{name, dialect}
***************
*** 83,86 ****
--- 79,118 ----
\end{funcdesc}
+ The \module{csv} module defines the following classes.
+
+ \begin{classdesc}{DictReader}{fileobj, fieldnames
+ \optional{, restkey=None}
+ \optional{, restval=None}
+ \optional{, dialect="excel"}
+ \optional{, fmtparam}}
+ Create an object which operates like a regular reader but maps the
+ information read into a dict whose keys are given by the {}\var{fieldnames}
+ parameter. If the row read has fewer fields than the fieldnames sequence,
+ the value of \var{restval} will be used as the default value. If the row
+ read has more fields than the fieldnames sequence, the remaining data is
+ added as a sequence keyed by the value of \var{restkey}. If the row read
+ has fewer fields than the fieldnames sequence, the remaining keys take the
+ value of the optiona \var{restval} parameter. All other parameters are
+ interpreted as for regular readers.
+ \end{classdesc}
+
+ \begin{classdesc}{DictWriter}{fileobj, fieldnames
+ \optional{, restval=""}
+ \optional{, extrasaction="raise"}
+ \optional{, dialect="excel"}
+ \optional{, fmtparam}}
+ Create an object which operates like a regular writer but maps dictionaries
+ onto output rows. The \var{fieldnames} parameter identifies the order in
+ which values in the dictionary passed to the \method{writerow} method are
+ written to the \var{fileobj}. The optional \var{restval} parameter
+ specifies the value to be written if the dictionary is missing a key in
+ {}\var{fieldnames}. If the dictionary passed to the \method{writerow}
+ method contains a key not found in {}\var{fieldnames}, the optional
+ {}\var{extrasaction} parameter indicates what action to take. If it is set
+ to \code{"raise"} a {}\exception{ValueError} is raised. If it is set to
+ {}\code{"ignore"}, extra values in the dictionary are ignored. All other
+ parameters are interpreted as for regular writers.
+ \end{classdesc}
+
The \module{csv} module defines the following exception.
***************
*** 131,169 ****
\begin{description}
! \item{quotechar}{specifies a one-character string to use as the quoting
character. It defaults to \code{"}.}
! \item{delimiter}{specifies a one-character string to use as the field
separator. It defaults to \code{,}.}
! \item{escapechar}{specifies a one-character string used to escape the
delimiter when quotechar is set to \var{None}.}
! \item{skipinitialspace}{specifies how to interpret whitespace which
immediately follows a delimiter. It defaults to False, which means
that whitespace immediately following a delimiter is part of the
following field.}
! \item{lineterminator}{specifies the character sequence which should
terminate rows.}
! \item{quoting}{controls when quotes should be generated by the
! writer. It can take on any of the following module constants:}
!
! \begin{description}
! \item{QUOTE_MINIMAL}{means only when required, for example, when a
! field contains either the quotechar or the delimiter.}
!
! \item{QUOTE_ALL}{means that quotes are always placed around all fields.}
!
! \item{QUOTE_NONNUMERIC}{means that quotes are always placed around
! fields which contain characters other than [+-0-9.].}
!
! \item{QUOTE_NONE}{means that quotes are never placed around fields.
! Instead, the \var{escapechar} is used to escape any instances of the
! \var{delimiter} which occurs in the data.}
! \end{description}
! \item{doublequote}{controls the handling of quotes inside fields. When
\var{True}, two consecutive quotes are interpreted as one during read, and
when writing, each quote is written as two quotes.}
--- 163,187 ----
\begin{description}
! \item[quotechar]{specifies a one-character string to use as the quoting
character. It defaults to \code{"}.}
! \item[delimiter]{specifies a one-character string to use as the field
separator. It defaults to \code{,}.}
! \item[escapechar]{specifies a one-character string used to escape the
delimiter when quotechar is set to \var{None}.}
! \item[skipinitialspace]{specifies how to interpret whitespace which
immediately follows a delimiter. It defaults to False, which means
that whitespace immediately following a delimiter is part of the
following field.}
! \item[lineterminator]{specifies the character sequence which should
terminate rows.}
! \item[quoting]{controls when quotes should be generated by the
! writer. It can take on any of the \code{QUOTE_*} constants defined above.}
! \item[doublequote]{controls the handling of quotes inside fields. When
\var{True}, two consecutive quotes are interpreted as one during read, and
when writing, each quote is written as two quotes.}
***************
*** 173,177 ****
\subsection{Reader Objects}
! \class{Reader} objects have the following public methods.
\begin{methoddesc}{next}{}
--- 191,196 ----
\subsection{Reader Objects}
! \class{DictReader} and \var{reader} objects have the following public
! methods.
\begin{methoddesc}{next}{}
***************
*** 183,187 ****
\subsection{Writer Objects}
! \class{Writer} objects have the following public methods.
\begin{methoddesc}{writerow}{row}
--- 202,207 ----
\subsection{Writer Objects}
! \class{DictWriter} and \var{writer} objects have the following public
! methods.
\begin{methoddesc}{writerow}{row}
***************
*** 198,202 ****
\subsection{Examples}
! The ``hello world'' of csv reading is
\begin{verbatim}
--- 218,222 ----
\subsection{Examples}
! The \code{"hello world"} of csv reading is
\begin{verbatim}
***************
*** 213,220 ****
writer.writerow(row)
\end{verbatim}
-
- Both the \class{reader} and \class{writer} classes accept a number of
- optional arguments which are used to tailor them to the dialect of the input
- or output file.
\begin{seealso}
--- 233,236 ----