Cells

Set the values, formulas, and appearance of a table’s cells.

Cell

class creator_studio_doc_format.core.Cell(*, preset_identifier='', value='', unformatted_value=None, cell_format=None, cell_properties=None, text_properties=None, strokes=None, anchored_objects=None, column_index=None, formula=None, spill_range=None, conditional_style_set_identifier=None, **extra_data)[source]

A cell in a table.

Its value is carried as a formatted display string in value, a typed underlying value in unformatted_value, or both. It can also have a formula and per-cell style and format overrides.

field value : str = ''

The cell’s content as a pre-formatted string (for example, $1,234.56, 12/25/2024, or 42%). It’s the simplest representation, intended for readers that render the cell as plain text. For the typed value, use unformatted_value.

field unformatted_value : UnformattedValue | None = None

The cell’s typed underlying value (number, text, date, boolean, or rich_text), which lets a reader recover the value’s type when value is only the formatted string. It’s absent when the value has no typed form: a formula that evaluated to an error arrives with formula set and an empty value, so an absent typed value doesn’t mean the cell is empty.

field cell_format : CellFormat | None = None

The cell’s value-formatting override. If it’s set, it overrides the column-level default in Table.ColumnHeader.cell_format for this cell only.

field cell_properties : CellProperties | None = None

The cell’s styling override (fill, alignment, padding, and wrap). If it’s set, it overrides the table-, column-, and row-level defaults for this cell only.

field text_properties : ParagraphProperties | None = None

The cell’s paragraph and text style override (font, size, color, and alignment). If it’s set, it overrides the table-, column-, and row-level defaults for this cell only.

field strokes : Strokes | None = None

The cell’s stroke overrides for each edge (top, bottom, left, and right). An omitted edge falls back to the table-level stroke for the cell’s region.

field anchored_objects : list[str] | None = None

The IDs of the objects, such as shapes and images, that are anchored to the cell. Keynote ignores them.

field column_index : int | None = None

The zero-based column position of the cell in its row, from 0 through Table.number_of_columns minus 1. It’s only required in a sparse row, to mark the first non-blank cell after a gap; the cells that follow are positioned sequentially.

field formula : Formula | None = None

The formula that produces the cell’s value. If it’s present, value and unformatted_value contain the most recently computed result of evaluating the formula.

field spill_range : RowColumnIdRange | None = None

The range that the cell’s formula populates when it spills, with this cell at its top left. It’s only meaningful for a cell whose formula spills, and it’s absent when the spill is blocked. The other cells in the range hold the last spilled result and are replaced on re-evaluation. A corner ID matching no row or column of this table is ignored without a warning, and the cells it would have covered keep the values written for them.

field conditional_style_set_identifier : str | None = None

The ID of a shared conditional style set, declared in Table.conditional_style_sets, that applies to the cell. The first rule in the set whose condition is true for this cell determines its conditional styling. An identifier matching no set is ignored without a warning, and the cell keeps its regular styling.

UnformattedValue

class creator_studio_doc_format.core.UnformattedValue(*, preset_identifier='', boolean=None, date=None, number=None, rich_text=None, text=None, **extra_data)[source]

The unformatted value of a cell, which can be one of several data types.

field boolean : bool | None = None

A Boolean value of true or false.

field date : Date | None = None

A date value, a time value, or both.

field number : float | None = None

A numeric value that’s an integer or decimal.

The cell’s value property carries the formatted string. A duration cell’s number is a count of seconds, so check cell_format before using it in arithmetic.

field rich_text : Text | None = None

Rich text with styling, such as paragraph and character styles.

field text : str | None = None

A plain text value with no styling.

For styled text, use rich_text instead.

Formula

class creator_studio_doc_format.core.Formula(*, preset_identifier='', display_string=None, id_based=None, **extra_data)[source]

The form in which a cell’s formula is carried.

The display_string form is the one to write: it’s the only one a reader resolves in version 1.0. An id_based formula is accepted, but its references aren’t substituted into the expression, so it reaches the reader with its placeholder tokens intact.

field display_string : str | None = None

Formula text in A1 notation.

Keynote writes this text in A1 notation, for example, =SUM(A1:A10), =B$1*$C2, where coordinates count from the table’s top-left cell, header rows and columns included, and $ pins a row or column. A reference into another table is prefixed with that table’s name (Table 2::A1). Keynote writes function names and the argument and decimal separators, among other things, in the presentation’s language and region, and reads them in the language and region the presentation opens with, usually the device’s; English function names are also accepted. A formula that doesn’t parse is dropped without a warning and the cell keeps the value given for it, while one that names an unknown function is kept and the cell shows an error.

