Conditional styles

Style a cell when its value meets a condition.

Filters test cells with the same predicates.

ConditionalStyleSet

class creator_studio_doc_format.core.ConditionalStyleSet(*, preset_identifier='', identifier, rules, **extra_data)[source]

A shared set of conditional highlighting rules that multiple cells can reference.

field identifier : str [Required]

The unique identifier of the conditional style set.

field rules : list[TableConditionalStyleSetRule] [Required]

The ordered list of conditional highlighting rules, with a maximum of 15. The first rule whose predicate is true for the cell is applied, and the rules after it aren’t.

TableConditionalStyleSetRule

class creator_studio_doc_format.core.TableConditionalStyleSetRule(*, preset_identifier='', predicate, cell_style=None, text_style=None, preset_kind=None, **extra_data)[source]

A single conditional highlighting rule with a predicate and styling to apply when the predicate is true.

field predicate : Predicate [Required]

The condition that determines when this rule applies.

field cell_style : CellProperties | None = None

The cell styling to apply when the predicate is true.

field text_style : ParagraphProperties | None = None

The text styling to apply when the predicate is true.

field preset_kind : PresetKind | None = None

The built-in conditional-highlighting preset this rule represents. A named preset supplies the styling when cell_style and text_style are omitted; when either is present, it overrides the preset. custom, or no value at all, makes the rule fully custom.

PresetKind

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

The built-in conditional-highlighting preset that a rule represents.

It lets readers associate the rule with a known visual style.

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

BLUE_FILL = 'blue_fill'

Blue cell fill with white text.

BLUE_TEXT = 'blue_text'

Blue text preset.

BOLD = 'bold'

Bold text preset.

CUSTOM = 'custom'

A fully custom style, set entirely by cell_style and text_style.

GRAY_TEXT = 'gray_text'

Gray text preset.

GREEN_FILL = 'green_fill'

Green cell fill with white text.

GREEN_TEXT = 'green_text'

Green text preset.

ITALICS = 'italics'

Italic text preset.

ORANGE_FILL = 'orange_fill'

Orange cell fill with white text.

RED_FILL = 'red_fill'

Red cell fill with white text.

RED_TEXT = 'red_text'

Red text preset.

TEAL_FILL = 'teal_fill'

Teal cell fill with white text.

YELLOW_FILL = 'yellow_fill'

Yellow cell fill with white text.

Predicate

class creator_studio_doc_format.core.Predicate(*, preset_identifier='', predicate_type, value1=None, value2=None, qualifier=None, date_qualifier1=None, date_qualifier2=None, duration_unit1=None, duration_unit2=None, value_list=None, **extra_data)[source]

A condition that’s evaluated against a single cell’s value.

Some predicates evaluate the cell relative to its column instead. Predicates are used by conditional highlighting rules and, in future versions, by table filter rules.

field predicate_type : PredicateType [Required]

The kind of comparison or test to perform. It determines which of value1, value2, value_list, qualifier, date_qualifier1, date_qualifier2, duration_unit1, and duration_unit2 are required.

field value1 : Value | None = None

The value the predicate compares the cell against. Predicates that take no operand, such as is_blank or date_is_today, ignore it, and the top and bottom predicates use it as the threshold count N. Its Value case must match the data type predicate_type operates on. For example, text_contains expects text.

field value2 : Value | None = None

The second comparison value. It’s required only for range predicates (value_between, value_not_between, date_is_between, duration_is_between, date_between_relative, duration_is_not_between). It must use the same Value case as value1.

field qualifier : Qualifier | None = None

The case sensitivity of a text predicate (text_contains, text_begins_with, text_ends_with, text_is, text_is_not, text_does_not_contain, text_not_starts_with, text_not_ends_with). If it’s omitted, it defaults to case_insensitive.

field date_qualifier1 : DateQualifier | None = None

The time unit for the first value of relative date predicates (date_is_in_the_last, date_is_in_the_next, date_before_relative, date_after_relative, date_between_relative, date_in_this). For example, a value1 of 5 with a date_qualifier1 of years means “5 years.” It’s required for these predicates.

field date_qualifier2 : DateQualifier | None = None

The time unit for the second value of relative-date range predicates (date_between_relative). It’s required only when both ends of the range need separate units.

field duration_unit1 : DurationUnit | None = None

The display unit for the first value of duration predicates. The duration value itself is stored as a number of seconds, and this unit determines how to interpret it; for example, 3600 seconds with a duration_unit1 of hour means “1 hour.” It’s required for duration predicates.

field duration_unit2 : DurationUnit | None = None

The display unit for the second value of duration range predicates (duration_is_between, duration_is_not_between). It’s required when those predicates are used.

field value_list : list[Value] | None = None

The ordered list of typed values that the in_list and not_in_list predicates compare the cell against. All entries must use the same Value case. If it’s present, value1 and value2 are ignored.

PredicateType

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

The type of conditional test to perform.

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

DATE_AFTER_RELATIVE = 'date_after_relative'

