API Reference¶

High level interface¶

`csv23.open_csv`	Context manager returning a CSV reader/writer (closing the file on exit).
`csv23.open_reader`	Context manager returning a CSV reader (closing the file on exit).
`csv23.open_writer`	Context manager returning a CSV writer (closing the file on exit).
`csv23.iterrows`	Iterator yielding rows from a CSV file (closed on exaustion or error).
`csv23.read_csv`	Iterator yielding rows from a file-like object with CSV data.
`csv23.write_csv`	Write rows into a file-like object using CSV format.

CSV readers and writers¶

`csv23.reader`	CSV reader yielding lists of `unicode()` strings (PY3: `str`).
`csv23.writer`	CSV writer for rows where string values are `unicode()` strings (PY3: `str`).
`csv23.DictReader`	`csv23.reader()` yielding dicts of `unicode()` strings (PY3: `str`).
`csv23.DictWriter`	`csv23.writer()` for dicts where string values are `unicode()` strings (PY3: `str`).
`csv23.NamedTupleReader`	`csv23.reader()` yielding namedtuples of `unicode()` strings (PY3: `str`).
`csv23.NamedTupleWriter`	`csv23.writer()` for namedtuples where string values are `unicode()` strings (PY3: `str`).

open_csv¶

csv23.open_csv(filename, mode='r', encoding='utf-8', dialect='excel', rowtype='list', **fmtparams)¶

Context manager returning a CSV reader/writer (closing the file on exit).

Parameters

filename – File (name) argument for the io.open() call.
mode (str) – 'r' for a csv23.reader(), 'w' for a csv23.writer().
encoding (str) – Name of the encoding used to de/encode the file content.
dialect – CSV dialect argument for the csv23.reader()/csv23.writer().
rowtype (str) – 'list' for a csv23.reader()/csv23.writer(), 'dict' for a csv23.DictReader/csv23.DictWriter, 'namedtuple' for a csv23.NamedTupleReader/csv23.NamedTupleWriter.
**fmtparams – Keyword arguments (formatting parameters) for the csv23.reader()/csv23.writer() (must include fieldnames if mode='w' and rowtype='dict').

Returns

A context manager returning a Python 3 csv.reader()/csv.writer() stand-in when entering.

>>> row = [u'Wonderful Spam', u'Lovely Spam']
>>> with open_csv('spam.csv', 'w') as writer:  
...     writer.writerow(row)
>>> with open_csv('spam.csv') as reader:  
...     assert list(reader) == [row]

Raises: TypeError – With mode='w' and rowtype='dict' but missing fieldnames keyword argument.

Notes

The reader/writer yields/expects string values as unicode() strings (PY3: str).
The underlying opened file object is closed on leaving the with-block.
If encoding=None is given, locale.getpreferredencoding() is used.
Under Python 2, an optimized implementation is used for 8-bit encodings that are ASCII-compatible (e.g. the default 'utf-8').

open_reader/writer¶

csv23.open_reader(filename, encoding='utf-8', dialect='excel', rowtype='list', **fmtparams)¶

Context manager returning a CSV reader (closing the file on exit).

Parameters

filename – File (name) argument for the io.open() call.
encoding (str) – Name of the encoding used to decode the file content.
dialect – Dialect argument for the csv23.reader().
rowtype (str) – 'list' for a csv23.reader(), 'dict' for a csv23.DictReader, 'namedtuple' for a csv23.NamedTupleReader.
**fmtparams – Keyword arguments (formatting parameters) for the csv23.reader().

Returns

A context manager returning a Python 3 csv.reader() stand-in when entering.

>>> with open_reader('spam.csv', encoding='utf-8') as reader:  
...     for row in reader:
...         print(row)
[u'Spam!', u'Spam!', u'Spam!']
[u'Spam!', u'Lovely Spam!', u'Lovely Spam!']
>>> reader.line_num  
2

Notes

The reader yields a list or dict of unicode() strings (PY3: str).
The underlying opened file object is closed on leaving the with-block.
If encoding=None is given, locale.getpreferredencoding() is used.
Under Python 2, an optimized implementation is used for 8-bit encodings that are ASCII-compatible (e.g. the default 'utf-8').

csv23.open_writer(filename, encoding='utf-8', dialect='excel', rowtype='list', **fmtparams)¶

Context manager returning a CSV writer (closing the file on exit).

Parameters

filename – File (name) argument for the io.open() call.
encoding (str) – Name of the encoding used to encode the output lines.
dialect – Dialect argument for the csv23.writer().
rowtype (str) – 'list' for a csv23.writer(), 'dict' for a csv23.DictWriter, 'namedtuple' for a csv23.NamedTupleWriter.
**fmtparams – Keyword arguments (formatting parameters) for the csv23.writer() (must include fieldnames with rowtype='dict').