field id_based : IdBasedFormula | None = None

A formula expression whose cell references are carried separately as row and column IDs.

This expression means they survive insertions and deletions of rows or columns. A reader in version 1.0 leaves the expression’s placeholder tokens unsubstituted, so a formula written this way arrives with the tokens still in place.

IdBasedFormula

class creator_studio_doc_format.core.IdBasedFormula(*, preset_identifier='', expression, references=None, **extra_data)[source]

A formula whose cell references are stored separately, by row and column ID.

Because they’re stored by ID, the references survive insertions and deletions of rows or columns.

field expression : str [Required]

The formula expression, with placeholder tokens in place of cell references. Placeholders have the form {refN}, zero-indexed. For example, in =SUM({ref0}) + {ref1}, {ref0} resolves to the range carried by references[0] and {ref1} to references[1].

field references : list[CellReference] | None = None

The cell references used by the expression, one entry for each placeholder. Their order must match the {refN} indices in expression.

CellReference

class creator_studio_doc_format.core.CellReference(*, preset_identifier='', placeholder, display_notation=None, start_row_identifier, start_column_identifier, end_row_identifier=None, end_column_identifier=None, is_row_absolute=False, is_column_absolute=False, is_end_row_absolute=False, is_end_column_absolute=False, table_identifier=None, **extra_data)[source]

A reference to a single cell or a rectangular range of cells.

It’s addressed by row and column ID rather than by index, so it stays stable across structural edits.

field placeholder : str [Required]

The placeholder token in the expression that this reference fills in, of the form {refN} (for example, {ref0} or {ref1}).

field display_notation : str | None = None

The original A1-style notation, preserved for display only (for example, A1, B2:D5, or $A$1). It isn’t used during evaluation.

field start_row_identifier : str [Required]

The row ID of a single cell, or of the top-left cell of a range. It must match a Table.Row.row_identifier in this table or, for a cross-table reference, in the table identified by table_identifier.

field start_column_identifier : str [Required]

The column ID of a single cell, or of the top-left cell of a range. It must match a Table.ColumnHeader.column_identifier in the referenced table.

field end_row_identifier : str | None = None

The row ID of the bottom-right cell of a range. Omit it for a single-cell reference.

field end_column_identifier : str | None = None

The column ID of the bottom-right cell of a range. Omit it for a single-cell reference.

field is_row_absolute : bool = False

Whether the start row reference is absolute. It’s true if the original notation pinned the row (for example, A$1) and false for a relative reference (A1).

field is_column_absolute : bool = False

Whether the start column reference is absolute. It’s true if the original notation pinned the column (for example, $A1) and false for a relative reference (A1).

field is_end_row_absolute : bool = False

Whether the end row reference of a range is absolute. It’s only meaningful when end_row_identifier is set.

field is_end_column_absolute : bool = False

Whether the end column reference of a range is absolute. It’s only meaningful when end_column_identifier is set.

field table_identifier : str | None = None

The identifier of another table, for a cross-table reference. It matches the Table.identifier of that table. Omit it for a reference within the same table. An example in A1 notation is Table 2::A1.

Strokes

class creator_studio_doc_format.core.Strokes(*, preset_identifier='', top=None, bottom=None, left=None, right=None, **extra_data)[source]

The stroke overrides for the edges of a cell.

An omitted edge falls back to the table-level stroke for the cell’s region (body, header, or footer).

field top : Stroke | None = None

The stroke along the top edge of the cell.

field bottom : Stroke | None = None

The stroke along the bottom edge of the cell.

field left : Stroke | None = None

The stroke along the left edge of the cell.

field right : Stroke | None = None

The stroke along the right edge of the cell.

CellProperties

class creator_studio_doc_format.core.CellProperties(*, preset_identifier='', text_wrap=None, vertical_alignment=None, padding=None, fill=Override.not_set(), **extra_data)[source]

The styling of a table cell, other than its strokes.

Strokes are kept separately, in Table.Cell.Strokes, so individual edges can be overridden.

field text_wrap : bool | None = None

Whether text that exceeds the column width wraps to more lines (true) or clip (false).

field vertical_alignment : VerticalAlignmentType | None = None

The vertical alignment of content in the cell (top, middle, or bottom).

field padding : Insets | None = None

The inset of the cell’s content from the cell’s edges, in points (top, leading, bottom, and trailing).

field fill : Override[Fill] = Override.not_set()

The cell’s background fill (color, gradient, or image). If it’s absent, the fill is inherited; an explicit null gives the cell no fill, which isn’t the same as a fill at 0% opacity.