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:
parent
e12319dd5d
commit
4bd57ea00d
76
pep-0305.txt
76
pep-0305.txt
|
@ -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,
|
||||
|
|
Loading…
Reference in New Issue