Rows and columns

Define a table’s rows and column headers, and the ranges of cells across them.

Row

class creator_studio_doc_format.core.Row(*, preset_identifier='', row_index=None, row_identifier=None, row_height=None, cell_properties=None, text_properties=None, cells=None, visibility_state=TableRowVisibilityState.VISIBLE, kind=TableRowKind(body=True), **extra_data)[source]

A row in a table.

It holds the row’s cells, optional row-level defaults (row_height, cell_properties, and text_properties), and the stable row_identifier that formula references and merges use.

field row_index : int | None = None

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

field row_identifier : str | None = None

The row’s stable identifier. Formula references (Table.Cell.Formula.CellReference.start_row_identifier and Table.Cell.Formula.CellReference.end_row_identifier) and merge ranges use it, so references survive row insertions and deletions.

field row_height : float | None = None

The height of the row, in points, which must be greater than 0. If it’s present, it overrides Table.default_row_height for this row only.

field cell_properties : CellProperties | None = None

The default cell styling for cells in the row. It overrides the table and column defaults, and Table.Cell.cell_properties overrides it for an individual cell.

field text_properties : ParagraphProperties | None = None

The default paragraph and text style for cells in the row. It overrides the table and column defaults, and Table.Cell.text_properties overrides it for an individual cell.

field cells : list[Cell] | None = None

The cells in the row, ordered from left to right. The list is sparse: trailing blank cells can be omitted, and a gap in the middle is marked by Table.Cell.column_index on the next non-blank cell.

field visibility_state : TableRowVisibilityState = TableRowVisibilityState.VISIBLE

Whether this row is visible, and if not, whether the user hid it or the active filter excluded it. Rows that aren’t visible remain in content.

field kind : TableRowKind = TableRowKind(body=True)

The row’s structural role: body for an ordinary data row. The other roles (group label, subtotal, and grand total) are reserved for categorized and pivot tables, which version 1.0 doesn’t support.

TableRowVisibilityState

class creator_studio_doc_format.core.TableRowVisibilityState(str, Enum)[source]

Whether a row is visible, and if not, whether it was hidden explicitly or excluded by the active filter.

A field accepts a member or its value, so TableRowVisibilityState.FILTERED and 'filtered' are the same. The member’s name as a string isn’t accepted.

FILTERED = 'filtered'

The row didn’t pass the active filter rules in transformation.filter_set. Disabling the filter or removing the failing rule makes the row visible again.

USER_HIDDEN = 'user_hidden'

The user hid the row with the Hide Row command.

VISIBLE = 'visible'

The row is shown.

TableRowKind

class creator_studio_doc_format.core.TableRowKind(*, preset_identifier='', body=None, grand_total=None, group_label=None, group_subtotal=None, **extra_data)[source]

The structural role of a row.

The default is body; the other cases are reserved for categorized and pivot tables, which version 1.0 doesn’t support.

field body : Literal[True] | None = None

An ordinary data row.

field grand_total : Literal[True] | None = None

A grand-total row in a categorized or pivot table, which version 1.0 doesn’t support.

field group_label : TableRowGroupLabel | None = None

A category header row, or a pivot table’s row-axis group label; version 1.0 supports neither. Its GroupLabel value identifies the grouping column and the group the row represents.

field group_subtotal : Literal[True] | None = None

A subtotal row for one group in a categorized or pivot table, which version 1.0 doesn’t support.

TableRowGroupLabel

class creator_studio_doc_format.core.TableRowGroupLabel(*, preset_identifier='', grouping_column_identifier, group_value, is_collapsed=False, nesting_level=0, **extra_data)[source]

The group that a category header row, or a pivot table’s row-axis group label, stands for.

It’s reserved for categorized and pivot tables, which version 1.0 doesn’t support. A row whose kind is group_label carries it. It identifies the column being grouped on and the group the row represents.

field grouping_column_identifier : str [Required]

The stable Table.ColumnHeader.column_identifier of the column in transformation.base_table.column_headers whose value drives this grouping.

field group_value : str [Required]

The raw lookup key for this group (for example, West). The formatted form is in the value of the row’s first cell; this is the key used for grouping and sorting, and it identifies the group.

field is_collapsed : bool = False

Whether this group is collapsed.

field nesting_level : int = 0

The zero-based nesting depth among the row-axis groupings. A value of 0 is the outermost grouping, and deeper levels nest inside it.

ColumnHeader

class creator_studio_doc_format.core.ColumnHeader(*, preset_identifier='', column_identifier=None, title=None, cell_format=None, column_width=None, cell_properties=None, text_properties=None, visibility_state=TableColumnHeaderVisibilityState.VISIBLE, kind=TableColumnHeaderKind(body=True), **extra_data)[source]

The metadata for a column in a table.

Its default formatting and styling apply to the body cells in the column.

field column_identifier : str | None = None

The column’s stable identifier. Formula references (Table.Cell.Formula.CellReference.start_column_identifier and Table.Cell.Formula.CellReference.end_column_identifier) and merge ranges use it, so inserting or removing columns doesn’t invalidate references.

