[Python-checkins] python/nondist/sandbox/csv libcsv.tex,1.5,1.6
montanaro@users.sourceforge.net
montanaro@users.sourceforge.net
Wed, 12 Feb 2003 09:37:54 -0800
Update of /cvsroot/python/python/nondist/sandbox/csv
In directory sc8-pr-cvs1:/tmp/cvs-serv26079
Modified Files:
libcsv.tex
Log Message:
rearranged the introduction and made lots of fiddly little changes to the
main text. In particular, describe Dialect class and its attributes, then
dumped the individual descriptions of the various parameters.
Index: libcsv.tex
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/csv/libcsv.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** libcsv.tex 10 Feb 2003 22:43:12 -0000 1.5
--- libcsv.tex 12 Feb 2003 17:37:49 -0000 1.6
***************
*** 7,41 ****
\indexii{data}{tabular}
- The \module{csv} module implements classes to read and write tabular data.
The so-called CSV (Comma Separated Values) format is the most common import
! and export format for spreadsheets and databases. While the delimiters and
! quoting characters vary, the overall format is similar enough that it is
! possible to write a single module which can manipulate such data.
!
! There is no ``CSV standard'', so the format is operationally defined by the
! 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.
--- 7,36 ----
\indexii{data}{tabular}
The so-called CSV (Comma Separated Values) format is the most common import
! and export format for spreadsheets and databases. There is no ``CSV
! standard'', so the format is operationally defined by the many applications
! which read and write it. The lack of a standard means that subtle
! differences often exist in the data produced and consumed by different
! applications. These differences can make it annoying to process CSV files
! from multiple sources. Still, while the delimiters and quoting characters
! vary, the overall format is similar enough that it is possible to write a
! single module which can efficiently manipulate such data, hiding the details
! of reading and writing the data from the programmer.
+ The \module{csv} module implements classes to read and write tabular data in
+ CSV format. It allows programmers to say, ``write this data in the format
+ preferred by Excel,'' or ``read data from this file which was generated by
+ Excel,'' without knowing the precise details of the CSV format used by
+ Excel. Programmers can also describe the CSV formats understood by other
+ applications or define their own special-purpose CSV formats.
! 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.
\subsection{Module Contents}
+
The \module{csv} module defines the following functions.
***************
*** 49,53 ****
information about the dialect and formatting parameters, see section
{}\ref{fmt-params}, ``Dialects and Formatting Parameters'' for details of
! these parameters.
\end{funcdesc}
--- 44,48 ----
information about the dialect and formatting parameters, see section
{}\ref{fmt-params}, ``Dialects and Formatting Parameters'' for details of
! these parameters. All data read are returned as strings.
\end{funcdesc}
***************
*** 62,66 ****
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}
--- 57,67 ----
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. To make it as easy as
! possible to interface with modules which implement the DB API, the value
! {}\constant{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. All other non-string data are stringified
! with \function{str} before being written.
\end{funcdesc}
***************
*** 70,75 ****
\end{funcdesc}
\begin{funcdesc}{get_dialect}{name}
! Return the dialect associated with \var{name}. A \exception{KeyError} is
raised if \var{name} is not a registered dialect name.
\end{funcdesc}
--- 71,82 ----
\end{funcdesc}
+ \begin{funcdesc}{unregister_dialect}{name}
+ Delete the dialect associated with \var{name} from the dialect registry. An
+ \exception{Error} is raised if \var{name} is not a registered dialect
+ name.
+ \end{funcdesc}
+
\begin{funcdesc}{get_dialect}{name}
! Return the dialect associated with \var{name}. An \exception{Error} is
raised if \var{name} is not a registered dialect name.
\end{funcdesc}
***************
*** 79,82 ****
--- 86,90 ----
\end{funcdesc}
+
The \module{csv} module defines the following classes.
***************
*** 97,100 ****
--- 105,109 ----
\end{classdesc}
+
\begin{classdesc}{DictWriter}{fileobj, fieldnames
\optional{, restval=""}
***************
*** 115,123 ****
\end{classdesc}
- The \module{csv} module defines the following exception.
! \begin{excdesc}{Error}
! Raised by any of the functions when an error is detected.
! \end{excdesc}
The \module{csv} module defines the following constants.
--- 124,172 ----
\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.
! \end{classdesc}
!
! \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}
!
The \module{csv} module defines the following constants.
***************
*** 139,148 ****
Instructs \class{writer} objects to never quote fields. When the current
{}\var{delimiter} occurs in output data it is preceded by the current
! {}\var{escapechar} character. When QUOTE_NONE is in effect, it is an error
! not to have a single-character \var{escapechar} defined, even if no data to
! be written contains the \var{delimiter} character.
\end{datadesc}
\subsection{Dialects and Formatting Parameters\label{fmt-params}}
--- 188,204 ----
Instructs \class{writer} objects to never quote fields. When the current
{}\var{delimiter} occurs in output data it is preceded by the current
! {}\var{escapechar} character. When \constant{QUOTE_NONE} is in effect, it
! is an error not to have a single-character \var{escapechar} defined, even if
! no data to be written contains the \var{delimiter} character.
\end{datadesc}
+ The \module{csv} module defines the following exception.
+
+ \begin{excdesc}{Error}
+ Raised by any of the functions when an error is detected.
+ \end{excdesc}
+
+
\subsection{Dialects and Formatting Parameters\label{fmt-params}}
***************
*** 154,190 ****
of the \class{Dialect} class as the dialect parameter. In addition to, or
instead of, the \var{dialect} parameter, the programmer can also specify
! individual formatting parameters, described in the following section.
!
!
! \subsubsection{Formatting Parameters}
!
! Both the \class{reader} and \class{writer} classes take several specific
! formatting parameters, specified as keyword parameters.
!
! \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.}
! \end{description}
--- 210,215 ----
of the \class{Dialect} class as the dialect parameter. In addition to, or
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.