Cell date is after a relative offset of value1 time units (the unit is given by date_qualifier1).

DATE_BEFORE_RELATIVE = 'date_before_relative'

Cell date is before a relative offset of value1 time units (the unit is given by date_qualifier1).

DATE_BETWEEN_RELATIVE = 'date_between_relative'

Cell date is between two relative offsets of value1 and value2 time units.

DATE_IN_THIS = 'date_in_this'

Cell date is in the day, week, month, or year (the unit is given by date_qualifier1).

DATE_IS_AFTER = 'date_is_after'

Cell date is after value1.

DATE_IS_BEFORE = 'date_is_before'

Cell date is before value1.

DATE_IS_BETWEEN = 'date_is_between'

Cell date is between value1 and value2.

DATE_IS_EXACTLY = 'date_is_exactly'

Cell date is exactly value1.

DATE_IS_IN_THE_LAST = 'date_is_in_the_last'

Cell date is within the last value1 units (the unit is given by date_qualifier1).

DATE_IS_IN_THE_NEXT = 'date_is_in_the_next'

Cell date is within the next value1 units (the unit is given by date_qualifier1).

DATE_IS_THE_DATE = 'date_is_the_date'

Cell date is on the same calendar day as value1. It’s distinct from date_is_exactly.

DATE_IS_TODAY = 'date_is_today'

Cell date is today.

DATE_IS_TOMORROW = 'date_is_tomorrow'

Cell date is tomorrow.

DATE_IS_YESTERDAY = 'date_is_yesterday'

Cell date is yesterday.

DISTINCTS = 'distincts'

Cell is one of the distinct values in the column.

DUPLICATES = 'duplicates'

Cell value is duplicated elsewhere in the column.

DURATION_ABOVE_AVERAGE = 'duration_above_average'

Cell duration is above the average.

DURATION_BELOW_AVERAGE = 'duration_below_average'

Cell duration is below the average.

DURATION_BOTTOM = 'duration_bottom'

Cell duration is in the bottom N values (or bottom N percent) of its column. The threshold N is given by value1.

DURATION_IS_BETWEEN = 'duration_is_between'

Cell duration is between value1 and value2.

DURATION_IS_EQUAL = 'duration_is_equal'

Cell duration equals value1.

DURATION_IS_GREATER_THAN = 'duration_is_greater_than'

Cell duration is greater than value1.

DURATION_IS_GREATER_THAN_OR_EQUAL = 'duration_is_greater_than_or_equal'

Cell duration is greater than or equal to value1.

DURATION_IS_LESS_THAN = 'duration_is_less_than'

Cell duration is less than value1.

DURATION_IS_LESS_THAN_OR_EQUAL = 'duration_is_less_than_or_equal'

Cell duration is less than or equal to value1.

DURATION_IS_NOT_BETWEEN = 'duration_is_not_between'

Cell duration isn’t between value1 and value2.

DURATION_IS_NOT_EQUAL = 'duration_is_not_equal'

Cell duration doesn’t equal value1.

DURATION_TOP = 'duration_top'

Cell duration is in the top N values (or top N percent) of its column. The threshold N is given by value1.

FORMULA = 'formula'

Cell matches an arbitrary formula-based predicate. The formula text is given by value1, in the consuming application’s formula syntax.

IN_LIST = 'in_list'

Cell value matches any value in value_list.

IS_BLANK = 'is_blank'

Cell is blank.

IS_CHECKED = 'is_checked'

Cell checkbox is checked.

IS_FALSE = 'is_false'

Cell value is FALSE.

IS_NEGATIVE = 'is_negative'

Cell numeric value is negative (< 0).

IS_NOT_BLANK = 'is_not_blank'

Cell isn’t blank.

IS_NOT_CHECKED = 'is_not_checked'

Cell checkbox isn’t checked.

IS_POSITIVE = 'is_positive'

Cell numeric value is zero or positive (>= 0).

IS_TRUE = 'is_true'

Cell value is TRUE.

NOT_IN_LIST = 'not_in_list'

Cell value matches none of the values in value_list.

PIVOT_SOURCE_FILTERED_FOR_COLUMN = 'pivot_source_filtered_for_column'

The column is filtered by a pivot table’s source predicates. It’s reserved for pivot tables, which version 1.0 doesn’t support.

PIVOT_SOURCE_FILTERED_FOR_ROW = 'pivot_source_filtered_for_row'

The row is filtered by a pivot table’s source predicates. It’s reserved for pivot tables, which version 1.0 doesn’t support.

TEXT_BEGINS_WITH = 'text_begins_with'

Cell text begins with value1.

TEXT_CONTAINS = 'text_contains'

Cell text contains value1.

TEXT_DOES_NOT_CONTAIN = 'text_does_not_contain'

Cell text doesn’t contain value1.

TEXT_ENDS_WITH = 'text_ends_with'

Cell text ends with value1.

TEXT_IS = 'text_is'

Cell text is exactly value1.

TEXT_IS_NOT = 'text_is_not'

