[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 ----