cs.csvutils 20190103

CSV file related facilities

Utility functions for CSV files.

In python 2 the stdlib CSV reader reads 8 bit byte data and returns str objects; these need to be decoded into unicode objects. In python 3 the stdlib CSV reader reads an open text file and returns str objects (== unicode). So we provide csv_reader() generators to yield rows containing unicode.

Function csv_import(fp, class_name=None, column_names=None, computed=None, preprocess=None, mixin=None, **kw)

Read CSV data where the first row contains column headers. Returns a row namedtuple factory and an iterable of instances.

Parameters:

• fp: a file object containing CSV data, or the name of such a file
• class_name: optional class name for the namedtuple subclass used for the row data.
• column_names: optional iterable of column headings; if provided then the file is not expected to have internal column headings
• computed: optional keyword parameter providing a mapping of str to functions of self; these strings are available via getitem
• preprocess: optional keyword parameter providing a callable to modify CSV rows before they are converted into the namedtuple. It receives a context object an the data row. It may return the row (possibly modified), or None to drop the row.
• mixin: an optional mixin class for the generated namedtuple subclass to provide extra methods or properties

All other keyword paramaters are passed to csv_reader(). This is a very thin shim around cs.mappings.named_column_tuples.

Examples:

  >>> cls, rows = csv_import(['a, b', '1,2', '3,4'], class_name='Example_AB')
  >>> cls     #doctest: +ELLIPSIS
  <function named_row_tuple.<locals>.factory at ...>
  >>> list(rows)
  [Example_AB(a='1', b='2'), Example_AB(a='3', b='4')]

  >>> cls, rows = csv_import(['1,2', '3,4'], class_name='Example_DEFG', column_names=['D E', 'F G '])
  >>> list(rows)
  [Example_DEFG(d_e='1', f_g='2'), Example_DEFG(d_e='3', f_g='4')]

Function csv_writerow(csvw, row, encoding='utf-8')

Write the supplied row as strings encoded with the supplied encoding, default 'utf-8'.

Function xl_import(workbook, sheet_name, skip_rows=0, **kw)

Read the named sheet_name from the Excel XLSX file named filename as for csv_import. Returns a row namedtuple factory and an iterable of instances.

Parameters:

• workbook: Excel work book from which to load the sheet; if this is a str then the work book is obtained from openpyxl.load_workbook()
• sheet_name: the name of the work book sheet whose data should be imported

Other keyword parameters are as for cs.mappings.named_column_tuples.

NOTE: this function requires the openpyxl module to be available.