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... ;-)
This commit is contained in:
Skip Montanaro 2003-01-29 14:09:45 +00:00
parent e12319dd5d
commit 4bd57ea00d
1 changed files with 52 additions and 24 deletions

View File

@ -61,17 +61,15 @@ Module Interface
================
The module supports two basic APIs, one for reading and one for
writing. The reading interface is::
writing. The basic reading interface is::
reader(fileobj [, dialect='excel2000']
[, quotechar='"']
[, delimiter=',']
[, skipinitialspace=False])
reader(fileobj [, dialect='excel2000'])
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::
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"))
for row in csvreader:
@ -79,32 +77,57 @@ follows::
The writing interface is similar::
writer(fileobj [, dialect='excel2000']
[, quotechar='"']
[, delimiter=',']
[, skipinitialspace=False])
writer(fileobj [, dialect='excel2000'], [, fieldnames=list])
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::
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"))
for row in someiterable:
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.::
Optional Parameters
-------------------
csvwriter = csv.writer(file("some.csv", "w"), fieldnames=names)
csvwriter.write(names)
for row in someiterable:
csvwriter.write(row)
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.
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
character. It defaults to '"'.
@ -117,6 +140,11 @@ parameters:
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
optional parameters, the dialect parameter is processed first, then
the others are processed. This makes it easy to choose a dialect,