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 inunformatted_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, or42%). It’s the simplest representation, intended for readers that render the cell as plain text. For the typed value, useunformatted_value.
-
field unformatted_value : UnformattedValue | None =
None¶ The cell’s typed underlying value (
number,text,date,boolean, orrich_text), which lets a reader recover the value’s type whenvalueis only the formatted string. It’s absent when the value has no typed form: a formula that evaluated to an error arrives withformulaset and an emptyvalue, 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_formatfor 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
0throughTable.number_of_columnsminus 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,
valueandunformatted_valuecontain the most recently computed result of evaluating the formula.
-
field spill_range : RowColumnIdRange | None =
None¶ The range that the cell’s
formulapopulates 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.
-
field value : str =
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 number : float | None =
None¶ A numeric value that’s an integer or decimal.
The cell’s
valueproperty carries the formatted string. A duration cell’s number is a count of seconds, so checkcell_formatbefore 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_textinstead.
-
field boolean : bool | None =
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_stringform is the one to write: it’s the only one a reader resolves in version 1.0. Anid_basedformula 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.
-
field display_string : str | None =
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 byreferences[0]and{ref1}toreferences[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 inexpression.
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_identifierin this table or, for a cross-table reference, in the table identified bytable_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_identifierin 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
trueif the original notation pinned the row (for example,A$1) andfalsefor a relative reference (A1).
-
field is_column_absolute : bool =
False¶ Whether the start column reference is absolute. It’s
trueif the original notation pinned the column (for example,$A1) andfalsefor 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_identifieris 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_identifieris set.
-
field table_identifier : str | None =
None¶ The identifier of another table, for a cross-table reference. It matches the
Table.identifierof that table. Omit it for a reference within the same table. An example in A1 notation isTable 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).
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 text_wrap : bool | None =