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 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_styleandtext_styleare omitted; when either is present, it overrides the preset.custom, or no value at all, makes the rule fully custom.
-
field cell_style : CellProperties | None =
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_FILLand'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_styleandtext_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.
-
BLUE_FILL =
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, andduration_unit2are required.
-
field value1 : Value | None =
None¶ The value the predicate compares the cell against. Predicates that take no operand, such as
is_blankordate_is_today, ignore it, and the top and bottom predicates use it as the threshold count N. ItsValuecase must match the data typepredicate_typeoperates on. For example,text_containsexpects 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 sameValuecase asvalue1.
-
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 tocase_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, avalue1of 5 with adate_qualifier1ofyearsmeans “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_unit1ofhourmeans “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.
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_RELATIVEand'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
value1time units (the unit is given bydate_qualifier1).
-
DATE_BEFORE_RELATIVE =
'date_before_relative'¶ Cell date is before a relative offset of
value1time units (the unit is given bydate_qualifier1).
-
DATE_BETWEEN_RELATIVE =
'date_between_relative'¶ Cell date is between two relative offsets of
value1andvalue2time 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
value1andvalue2.
-
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
value1units (the unit is given bydate_qualifier1).
-
DATE_IS_IN_THE_NEXT =
'date_is_in_the_next'¶ Cell date is within the next
value1units (the unit is given bydate_qualifier1).
-
DATE_IS_THE_DATE =
'date_is_the_date'¶ Cell date is on the same calendar day as
value1. It’s distinct fromdate_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
value1andvalue2.
-
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
value1andvalue2.
-
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
value1andvalue2(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
value1andvalue2.
-
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.
-
DATE_AFTER_RELATIVE =
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.value1orTable.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, anddate_is_the_date.
-
field duration : float | None =
None¶ Duration value in seconds, used by duration predicates. The accompanying
Table.Predicate.duration_unit1(orduration_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, andvalue_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
referenceinvalue1orvalue2is dropped and a warning is reported, and areferenceentry invalue_listis skipped.
-
field text : str | None =
None¶ Text value, used by text-matching predicates (such as
text_contains,text_begins_with,text_ends_with, andtext_is).
-
field date : Date | None =
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_identifierin this table or, for a cross-table reference, in the table identified bytable_identifier.
- field column_identifier : str [Required]¶
The column ID of the referenced cell. It must match a
Table.ColumnHeader.column_identifierin the referenced table.
-
field is_row_absolute : bool =
False¶ Whether the row reference is absolute. It’s
trueif the original notation pinned the row (for example,A$1), andfalseif the row is relative (A1).
-
field is_column_absolute : bool =
False¶ Whether the column reference is absolute. It’s
trueif the original notation pinned the column (for example,$A1), andfalseif 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.identifierof 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_INSENSITIVEand'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.
-
CASE_INSENSITIVE =
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, anddate_in_this.A field accepts a member or its value, so
DateQualifier.AGOand'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_relativeanddate_after_relativepredicates.
-
DAYS =
'days'¶ Days
-
FROM_NOW =
'from_now'¶ The unit count is in the future, for use with the
date_before_relativeanddate_after_relativepredicates.
-
MONTHS =
'months'¶ Months
-
QUARTERS =
'quarters'¶ Quarters
-
WEEKS =
'weeks'¶ Weeks
-
YEARS =
'years'¶ Years
-
AGO =
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
hourmeans “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.DAYand'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
-
DAY =