Cell text isn’t value1.

TEXT_NOT_ENDS_WITH = 'text_not_ends_with'

Cell text doesn’t end with value1.

TEXT_NOT_STARTS_WITH = 'text_not_starts_with'

Cell text doesn’t begin with value1.

UNIQUES = 'uniques'

Cell value is unique in the column.

VALUE_ABOVE_AVERAGE = 'value_above_average'

Cell value is above the column or row average.

VALUE_BELOW_AVERAGE = 'value_below_average'

Cell value is below the column or row average.

VALUE_BETWEEN = 'value_between'

Cell value is between value1 and value2 (inclusive).

VALUE_BOTTOM = 'value_bottom'

Cell value is in the bottom N values (or bottom N percent) of its column. The threshold N is given by value1.

VALUE_EQUAL = 'value_equal'

Cell value equals value1.

VALUE_GREATER_THAN = 'value_greater_than'

Cell value is greater than value1.

VALUE_GREATER_THAN_OR_EQUAL = 'value_greater_than_or_equal'

Cell value is greater than or equal to value1.

VALUE_LESS_THAN = 'value_less_than'

Cell value is less than value1.

VALUE_LESS_THAN_OR_EQUAL = 'value_less_than_or_equal'

Cell value is less than or equal to value1.

VALUE_NOT_BETWEEN = 'value_not_between'

Cell value isn’t between value1 and value2.

VALUE_NOT_EQUAL = 'value_not_equal'

Cell value doesn’t equal value1.

VALUE_TOP = 'value_top'

Cell value is in the top N values (or top N percent) of its column. The threshold N is given by value1.

Value

class creator_studio_doc_format.core.Value(*, preset_identifier='', date=None, duration=None, number=None, reference=None, text=None, **extra_data)[source]

A typed comparison value.

This value is carried in Table.Predicate.value1 or Table.Predicate.value2.

Its case must match the data type the predicate operates on.

field date : Date | None = None

Absolute date value, used by absolute date predicates.

Examples of these values are date_is_before, date_is_after, date_is_between, date_is_exactly, and date_is_the_date.

field duration : float | None = None

Duration value in seconds, used by duration predicates. The accompanying Table.Predicate.duration_unit1 (or duration_unit2) determines how to interpret the value.

field number : float | None = None

Numeric value, used by value-comparison predicates, for example, value_equal, value_greater_than, and value_between, and by relative date predicates that take a unit count, for example, date_is_in_the_last.

field reference : Reference | None = None

The comparison operand is another cell rather than a literal value (for example, “date is before [B2]”). A reader compares the referenced cell’s value at evaluation time. A version 1.0 reader doesn’t support a cell operand: a rule that compares against a reference in value1 or value2 is dropped and a warning is reported, and a reference entry in value_list is skipped.

field text : str | None = None

Text value, used by text-matching predicates (such as text_contains, text_begins_with, text_ends_with, and text_is).

Reference

class creator_studio_doc_format.core.Reference(*, preset_identifier='', row_identifier, column_identifier, is_row_absolute=False, is_column_absolute=False, table_identifier=None, **extra_data)[source]

A reference to a single cell, used as a predicate’s comparison operand.

It addresses the cell by row and column ID, so the reference stays stable across structural edits. Range references aren’t supported here; predicate operands are always single scalar values.

field row_identifier : str [Required]

The row ID of the referenced cell. 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 column_identifier : str [Required]

The column ID of the referenced cell. It must match a Table.ColumnHeader.column_identifier in the referenced table.

field is_row_absolute : bool = False

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

field is_column_absolute : bool = False

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

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.

Qualifier

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

A qualifier for text-matching predicates.

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

CASE_INSENSITIVE = 'case_insensitive'

Match is case insensitive.

CASE_SENSITIVE = 'case_sensitive'

Match is case sensitive.

DateQualifier

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

A time unit for relative date predicates, as in “in the last 5 years.”

It’s used by predicates that take a unit count as their value, such as date_is_in_the_last, date_is_in_the_next, date_before_relative, date_after_relative, date_between_relative, and date_in_this.

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

AGO = 'ago'

The unit count is in the past, for use with the date_before_relative and date_after_relative predicates.

DAYS = 'days'

Days

FROM_NOW = 'from_now'

The unit count is in the future, for use with the date_before_relative and date_after_relative predicates.

MONTHS = 'months'

Months

QUARTERS = 'quarters'

Quarters

WEEKS = 'weeks'

Weeks

YEARS = 'years'

Years

DurationUnit

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

The display unit for a duration predicate’s values.

The duration value itself is stored as a number of seconds; this unit indicates how to interpret and render that value. For example, a value of 7200 with the unit hour means “2 hours.” It’s required for a predicate with duration values to be read back correctly.

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

DAY = 'day'

Days

HOUR = 'hour'

Hours

MILLISECOND = 'millisecond'

Milliseconds

MINUTE = 'minute'

Minutes

SECOND = 'second'

Seconds

WEEK = 'week'

Weeks