CSVHandler — Aspose.Cells FOSS for Python API Reference
aspose-cells-foss provides CSV import and export through the CSVHandler class and two companion option classes. Module-level convenience functions are also available for simple use cases.
Package: aspose.cells_foss
from aspose.cells_foss import CSVHandler, CSVLoadOptions, CSVSaveOptions
from aspose.cells_foss import load_csv_workbook, save_workbook_as_csvCSVLoadOptions
Options that control how a CSV file is parsed when loading.
Constructor
CSVLoadOptions()Properties
| Property | Type | Default | Description |
|---|---|---|---|
delimiter | str | ',' | Field separator character. |
encoding | str | 'utf-8' | Character encoding of the source file. |
has_header | bool | False | When True, treats the first row as a header row. |
quote_char | str | '"' | Character used to quote fields that contain the delimiter or newlines. |
escape_char | str | None | None | Optional escape character (e.g., '\\'). |
skip_rows | int | 0 | Number of leading rows to skip before parsing data. |
auto_detect_types | bool | True | When True, attempts to infer numeric and boolean types from cell text. |
date_formats | list | [] | List of date format strings (e.g., ["%Y-%m-%d"]) tried in order during type detection. |
true_values | list | [] | Strings recognized as boolean True (e.g., ["yes", "true", "1"]). |
false_values | list | [] | Strings recognized as boolean False (e.g., ["no", "false", "0"]). |
CSVSaveOptions
Options that control how a workbook is serialized to CSV.
Constructor
CSVSaveOptions()Properties
| Property | Type | Default | Description |
|---|---|---|---|
delimiter | str | ',' | Field separator written between values. |
encoding | str | 'utf-8' | Character encoding for the output file. |
quote_char | str | '"' | Character used to quote fields containing the delimiter or newlines. |
line_terminator | str | '\r\n' | Line-ending sequence written after each row. |
include_header | bool | True | When True, writes the header row. |
worksheet_index | int | 0 | Zero-based index of the worksheet to export. |
date_format | str | — | Format string for datetime.date values (e.g., "%Y-%m-%d"). |
datetime_format | str | — | Format string for datetime.datetime values. |
time_format | str | — | Format string for datetime.time values. |
write_bom | bool | False | When True, writes a UTF-8 BOM at the start of the file. |
CSVHandler
CSVHandler contains only static methods and is never instantiated.
CSVHandler.save_csv
CSVHandler.save_csv(workbook, file_path: str, options: CSVSaveOptions | None = None) -> NoneSaves the specified worksheet of workbook to a CSV file at file_path. If options is None, default CSVSaveOptions are used.
CSVHandler.save_csv_to_string
CSVHandler.save_csv_to_string(workbook, options: CSVSaveOptions | None = None) -> strSerializes the worksheet to a CSV string and returns it. No file is written.
CSVHandler.load_csv
CSVHandler.load_csv(workbook, file_path: str, options: CSVLoadOptions | None = None) -> NoneParses the CSV file at file_path and loads its data into the first worksheet of workbook, replacing any existing content. If options is None, default CSVLoadOptions are used.
CSVHandler.load_csv_from_string
CSVHandler.load_csv_from_string(workbook, csv_content: str, options: CSVLoadOptions | None = None) -> NoneParses a CSV string and loads its data into the first worksheet of workbook.
Module Functions
load_csv_workbook
load_csv_workbook(file_path: str, options: CSVLoadOptions | None = None) -> WorkbookCreates a new Workbook, loads the CSV file into its first worksheet, and returns the workbook. Equivalent to creating a Workbook and calling CSVHandler.load_csv(wb, file_path, options).
save_workbook_as_csv
save_workbook_as_csv(workbook, file_path: str, options: CSVSaveOptions | None = None) -> NoneConvenience wrapper around CSVHandler.save_csv(workbook, file_path, options).
Example
The following example loads a comma-delimited CSV file and saves it back with a semicolon delimiter.
from aspose.cells_foss import load_csv_workbook, CSVLoadOptions, CSVSaveOptions, save_workbook_as_csv
# Load the original CSV
load_opts = CSVLoadOptions()
load_opts.delimiter = ","
load_opts.has_header = True
load_opts.auto_detect_types = True
wb = load_csv_workbook("input.csv", options=load_opts)
# Inspect what was loaded
ws = wb.worksheets[0]
print(f"Rows loaded: {ws.cells.max_data_row + 1}")
# Save as semicolon-delimited CSV
save_opts = CSVSaveOptions()
save_opts.delimiter = ";"
save_opts.encoding = "utf-8"
save_opts.line_terminator = "\n" # Unix line endings
save_workbook_as_csv(wb, "output_semicolon.csv", options=save_opts)