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_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.

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)

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