Returns

A context manager returning a Python 3 csv.writer() stand-in when entering.

>>> with open_writer('spam.csv', encoding='utf-8') as writer:  
...     writer.writerow([u'Spam!', u'Spam!', u'Spam!'])
...     writer.writerow([u'Spam!', u'Lovely Spam!', u'Lovely Spam!'])

Raises: TypeError – With rowtype='dict' but missing fieldnames keyword argument.

Notes

The writer expects string values as unicode() strings (PY3: str).
The underlying opened file object is closed on leaving the with-block.
If encoding=None is given, locale.getpreferredencoding() is used.
Under Python 2, an optimized implementation is used for 8-bit encodings that are ASCII-compatible (e.g. the default 'utf-8').

iterrows¶

csv23.iterrows(filename, encoding='utf-8', dialect='excel', rowtype='list', **fmtparams)¶

Iterator yielding rows from a CSV file (closed on exaustion or error).

Parameters

filename – File (name) argument for the io.open() call.
encoding (str) – Name of the encoding used to decode the file content.
dialect – CSV dialect argument for csv23.reader().
rowtype (str) – 'list' for list rows, 'dict' for dict rows, 'namedtuple' for collections.namedtuple() rows.
**fmtparams – Keyword arguments (formatting parameters) for the csv23.reader().

Yields

list, dict, or collections.namedtuple() – The next row from the CSV file.

>>> for row in iterrows('spam.csv', encoding='utf-8'):  
...     print(row)
...     break
[u'Wonderful Spam', u'Lovely Spam']

>>> rows = iterrows('spam.csv', encoding='utf-8')  
>>> next(rows)  
[u'Wonderful Spam', u'Lovely Spam']
>>> rows.close()  

Notes

The rows are list or dict of unicode() strings (PY3: str).
The underlying opened file object is closed automatically, i.e. on exhaustion, in case of an exception, or by garbage collection. To do it manually, call the .close().method of the returned generator object.
If encoding=None is given, locale.getpreferredencoding() is used.
Under Python 2, an optimized implementation is used for 8-bit encodings that are ASCII-compatible (e.g. the default 'utf-8').

read_csv/write_csv¶

csv23.read_csv(file, dialect='excel', encoding='utf-8', as_list=False, autocompress=False)¶

Iterator yielding rows from a file-like object with CSV data.

Parameters

file – Source as readable file-like object or filename/py:os.PathLike.
dialect – CSV dialect argument for the csv23.reader().
encoding (str) – Name of the encoding used to decode the file content.
as_list (bool) – Return a py:list of rows instead of an iterator.
autocompress (bool) – Decompress if file is a path that ends in '.bz2', '.gz', or '.xz'.

Returns

An iterator yielding a py:list of row values for each row.

>>> read_csv(io.BytesIO(b'spam,eggs\r\n'), encoding='ascii', as_list=True)
[['spam', 'eggs']]

Raises: TypeError – If file is a binary buffer or filename/path and encoding is None. Also if file is a text buffer and encoding is not None.
Warns: UserWarning – If file is a path that ends in '.bz2', '.gz', or '.xz' but autocompress=False is given.

Notes

encoding is required if file is binary or a filesystem path.
if file is a text stream, encoding needs to be None.

csv23.write_csv(file, rows, header=None, dialect='excel', encoding='utf-8', autocompress=False)¶

Write rows into a file-like object using CSV format.

Parameters

file – Target as writeable file-like object, or as filename or py:os.Pathlike, or as updateable hash, or None for string output.
rows – CSV values to write as iterable of row value iterables.
header – Iterable of first row values or None for no header.
dialect – Dialect argument for the csv23.writer().
encoding (str) – Name of the encoding used to encode the file content.
autocompress (bool) – Compress if file is a path that ends in '.bz2', '.gz', or '.xz'.

Returns

If file is a filename/path, return it as py:pathlib.Path. If file is a file-like object or a hash return it (without closing). If file is None return the CSV data as str.

>>> write_csv(io.BytesIO(), iter([('spam', 'eggs')]), encoding='ascii').getvalue()
b'spam,eggs\r\n'

Raises: TypeError – If file is a binary buffer or filename/path and encoding is None. Also if file is a text buffer and encoding is not None.
Warns: UserWarning – If file is a path that ends in '.bz2', '.gz', or '.xz' but autocompress=False is given.

Notes

encoding is required if file is binary or a filesystem path.
if file is a text stream, encoding needs to be None.

reader/writer¶

csv23.reader(stream, dialect='excel', encoding=False, **fmtparams)¶

CSV reader yielding lists of unicode() strings (PY3: str).

Parameters

