Aspose.Cells FOSS
Python
JsonHandler

JsonHandler — Aspose.Cells FOSS for Python API Reference

aspose-cells-foss can export worksheet data to JSON via the JsonHandler class. The output represents each row as a JSON object keyed by column header, collected into an array.

Package: aspose.cells_foss

from aspose.cells_foss import JsonHandler, JsonSaveOptions
from aspose.cells_foss import save_workbook_as_json

JsonSaveOptions

Options that control how the worksheet is serialized to JSON.

Constructor 

JsonSaveOptions()

Properties

PropertyTypeDefaultDescription
encodingstr'utf-8'Character encoding for the output file.
worksheet_indexint0Zero-based index of the worksheet to export.
include_worksheet_nameboolFalseWhen True, wraps the row array in an object keyed by the worksheet name.
date_formatstr—strftime format string for datetime.date values (e.g., "%Y-%m-%d").
datetime_formatstr—strftime format string for datetime.datetime values.
time_formatstr—strftime format string for datetime.time values.
empty_cell_valueAnyNoneValue written in place of empty cells (e.g., "", 0, None).
skip_empty_rowsboolFalseWhen True, rows where every cell is empty are omitted.
indentint2JSON indentation in spaces. 0 produces compact single-line output.
ensure_asciiboolFalseWhen True, non-ASCII characters are escaped as \uXXXX sequences.

JsonHandler

JsonHandler contains only static methods and is never instantiated.

JsonHandler.save_json 

JsonHandler.save_json(workbook, file_path: str, options: JsonSaveOptions | None = None) -> None

Exports the worksheet specified by options.worksheet_index (default 0) to a JSON file at file_path. If options is None, default JsonSaveOptions are used.

JsonHandler.save_json_to_dict 

JsonHandler.save_json_to_dict(workbook, options: JsonSaveOptions | None = None) -> dict

Serializes the worksheet to a Python dict (or list) and returns it without writing any file. Useful for programmatic post-processing.

Module Function

save_workbook_as_json 

save_workbook_as_json(workbook, file_path: str, options: JsonSaveOptions | None = None) -> None

Convenience wrapper around JsonHandler.save_json(workbook, file_path, options).

Example

The following example writes a sales table and exports it to a JSON file with ISO date formatting.

from aspose.cells_foss import Workbook, JsonHandler, JsonSaveOptions
import datetime

wb = Workbook()
ws = wb.worksheets[0]
ws.name = "Sales"

# Header row
ws.cells["A1"].put_value("Date")
ws.cells["B1"].put_value("Product")
ws.cells["C1"].put_value("Amount")

# Data rows
ws.cells["A2"].put_value(datetime.date(2025, 1, 15))
ws.cells["B2"].put_value("Widget A")
ws.cells["C2"].put_value(1250.00)

ws.cells["A3"].put_value(datetime.date(2025, 1, 22))
ws.cells["B3"].put_value("Widget B")
ws.cells["C3"].put_value(840.50)

opts = JsonSaveOptions()
opts.date_format = "%Y-%m-%d"
opts.indent = 2
opts.skip_empty_rows = True
opts.include_worksheet_name = True

# Save to file
JsonHandler.save_json(wb, "sales.json", options=opts)

# Or retrieve as a Python dict
data = JsonHandler.save_json_to_dict(wb, options=opts)
print(data)

Example output (sales.json):

{
  "Sales": [
    {"Date": "2025-01-15", "Product": "Widget A", "Amount": 1250.0},
    {"Date": "2025-01-22", "Product": "Widget B", "Amount": 840.5}
  ]
}

See Also