CSV / Excel

Purpose and Use Case

The zbsync_excel_csv module adds a matched pair of workers for reading and writing tabular file formats:

Worker	Technical name	Role
CSV / Excel Grabber	zbs.grabber.csvexcel	Parses CSV or Excel (.xlsx) content into a list of records.
CSV / Excel Dumper	zbs.dumper.csvexcel	Serialises incoming records into CSV or Excel content.

Both workers operate on the content (or filecontent) of the record they receive — they don't read from disk themselves. They're typically placed after a File Grabber, FTP Grabber, or a file-upload wizard (which supplies the raw bytes), and before/after a Mapper that shapes the row data to match the destination.

CSV / Excel Grabber

Configuration

Field	Description
Type	CSV or Excel — selects which parser is used.
First Line of Data	1-based row number where data starts. Rows before this are skipped entirely (useful for files with title rows above the header).
Data Contains Headers	If enabled, the first data row's cell values become the field names for every subsequent row.
Field names comma separated	Required when Data Contains Headers is disabled — a comma-separated list of field names to apply, in column order.
Max Column Count	Excel only. Caps how many columns are scanned per row (default 1000).
CSV Delimiter	CSV only. Default ;.
Sample File	An example file upload, intended to drive an automatic mapper suggestion.
Encoding	Character encoding used when the underlying content is binary and needs decoding to text (CSV only).
Sheet Name	Excel only. Leave blank to read the workbook's active sheet.

The Generate Mapper button (next to Sample File) is not implemented yet — clicking it raises an error rather than creating a mapper. Build the downstream Mapper manually until this ships.

How It Works

• CSV: streamed row by row with Python's csv module, honoring the configured delimiter.
• Excel: read with openpyxl in read-only mode, iterating rows on the selected (or active) sheet up to Max Column Count columns.
• Both output one dict per row, keyed by the resolved field names, ready for a Mapper or Dumper.

CSV / Excel Dumper

Configuration

Field	Description
Type	CSV or Excel — selects which writer is used.
Encoding	Character encoding applied to CSV output. Not used for Excel, which always produces binary .xlsx content.
First Line Headers	If enabled, writes a header row from the field names before the data rows.
Field names comma separated	Explicit column order and set of fields to write. If left blank, the keys of the first incoming record are used.
CSV Delimiter	CSV only. Default ;.

How It Works

• CSV: writes rows with Python's csv module, then encodes the resulting text with the configured Encoding.
• Excel: builds a single-sheet workbook with openpyxl and returns the binary content.
• The dumper's output feeds a following worker (e.g. a File Dumper or FTP Dumper) that writes the content to its final destination — the CSV/Excel Dumper itself only produces the file content, it doesn't write to disk.

Usage and Best Practices

Common Pitfalls

• Wrong delimiter: a CSV Grabber/Dumper configured with the wrong CSV Delimiter silently produces single-column rows rather than an error.
• Header mismatch: if Data Contains Headers is disabled on the Grabber but Field names is left blank, rows will be dropped because there is nothing to key them by.
• Sheet Name typos: an incorrect Sheet Name on the Grabber raises a key error at runtime rather than falling back to the active sheet.

Performance Tips

• For very wide Excel sheets, set Max Column Count to the actual number of columns in use — a default cap of 1000 columns is scanned per row otherwise.
• The Excel Grabber uses openpyxl's read-only, lazy-loading mode, so large workbooks are not fully loaded into memory at once.