stream – Iterable of text (unicode(), PY3: str) lines. If an encoding is given, iterable of encoded (str, PY3: bytes) lines in the given (8-bit clean) encoding.
dialect – Dialect argument for the underlying csv.reader().
encoding – If not False (default): name of the encoding needed to decode the encoded (str, PY3: bytes) lines from stream.
**fmtparams – Keyword arguments (formatting parameters) for the underlying csv.reader().

Returns

A Python 3 csv.reader() stand-in yielding a list of unicode() strings (PY3: str) for each row.

>>> import io
>>> text = u'Spam!,Spam!,Spam!\r\nSpam!,Lovely Spam!,Lovely Spam!\r\n'
>>> with io.StringIO(text, newline='') as f:
...     for row in reader(f):
...         print(', '.join(row))
Spam!, Spam!, Spam!
Spam!, Lovely Spam!, Lovely Spam!

Raises: NotImplementedError – If encoding is not 8-bit clean.

csv23.writer(stream, dialect='excel', encoding=False, **fmtparams)¶

CSV writer for rows where string values are unicode() strings (PY3: str).

Parameters

stream – File-like object (in binary mode if encoding is given).
dialect – Dialect argument for the underlying csv.writer().
encoding – If not False (default): name of the encoding used to encode the output lines.
**fmtparams – Keyword arguments (formatting parameters) for the underlying csv.writer().

Returns

A Python 3 csv.writer() stand-in taking a list of unicode() strings (PY3: str) for each row.

>>> import io
>>> with io.StringIO(newline='') as f:  
...     w = writer(f)
...     w.writerow([u'Wonderful Spam', u'Lovely Spam'])
...     w.writerow([u'Spam!', u'Spam!', u'Spam!'])
...     f.getvalue()
u'Spam!,Spam!,Spam!\r\nWonderful Spam,Lovely Spam\r\n'

Raises: NotImplementedError – If encoding is not 8-bit clean.

DictReader/Writer¶

class csv23.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', encoding=False, **kwds)¶: csv23.reader() yielding dicts of unicode() strings (PY3: str).

class csv23.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', encoding=False, **kwds)¶: csv23.writer() for dicts where string values are unicode() strings (PY3: str).

NamedTupleReader/Writer¶

class csv23.NamedTupleReader(stream, dialect='excel', rename=False, row_name='Row', encoding=False, **kwargs)¶

csv23.reader() yielding namedtuples of unicode() strings (PY3: str).

Parameters

stream – Iterable of text (unicode(), PY3: str) lines. If an encoding is given, iterable of encoded (str, PY3: bytes) lines in the given (8-bit clean) encoding.
dialect – Dialect argument for the csv23.reader().
rename – rename argument for collections.namedtuple(), or a function that is mapped to the first row to turn it into the field_names of the namedtuple.
row_name – The typename for the row collections.namedtuple().
encoding – If not False (default): name of the encoding needed to decode the encoded (str, PY3: bytes) lines from stream.
**kwargs – Keyword arguments for the csv23.reader().

Raises

NotImplementedError – If encoding is not 8-bit clean.

Notes

Creates a collections.namedtuple() when reading the first row (header).
Uses the first row as field_names. They must be valid Python identifiers (e.g. no hyphen or dot, they cannot be Python keywords like class). They cannot start with an underscore.
rename=True replaces invalid field_names with positional names (_0, _1, etc.).
If rename is callable, it is applied to turn the first row strings into field_names.

>>> import io
>>> text = u'coordinate.x,coordinate.y\r\n11,22\r\n'
>>> with io.StringIO(text, newline='') as f:
...     for row in NamedTupleReader(f, rename=lambda x: x.replace('.', '_')):
...         print('%s %s' % (row.coordinate_x, row.coordinate_y))
11 22

__next__()¶: Return the next row of the reader’s iterable object as a namedtuple, parsed according to the current dialect. Usually you should call this as next(reader).

property dialect¶: A read-only description of the dialect in use by the parser.

property line_num¶: The number of lines read from the source iterator. This is not the same as the number of records returned, as records can span multiple lines.

property row_cls¶: The row tuple subclass from collections.namedtuple() (None before the first row is read).

class csv23.NamedTupleWriter(stream, dialect='excel', encoding=False, **kwargs)¶

csv23.writer() for namedtuples where string values are unicode() strings (PY3: str).

Parameters

stream – File-like object (in binary mode if encoding is given).
dialect – Dialect argument for the func:csv23.writer.
encoding – If not False (default): name of the encoding used to encode the output lines.
**kwargs – Keyword arguments for the csv23.writer().

Raises

NotImplementedError – If encoding is not 8-bit clean.

property dialect¶: A read-only description of the dialect in use by the writer.

writerow(row)¶: Write the row namedtuple to the writer’s file object, formatted according to the current dialect.

writerows(rows)¶: Write all the rows namedtuples to the writer’s file object, formatted according to the current dialect.