field title : str | None = None

The column’s display title. By default, it mirrors the value of the column’s first header cell; for a column with no header or a blank header, a generic name (for example, Column C) may be used.

field cell_format : CellFormat | None = None

The default data format (such as number, currency, or date) for body cells in the column. Header and footer rows aren’t affected. Table.Cell.cell_format overrides it for an individual cell.

field column_width : float | None = None

The width of the column, in points, which must be greater than 0. If it’s present, it overrides Table.default_column_width for this column only.

field cell_properties : CellProperties | None = None

The default cell styling (fill, alignment, padding, and wrap) for body cells in the column. Table.Cell.cell_properties overrides it for an individual cell.

field text_properties : ParagraphProperties | None = None

The default paragraph and text style for body cells in the column. Table.Cell.text_properties overrides it for an individual cell.

field visibility_state : TableColumnHeaderVisibilityState = TableColumnHeaderVisibilityState.VISIBLE

Whether this column is visible. Hidden columns are still counted by number_of_columns.

field kind : TableColumnHeaderKind = TableColumnHeaderKind(body=True)

The column’s structural role: body for an ordinary data column. The other roles (group label, subtotal, and grand total) are reserved for pivot tables, which version 1.0 doesn’t support.

TableColumnHeaderVisibilityState

class creator_studio_doc_format.core.TableColumnHeaderVisibilityState(str, Enum)[source]

A string that indicates whether a column is visible.

A field accepts a member or its value, so TableColumnHeaderVisibilityState.USER_HIDDEN and 'user_hidden' are the same. The member’s name as a string isn’t accepted.

USER_HIDDEN = 'user_hidden'

The user hid the with the Hide Column command.

VISIBLE = 'visible'

The column is shown.

TableColumnHeaderKind

class creator_studio_doc_format.core.TableColumnHeaderKind(*, preset_identifier='', body=None, grand_total=None, group_label=None, group_subtotal=None, **extra_data)[source]

The structural role of a column.

The default is body; the other cases are reserved for pivot tables, which version 1.0 doesn’t support.

field body : Literal[True] | None = None

An ordinary data column.

field grand_total : Literal[True] | None = None

A pivot table’s grand-total column, which version 1.0 doesn’t support.

field group_label : TableColumnHeaderGroupLabel | None = None

A pivot table’s group-label column, which version 1.0 doesn’t support. Its GroupLabel value holds the grouping row identifier and the group value.

field group_subtotal : Literal[True] | None = None

A pivot table’s subtotal column for one group, which version 1.0 doesn’t support.

TableColumnHeaderGroupLabel

class creator_studio_doc_format.core.TableColumnHeaderGroupLabel(*, preset_identifier='', grouping_row_identifier, group_value, is_collapsed=False, nesting_level=0, **extra_data)[source]

The group that a pivot table’s group-label column stands for.

It’s reserved for pivot tables, which version 1.0 doesn’t support. A column whose kind is group_label carries it. It identifies the row in the source data being grouped on and the group the column represents.

field grouping_row_identifier : str [Required]

The stable Table.Row.row_identifier of the row in transformation.base_table.content whose value drives this grouping along the column axis.

field group_value : str [Required]

The raw lookup key for this group (for example, West). It’s distinct from any formatted display string in the column header cell: the formatted form is in the corresponding cells, and this is the key used for grouping and sorting, and it identifies the group.

field is_collapsed : bool = False

Whether this group is collapsed.

field nesting_level : int = 0

The zero-based nesting depth among the column-axis groupings. A value of 0 is the outermost grouping, and deeper levels nest inside it.

CellRange

class creator_studio_doc_format.core.CellRange(*, preset_identifier='', row_column_id_range=None, **extra_data)[source]

A rectangular range of cells in a table.

It’s addressed by row and column IDs, so it stays stable across structural edits. It’s defined so that future versions can add other ways to address a range. Fields that use it include Table.merges (visually combined cells) and Table.Cell.spill_range (the range a spilling formula populates).

field row_column_id_range : RowColumnIdRange | None = None

A range addressed by the row ID and column ID of its top-left and bottom-right cells.

RowColumnIdRange

class creator_studio_doc_format.core.RowColumnIdRange(*, preset_identifier='', top_left_row_identifier, top_left_column_identifier, bottom_right_row_identifier, bottom_right_column_identifier, **extra_data)[source]

A range addressed by the row and column IDs of its top-left and bottom-right cells.

Using IDs rather than indexes keeps the range stable across row and column insertions and deletions. Resolve each ID against the row_identifier`s of the rows in `content and the column_identifier`s in `column_headers; a range can name a row that content omits, and such a range can’t be located.

field top_left_row_identifier : str [Required]

The row ID of the top-left cell of the range.

field top_left_column_identifier : str [Required]

The column ID of the top-left cell of the range.

field bottom_right_row_identifier : str [Required]

The row ID of the bottom-right cell of the range.

field bottom_right_column_identifier : str [Required]

The column ID of the bottom-right cell of the range.