Raw API Reference

The raw API (Model) is a low level API. Nothing is evaluated automatically: call Model.evaluate() after making changes, otherwise the workbook may be in an inconsistent state. There is no undo/redo history and no diffs are produced. It is faster and more flexible than the user API, but easier to get wrong.

Conventions are the same as in the user API: 0-based sheet indexes, 1-based row and column indexes, dictionaries for complex values and WorkbookError on invalid input.

Evaluation and persistence

Model.evaluate()

Evaluates the workbook. Call this after each batch of changes.

Model.save_to_xlsx(file: str)

Model.save_to_icalc(file: str)

Model.to_xlsx() → bytes

Returns the workbook as bytes in xlsx format.

Model.to_bytes() → bytes

Setting values

Model.set_user_input(sheet: int, row: int, column: int, value: str)

Sets the input of a cell as a user would type it: "3.5" is a number, "Hello" a string, "=A1*2" a formula.

Model.update_cell_with_text(sheet: int, row: int, column: int, value: str)

Sets a string value without input parsing ("123" stays a string).

Model.update_cell_with_number(sheet: int, row: int, column: int, value: float)

Model.update_cell_with_bool(sheet: int, row: int, column: int, value: bool)

Model.update_cell_with_formula(sheet: int, row: int, column: int, formula: str)

Model.set_user_array_formula(sheet, row, column, width, height, formula: str)

Sets an array (spill) formula covering width x height cells.

Model.clear_cell_contents(sheet: int, row: int, column: int)

Clears the content of a single cell, keeping the formatting.

Model.range_clear_contents(sheet, start_row, start_column, end_row, end_column)

Model.range_clear_all(sheet, start_row, start_column, end_row, end_column)

Getting values

Model.get_cell_value(sheet: int, row: int, column: int)

Returns the value of a cell as a native Python value: None, str, float or bool.

Model.get_cell_value_by_ref(cell_ref: str)

Same, with a reference like "Sheet1!C4".

Model.get_formatted_cell_value(sheet: int, row: int, column: int) → str

Returns the value formatted with the cell’s number format (i.e. "$5.75").

Model.get_cell_content(sheet: int, row: int, column: int) → str

Returns the content as seen in the editor: the formula if there is one, the raw value otherwise.

Model.get_cell_formula(sheet: int, row: int, column: int) → str | None

Model.get_cell_type(sheet: int, row: int, column: int) → CellType

Model.is_empty_cell(sheet: int, row: int, column: int) → bool

Model.get_all_cells() → list[tuple[int, int, int]]

Returns all non-empty cells as (sheet, row, column) tuples.

Model.get_sheet_dimensions(sheet: int)

Returns (min_row, max_row, min_column, max_column) of the non-empty cells; (1, 1, 1, 1) for an empty sheet.

Model.get_sheet_markup(sheet: int) → str

Returns a markdown-like table of the sheet (formulas, not values), useful for debugging and tests.

Model.cycle_reference(value: str, start: int, end: int)

Cycles the references touched by the cursor through the four absolute/relative states, Excel F4 style (see UserModel.cycle_reference()).

Styles

Styles are dictionaries; see Objects.

Model.get_cell_style(sheet: int, row: int, column: int) → dict

Model.set_cell_style(sheet: int, row: int, column: int, style: dict)

Model.get_column_style(sheet: int, column: int) → dict | None

Model.set_column_style(sheet: int, column: int, style: dict)

Model.delete_column_style(sheet: int, column: int)

Model.get_row_style(sheet: int, row: int) → dict | None

Model.set_row_style(sheet: int, row: int, style: dict)

Model.delete_row_style(sheet: int, row: int)

Rows and columns

Model.insert_rows(sheet: int, row: int, row_count: int)

Model.insert_columns(sheet: int, column: int, column_count: int)

Model.delete_rows(sheet: int, row: int, row_count: int)

Model.delete_columns(sheet: int, column: int, column_count: int)

Model.get_column_width(sheet: int, column: int) → float

Model.get_row_height(sheet: int, row: int) → float

Model.set_column_width(sheet: int, column: int, width: float)

Model.set_row_height(sheet: int, row: int, height: float)

Model.set_column_hidden(sheet: int, column: int, hidden: bool)

Model.set_row_hidden(sheet: int, row: int, hidden: bool)

Model.is_column_hidden(sheet: int, column: int) → bool

Model.is_row_hidden(sheet: int, row: int) → bool

Model.get_frozen_rows_count(sheet: int) → int

Model.get_frozen_columns_count(sheet: int) → int

Model.set_frozen_rows_count(sheet: int, row_count: int)

Model.set_frozen_columns_count(sheet: int, column_count: int)

Sheets

Model.add_sheet(sheet_name: str)

Model.new_sheet()

Adds a sheet with an automatically generated name.

Model.delete_sheet(sheet: int)

Model.rename_sheet(sheet: int, new_name: str)

Model.set_sheet_color(sheet: int, color)

color is None, "#RRGGBB" or [theme_index, tint].

Model.set_sheet_state(sheet: int, state: str)

state is "visible", "hidden" or "veryHidden".

Model.get_worksheets_properties() → list[dict]

Model.set_show_grid_lines(sheet: int, show_grid_lines: bool)

Merged cells

Model.merge_cells(sheet, start_row, start_column, end_row, end_column)

Merges the range into a single cell anchored at its top-left corner. At most one cell of the range may have content: it moves to the anchor. Fails if the range is a single cell, intersects an existing merged cell or an array formula, or has more than one cell with content.

Model.merge_cells_center(sheet, start_row, start_column, end_row, end_column)

Same as merge_cells but also centers the content horizontally (“merge & center”).

Model.merge_cells_across(sheet, start_row, start_column, end_row, end_column)

Merges each row of the range separately (“merge across”). All-or-nothing.

Model.merge_cells_down(sheet, start_row, start_column, end_row, end_column)

Merges each column of the range separately (“merge down”). All-or-nothing.

Model.unmerge_cells(sheet, start_row, start_column, end_row, end_column)

Removes every merged cell that intersects the range, keeping the content of the anchors. Unmerging nothing is not an error.

Model.get_merged_cells(sheet: int) → list[dict]

One entry per merged cell: {"row", "column", "width", "height"} where (row, column) is the anchor cell.

Defined names

Model.get_defined_name_list() → list[dict]

Model.new_defined_name(name: str, scope: int | None, formula: str)

Model.update_defined_name(name, scope, new_name, new_scope, new_formula)

Model.delete_defined_name(name: str, scope: int | None)

Workbook properties

Model.get_theme() → dict

Model.set_theme(theme: dict)

Model.get_timezone() → str

Model.set_timezone(timezone: str)

Model.get_locale() → str

Model.set_locale(locale: str)

Model.get_language() → str

Model.set_language(language: str)

Model.get_fmt_settings() → dict