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, andtext_properties), and the stablerow_identifierthat formula references and merges use.-
field row_index : int | None =
None¶ The zero-based position of the row in the table, from
0throughTable.number_of_rowsminus 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_identifierandTable.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_heightfor 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_propertiesoverrides 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_propertiesoverrides 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_indexon 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:
bodyfor 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.
-
field row_index : int | None =
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.FILTEREDand'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.
-
FILTERED =
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
GroupLabelvalue 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.
-
field body : Literal[True] | None =
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_labelcarries 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_identifierof the column intransformation.base_table.column_headerswhose value drives this grouping.
- field group_value : str [Required]¶
The raw lookup key for this group (for example,
West). The formatted form is in thevalueof 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
0is 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_identifierandTable.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_formatoverrides 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_widthfor 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_propertiesoverrides 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_propertiesoverrides 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:
bodyfor 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.
-
field column_identifier : str | None =
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_HIDDENand'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.
-
USER_HIDDEN =
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
GroupLabelvalue 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.
-
field body : Literal[True] | None =
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_labelcarries 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_identifierof the row intransformation.base_table.contentwhose 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
0is 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) andTable.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.
-
field row_column_id_range : RowColumnIdRange | None =
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 `contentand thecolumn_identifier`s in `column_headers; a range can name a row thatcontentomits, 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.