[Python-checkins] python/nondist/peps pep-0305.txt,1.3,1.4

[montanaro@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/peps
In directory sc8-pr-cvs1:/tmp/cvs-serv27509

Modified Files:
	pep-0305.txt 
Log Message:
started reorganizing the information about low-level formatting parameters.
Define dialects in their own subsection.  Define low-level parameters in a
separate subsection.  Define set_dialect() and get_dialect() module-level
functions. 

More to be done, but I have to get to work... ;-)



Index: pep-0305.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0305.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** pep-0305.txt	29 Jan 2003 13:36:59 -0000	1.3
--- pep-0305.txt	29 Jan 2003 14:09:45 -0000	1.4
***************
*** 62,76 ****
  
  The module supports two basic APIs, one for reading and one for
! writing.  The reading interface is::
  
!     reader(fileobj [, dialect='excel2000']
!                    [, quotechar='"']
!                    [, delimiter=',']
!                    [, skipinitialspace=False])
  
  A reader object is an iterable which takes a file-like object opened
! for reading as the sole required parameter.  It also accepts four
! optional parameters (discussed below).  Readers are typically used as
! follows::
  
      csvreader = csv.reader(file("some.csv"))
--- 62,74 ----
  
  The module supports two basic APIs, one for reading and one for
! writing.  The basic reading interface is::
  
!     reader(fileobj [, dialect='excel2000'])
  
  A reader object is an iterable which takes a file-like object opened
! for reading as the sole required parameter.  The optional dialect
! parameter is discussed below.  It also accepts several keyword
! parameters which define specific format settings (see the section
! "Formatting Parameters").  Readers are typically used as follows::
  
      csvreader = csv.reader(file("some.csv"))
***************
*** 80,91 ****
  The writing interface is similar::
  
!     writer(fileobj [, dialect='excel2000']
!                    [, quotechar='"']
!                    [, delimiter=',']
!                    [, skipinitialspace=False])
  
  A writer object is a wrapper around a file-like object opened for
! writing.  It accepts the same four optional parameters as the reader
! constructor.  Writers are typically used as follows::
  
      csvwriter = csv.writer(file("some.csv", "w"))
--- 78,91 ----
  The writing interface is similar::
  
!     writer(fileobj [, dialect='excel2000'], [, fieldnames=list])
  
  A writer object is a wrapper around a file-like object opened for
! writing.  It accepts the same keyword parameters as the reader
! constructor.  In addition, it accepts an optional fieldnames
! argument.  This is a list which defines the order of fields in the
! output file.  It allows the write() method to accept mapping objects
! as well as sequence objects.
! 
! Writers are typically used as follows::
  
      csvwriter = csv.writer(file("some.csv", "w"))
***************
*** 93,109 ****
          csvwriter.write(row)
  
  
! Optional Parameters
! -------------------
  
- Both the reader and writer constructors take four optional keyword
- parameters:
  
! - dialect is an easy way of specifying a complete set of format
!   constraints for a reader or writer.  Most people will know what
!   application generated a CSV file or what application will process
!   the CSV file they are generating, but not the precise settings
!   necessary.  The only dialect defined initially is "excel2000".  The
!   dialect parameter is interpreted in a case-insensitive manner.
  
  - quotechar specifies a one-character string to use as the quoting
--- 93,132 ----
          csvwriter.write(row)
  
+ To generate a set of field names as the first row of the CSV file, the
+ programmer must explicitly write it, e.g.::
  
!     csvwriter = csv.writer(file("some.csv", "w"), fieldnames=names)
!     csvwriter.write(names)
!     for row in someiterable:
!         csvwriter.write(row)
  
  
! Dialects
! --------
! 
! Readers and writers support a dialect argument which is just a
! convenient (string) handle on a group of lower level parameters.
! Dialects will generally be named after applications or organizations
! which define specific sets of format constraints.  The initial dialect
! is "excel2000", which describes the format constraints of Excel 2000's
! CSV format.  Another possible dialect (used here only as an example)
! might be "gnumeric".
! 
! Two functions are defined in the API to set and retrieve dialects::
! 
!     set_dialect(dialect, pdict)
!     pdict = get_dialect(dialect)
! 
! The pdict parameter is a dictionary whose keys are the names the
! formatting parameters defined in the next section.
! 
! 
! Formatting Parameters
! ---------------------
! 
! Both the reader and writer constructors take several specific
! formatting parameters, specified as keyword parameters.  The
! parameters are also the keys for the input and output mapping objects
! for the set_dialect() and get_dialect() module functions.
  
  - quotechar specifies a one-character string to use as the quoting
***************
*** 117,120 ****
--- 140,148 ----
    that whitespace immediate following a delimiter is part of the
    following field.
+ 
+ - lineterminator specifies the character sequence which should
+   terminate rows.
+ 
+ ... XXX More to come XXX ...
  
  When processing a dialect setting and one or more of the other