Back to module index
Go to module by name
csv
CSV parsing and writing.
This module provides classes that assist in the reading and writing
of Comma Separated Value (CSV) files, and implements the interface
described by PEP 305. Although many CSV files are simple to parse,
the format is not formally defined by a stable specification and
is subtle enough that parsing lines of a CSV file with something
like line.split(",") is bound to fail. The module supports three
basic APIs: reading, writing, and registration of dialects.
DIALECT REGISTRATION:
Readers and writers support a dialect argument, which is a convenient
handle on a group of settings. When the dialect argument is a string,
it identifies one of the dialects previously registered with the module.
If it is a class or instance, the attributes of the argument are used as
the settings for the reader or writer:
class excel:
delimiter = ','
quotechar = '"'
escapechar = None
doublequote = True
skipinitialspace = False
lineterminator = '\r\n'
quoting = QUOTE_MINIMAL
SETTINGS:
* quotechar - specifies a one-character string to use as the
quoting character. It defaults to '"'.
* delimiter - specifies a one-character string to use as the
field separator. It defaults to ','.
* 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.
* lineterminator - specifies the character sequence which should
terminate rows.
* quoting - controls when quotes should be generated by the writer.
It can take on any of the following module constants:
csv.QUOTE_MINIMAL means only when required, for example, when a
field contains either the quotechar or the delimiter
csv.QUOTE_ALL means that quotes are always placed around fields.
csv.QUOTE_NONNUMERIC means that quotes are always placed around
fields which do not parse as integers or floating point
numbers.
csv.QUOTE_NONE means that quotes are never placed around fields.
* escapechar - specifies a one-character string used to escape
the delimiter when quoting is set to QUOTE_NONE.
* doublequote - controls the handling of quotes inside fields. When
True, two consecutive quotes are interpreted as one during read,
and when writing, each quote character embedded in the data is
written as two quotes
Classes
Dialect
Describe a CSV dialect.
This must be subclassed (see csv.excel). Valid attributes are:
delimiter, quotechar, escapechar, doublequote, skipinitialspace,
lineterminator, quoting.
delimiter = None
doublequote = None
escapechar = None
lineterminator = None
quotechar = None
quoting = None
skipinitialspace = None
DictReader
fieldnames = <property object at 0x7ff3602b89a0>
DictWriter
writeheader(self)
writerow(self, rowdict)
writerows(self, rowdicts)
Error
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.
args = <attribute 'args' of 'BaseException' objects>
Sniffer
"Sniffs" the format of a CSV file (i.e. delimiter, quotechar)
Returns a Dialect object.
has_header(self, sample)
sniff(self, sample, delimiters=None)
Returns a dialect (or None) corresponding to the sample
StringIO
Text I/O implementation using an in-memory buffer.
The initial_value argument sets the value of object. The newline
argument is like the one of TextIOWrapper's constructor.
close(self, /)
Close the IO object.
Attempting any further operation after the object is closed
will raise a ValueError.
This method has no effect if the file is already closed.
detach(...)
Separate the underlying buffer from the TextIOBase and return it.
After the underlying buffer has been detached, the TextIO is in an
unusable state.
fileno(self, /)
Returns underlying file descriptor if one exists.
OSError is raised if the IO object does not use a file descriptor.
flush(self, /)
Flush write buffers, if applicable.
This is not implemented for read-only and non-blocking streams.
getvalue(self, /)
Retrieve the entire contents of the object.
isatty(self, /)
Return whether this is an 'interactive' stream.
Return False if it can't be determined.
read(self, size=-1, /)
Read at most size characters, returned as a string.
If the argument is negative or omitted, read until EOF
is reached. Return an empty string at EOF.
readable(self, /)
Returns True if the IO object can be read.
readline(self, size=-1, /)
Read until newline or EOF.
Returns an empty string if EOF is hit immediately.
readlines(self, hint=-1, /)
Return a list of lines from the stream.
hint can be specified to control the number of lines read: no more
lines will be read if the total size (in bytes/characters) of all
lines so far exceeds hint.
seek(self, pos, whence=0, /)
Change stream position.
Seek to character offset pos relative to position indicated by whence:
0 Start of stream (the default). pos should be >= 0;
1 Current position - pos must be 0;
2 End of stream - pos must be 0.
Returns the new absolute position.
seekable(self, /)
Returns True if the IO object can be seeked.
tell(self, /)
Tell the current file position.
truncate(self, pos=None, /)
Truncate size to pos.
The pos argument defaults to the current file position, as
returned by tell(). The current file position is unchanged.
Returns the new absolute position.
writable(self, /)
Returns True if the IO object can be written.
write(self, s, /)
Write string to file.
Returns the number of characters written, which is always equal to
the length of the string.
writelines(self, lines, /)
Write a list of lines to stream.
Line separators are not added, so it is usual for each of the
lines provided to have a line separator at the end.
closed = <attribute 'closed' of '_io.StringIO' objects>
encoding = <attribute 'encoding' of '_io._TextIOBase' objects>
Encoding of the text stream.
Subclasses should override.
errors = <attribute 'errors' of '_io._TextIOBase' objects>
The error setting of the decoder or encoder.
Subclasses should override.
line_buffering = <attribute 'line_buffering' of '_io.StringIO' objects>
newlines = <attribute 'newlines' of '_io.StringIO' objects>
excel
Describe the usual properties of Excel-generated CSV files.
delimiter = ','
doublequote = True
escapechar = None
lineterminator = '\r\n'
quotechar = '"'
quoting = 0
skipinitialspace = False
excel_tab
Describe the usual properties of Excel-generated TAB-delimited files.
delimiter = '\t'
doublequote = True
escapechar = None
lineterminator = '\r\n'
quotechar = '"'
quoting = 0
skipinitialspace = False
unix_dialect
Describe the usual properties of Unix-generated CSV files.
delimiter = ','
doublequote = True
escapechar = None
lineterminator = '\n'
quotechar = '"'
quoting = 1
skipinitialspace = False
Functions
field_size_limit
field_size_limit(...)
Sets an upper limit on parsed fields.
csv.field_size_limit([limit])
Returns old limit. If limit is not given, no new limit is set and
the old limit is returned
get_dialect
get_dialect(...)
Return the dialect instance associated with name.
dialect = csv.get_dialect(name)
list_dialects
list_dialects(...)
Return a list of all know dialect names.
names = csv.list_dialects()
reader
reader(...)
csv_reader = reader(iterable [, dialect='excel']
[optional keyword args])
for row in csv_reader:
process(row)
The "iterable" argument can be any object that returns a line
of input for each iteration, such as a file object or a list. The
optional "dialect" parameter is discussed below. The function
also accepts optional keyword arguments which override settings
provided by the dialect.
The returned object is an iterator. Each iteration returns a row
of the CSV file (which can span multiple input lines).
register_dialect
register_dialect(...)
Create a mapping from a string name to a dialect class.
dialect = csv.register_dialect(name[, dialect[, **fmtparams]])
unregister_dialect
unregister_dialect(...)
Delete the name/dialect mapping associated with a string name.
csv.unregister_dialect(name)
writer
writer(...)
csv_writer = csv.writer(fileobj [, dialect='excel']
[optional keyword args])
for row in sequence:
csv_writer.writerow(row)
[or]
csv_writer = csv.writer(fileobj [, dialect='excel']
[optional keyword args])
csv_writer.writerows(rows)
The "fileobj" argument can be any object that supports the file API.
Other members
QUOTE_ALL = 1
QUOTE_MINIMAL = 0
QUOTE_NONE = 3
QUOTE_NONNUMERIC = 2
Modules
re