Cell formats¶
Control how Keynote displays a cell’s value.
Charts use the same formats for their labels.
CellFormat¶
-
class creator_studio_doc_format.core.CellFormat(*, preset_identifier=
'', format_type=None, number_format=None, currency_format=None, fraction_format=None, base_format=None, bool_format=None, duration_format=None, date_time_format=None, custom_format_identifier=None, **extra_data)[source]¶ The display format of a cell’s value.
format_typeselects the kind of format, and the matching sub-format property (number_format,currency_format, and so on) holds the options for that kind. Sub-formats for a different kind are ignored.-
field format_type : FormatType | None =
None¶ The kind of formatting to apply (such as number, currency, or date). It determines which sub-format property is read. Keynote doesn’t write
automatic: a cell set to Automatic is written with the format its value is displayed in, such asnumberordate_time, and opens set to that format rather than to Automatic, unless that format istext.
-
field number_format : NumberFormat | None =
None¶ The options for the
number,percentage, andscientificformat types.
-
field currency_format : CurrencyFormat | None =
None¶ The options for the
currencyformat type (such as the currency code and accounting style).
-
field fraction_format : FractionFormat | None =
None¶ The options for the
fractionformat type (for example, display as halves, as eighths, or with an up-to-three-digit numerator).
-
field base_format : BaseFormat | None =
None¶ The options for the
baseformat type (numeric base 2 through 36; for example, binary, octal, or hexadecimal).
-
field bool_format : BoolFormat | None =
None¶ The options for the
booleanformat type (the strings to display for true and false).
-
field duration_format : DurationFormat | None =
None¶ The options for the
durationformat type (its unit range and style).
-
field date_time_format : DateTimeFormat | None =
None¶ The options for the
date_timeformat type (its format string).
-
field custom_format_identifier : str | None =
None¶ The identifier of a shared custom format, declared in
Table.custom_formats, that applies to this cell. It’s used only whenformat_typeiscustomand is ignored for built-in format types.
-
field format_type : FormatType | None =
FormatType¶
- class creator_studio_doc_format.core.FormatType(str, Enum)[source]¶
The kind of formatting to apply to a cell’s value.
Each case selects which sub-format property of the cell format is read.
A field accepts a member or its value, so
FormatType.AUTOMATICand'automatic'are the same. The member’s name as a string isn’t accepted.-
AUTOMATIC =
'automatic'¶ Inferred from the value’s data type: numbers display as numbers, dates as dates, and so on.
-
BASE =
'base'¶ Display in a chosen numeric base (for example, binary, octal, hexadecimal). Shown in Keynote as Numeral System.
-
BOOLEAN =
'boolean'¶ Display as TRUE or FALSE (or as user-specified strings set in the Boolean format options).
-
CURRENCY =
'currency'¶ Currency formatting with a currency symbol or code and optional accounting style.
-
CUSTOM =
'custom'¶ User-defined format string with optional conditional rules (see the table’s custom formats).
-
DATE_TIME =
'date_time'¶ A date, a time, or both, formatted with a date and time format string.
-
DURATION =
'duration'¶ Duration in chosen units (weeks, days, hours, and so on).
-
FRACTION =
'fraction'¶ Display as a fraction at a chosen accuracy (such as halves, eighths, or up to a number of digits).
-
NUMBER =
'number'¶ Plain numeric formatting (decimal places, thousands separator, negative number style).
-
PERCENTAGE =
'percentage'¶ Numeric formatting where the displayed value is the underlying value multiplied by 100, suffixed with “%.”
-
SCIENTIFIC =
'scientific'¶ Scientific notation (for example, 1.23E+04).
-
TEXT =
'text'¶ Treat the value as raw text (no numeric or date interpretation). A reader in version 1.0 doesn’t apply this format, so a cell written with it opens with the
automaticformat instead.
-
AUTOMATIC =
NumberFormat¶
-
class creator_studio_doc_format.core.NumberFormat(*, preset_identifier=
'', decimal_places=2, negative_number_style=NegativeNumberStyle.MINUS, use_thousands_separator=True, **extra_data)[source]¶ Options for plain numeric, percentage, and scientific formatting.
-
field decimal_places : int =
2¶ The number of decimal places to display,
0through 30; a negative value is treated as zero rather than rejected. The value 253 means automatic (as many decimal places as the value needs) rather than a digit count.
-
field negative_number_style : NegativeNumberStyle =
NegativeNumberStyle.MINUS¶ The display style for negative numbers.
-
field use_thousands_separator : bool =
True¶ Whether to insert a thousands separator (for example, 1,234,567).
-
field decimal_places : int =
NegativeNumberStyle¶
- class creator_studio_doc_format.core.NegativeNumberStyle(str, Enum)[source]¶
A style for displaying negative numbers.
A field accepts a member or its value, so
NegativeNumberStyle.MINUSand'minus'are the same. The member’s name as a string isn’t accepted.-
MINUS =
'minus'¶ Prefix with a minus sign (for example, -1,234.56).
-
NONE =
'none'¶ No special treatment for negative values.
-
PARENTHESES =
'parentheses'¶ Wrap in parentheses with no minus sign (for example, (1,234.56)).
-
RED =
'red'¶ Display in red text with a minus sign.
-
RED_AND_PARENTHESES =
'red_and_parentheses'¶ Wrap in parentheses and display in red text.
-
MINUS =
CurrencyFormat¶
-
class creator_studio_doc_format.core.CurrencyFormat(*, preset_identifier=
'', decimal_places=2, negative_number_style=NegativeNumberStyle.MINUS, use_thousands_separator=True, accounting_style=False, currency_code='USD', **extra_data)[source]¶ Options for currency formatting.
-
field decimal_places : int =
2¶ The number of decimal places to display,
0through 30; a negative value is treated as zero rather than rejected. The value 253 means automatic (as many decimal places as the value needs) rather than a digit count.
-
field negative_number_style : NegativeNumberStyle =
NegativeNumberStyle.MINUS¶ The display style for negative amounts.
-
field use_thousands_separator : bool =
True¶ Whether to insert a thousands separator (for example, $1,234,567.00).
-
field accounting_style : bool =
False¶ Whether to use accounting style: currency symbol left-aligned and negative values in parentheses.
-
field currency_code : str =
'USD'¶ The ISO 4217 currency code (for example,
USD,EUR, orJPY) that determines the symbol shown.
-
field decimal_places : int =
FractionFormat¶
-
class creator_studio_doc_format.core.FractionFormat(*, preset_identifier=
'', accuracy=Accuracy.UP_TO_THREE_DIGITS, **extra_data)[source]¶ Options for fraction formatting, such as showing a decimal as a fraction.
Accuracy¶
- class creator_studio_doc_format.core.Accuracy(str, Enum)[source]¶
The granularity of a fraction display.
It’s either a maximum digit count for the numerator and denominator, or a fixed denominator such as halves or quarters.
A field accepts a member or its value, so
Accuracy.CONFLICTINGand'conflicting'are the same. The member’s name as a string isn’t accepted.-
CONFLICTING =
'conflicting'¶ A value that marks a range of cells with mixed fraction accuracies. It’s not a value to set on a single cell.
-
EIGHTHS =
'eighths'¶ Fixed denominator of 8.
-
HALVES =
'halves'¶ Fixed denominator of 2 (for example, 0/2, 1/2).
-
HUNDREDTHS =
'hundredths'¶ Fixed denominator of 100.
-
QUARTERS =
'quarters'¶ Fixed denominator of 4 (for example, 1/4, 3/4).
-
SIXTEENTHS =
'sixteenths'¶ Fixed denominator of 16.
-
TENTHS =
'tenths'¶ Fixed denominator of 10.
-
UP_TO_ONE_DIGIT =
'up_to_one_digit'¶ At most one digit in the numerator and denominator (for example, 1/2, 3/4).
-
UP_TO_THREE_DIGITS =
'up_to_three_digits'¶ At most three digits in the numerator and denominator.
-
UP_TO_TWO_DIGITS =
'up_to_two_digits'¶ At most two digits in the numerator and denominator (for example, 5/16, 22/87).
-
CONFLICTING =
BaseFormat¶
-
class creator_studio_doc_format.core.BaseFormat(*, preset_identifier=
'', base=10, base_places=0, base_use_minus_sign=True, **extra_data)[source]¶ Options for formatting a number in a numeral system such as binary, octal, or hexadecimal.
-
field base : int =
10¶ The numeric base, 1-36 (for example, 2 for binary, 8 for octal, or 16 for hexadecimal). A value outside that range is adjusted to the nearest supported base rather than rejected.
-
field base_places : int =
0¶ The minimum number of digits to display, padding with leading zeros if needed. Values are supported from
0to 32; anything outside that range is adjusted to the nearest supported value rather than rejected.
-
field base_use_minus_sign : bool =
True¶ Whether negative values are shown with a leading minus sign. If
false, they are shown using two’s complement in the chosen base.
-
field base : int =
BoolFormat¶
-
class creator_studio_doc_format.core.BoolFormat(*, preset_identifier=
'', true_string, false_string, **extra_data)[source]¶ Options for Boolean formatting, including the strings shown in place of true and false.
- field true_string : str [Required]¶
The string displayed when the cell value is true (for example,
TRUE,Yes, or✓). It’s only read when the cell’sformat_typeisboolean.
- field false_string : str [Required]¶
The string displayed when the cell value is false (for example,
FALSE,No, or✗). It’s only read when the cell’sformat_typeisboolean.
DurationFormat¶
-
class creator_studio_doc_format.core.DurationFormat(*, preset_identifier=
'', use_automatic_units=True, smallest_unit=Unit.SECOND, largest_unit=Unit.HOUR, style=Style.SHORT, **extra_data)[source]¶ Options for duration formatting.
They set how a span of time is broken into units and displayed.
-
field use_automatic_units : bool =
True¶ Whether units are chosen automatically based on the duration’s magnitude. If it’s
false,smallest_unitandlargest_unitare used.
-
field smallest_unit : Unit =
Unit.SECOND¶ The smallest unit to include in the displayed duration. It’s used only when
use_automatic_unitsisfalse.
-
field use_automatic_units : bool =
Unit¶
- class creator_studio_doc_format.core.Unit(str, Enum)[source]¶
A duration unit.
A field accepts a member or its value, so
Unit.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
-
NONE =
'none'¶ No unit
-
SECOND =
'second'¶ Seconds
-
WEEK =
'week'¶ Weeks
-
DAY =
Style¶
- class creator_studio_doc_format.core.Style(str, Enum)[source]¶
The length of the unit labels in a displayed duration.
A field accepts a member or its value, so
Style.COMPACTand'compact'are the same. The member’s name as a string isn’t accepted.-
COMPACT =
'compact'¶ Single-letter labels with no space (for example, “1h 30m”). Shown in Keynote as None, since the option suppresses unit labels entirely.
-
LONG =
'long'¶ Full-word labels (for example, “1 hour 30 minutes”).
-
SHORT =
'short'¶ Abbreviated labels (for example, “1 hr 30 min”).
-
COMPACT =
DateTimeFormat¶
-
class creator_studio_doc_format.core.DateTimeFormat(*, preset_identifier=
'', format_string, **extra_data)[source]¶ Options for date and time formatting.
- field format_string : str [Required]¶
The date and time format pattern, in Unicode date format (for example,
MMM d, yyyy h:mm a).
CustomFormat¶
-
class creator_studio_doc_format.core.CustomFormat(*, preset_identifier=
'', identifier, format_name=None, format_string, format_type=CustomFormatType.NUMBER, number_format_data=None, conditions=None, **extra_data)[source]¶ A user-defined format for a cell.
A custom format has a format pattern string and optional conditional rules that switch the pattern based on the cell’s value. It’s used when
Table.CellFormat.format_typeiscustom. Custom formats are stored inTable.custom_formats, and individual cells refer to one throughcell_format.custom_format_identifier, so a single definition can be reused by many cells.- field identifier : str [Required]¶
The unique identifier of the custom format. Cells refer to it through
Table.CellFormat.custom_format_identifier.
-
field format_name : str | None =
None¶ The name of the custom format as shown in Keynote’s Data Format pop-up menu (for example,
My Sales Format). It’s optional and purely cosmetic.
- field format_string : str [Required]¶
The format pattern, whose syntax depends on
format_type. Number formats use placeholder tokens such as#,###.00or#,###K, date and time formats use Unicode date patterns such asMMM d, yyyy, and text formats use@as the value placeholder.
-
field format_type : CustomFormatType =
CustomFormatType.NUMBER¶ The kind of value the format applies to. It determines how
format_stringis interpreted and which other properties are used.
-
field number_format_data : NumberFormatData | None =
None¶ The parsed details of
format_string, such as placeholder counts and the scale factor, used to render numeric custom formats. It’s used only whenformat_typeisnumber.
-
field conditions : list[CustomFormatCondition] | None =
None¶ The conditional rules that swap in a different format string when the cell value meets a threshold condition, for example, to format negative values differently from positive ones. They’re used only when
format_typeisnumber.
CustomFormatType¶
- class creator_studio_doc_format.core.CustomFormatType(str, Enum)[source]¶
The kind of value the custom format applies to.
A field accepts a member or its value, so
CustomFormatType.DATE_TIMEand'date_time'are the same. The member’s name as a string isn’t accepted.-
DATE_TIME =
'date_time'¶ Custom format for date and time values; only
format_stringapplies.
-
NUMBER =
'number'¶ Custom format for numeric values;
number_format_dataandconditionsmay be set.
-
TEXT =
'text'¶ Custom format for text values; only
format_stringapplies.
-
DATE_TIME =
NumberFormatData¶
-
class creator_studio_doc_format.core.NumberFormatData(*, preset_identifier=
'', scale_factor=1, fraction_accuracy=None, interstitial_strings=None, interstitial_string_insertion_indexes=None, minimum_integer_width=0, decimal_width=0, number_of_non_space_integer_placeholder_digits=0, number_of_non_space_decimal_placeholder_digits=0, index_from_right_of_last_digit_placeholder=0, number_of_hash_decimal_placeholders=0, total_number_of_decimal_placeholders_in_format=0, currency_code=None, show_thousands_separator=False, use_accounting_style=False, requires_fraction_replacement=False, format_contains_integer_token=False, is_complex_format=False, **extra_data)[source]¶ Details that the reader precomputes from a custom number format’s format string.
They include placeholder counts, padding widths, the scale factor, and currency and separator settings, and they let a reader render the format without having to re-parse the
format_string. They’re shared betweenTable.CustomFormatandTable.CustomFormat.CustomFormatCondition.-
field scale_factor : float =
1¶ The multiplier applied to the value before it’s rendered, used for unit-suffixed formats. For example,
#,###Khas ascale_factorof 0.001, so 1500 displays as “1.5K”, and a percentage uses 100. The default is 1.0, which means no scaling.
-
field fraction_accuracy : Accuracy | None =
None¶ The fraction display granularity. It’s set only when the
format_stringincludes a fraction token such as# ?/?.
-
field interstitial_strings : list[str] | None =
None¶ The literal text fragments embedded in the format string between digit placeholders (for example, the
,, theK, or any quoted text). They’re indexed againstinterstitial_string_insertion_indexes.
-
field interstitial_string_insertion_indexes : list[int] | None =
None¶ The digit positions at which each
interstitial_stringsentry is inserted. It parallelsinterstitial_strings, so their length and order must match.
-
field minimum_integer_width : int =
0¶ The minimum number of integer digits to render. A value with fewer digits is padded with zeros; for example,
0000displays 42 as “0042”.
-
field decimal_width : int =
0¶ The number of decimal-side digit placeholders in the format string, which is the count of
0,#, and?characters after the decimal point.
-
field number_of_non_space_integer_placeholder_digits : int =
0¶ The number of integer-side digit placeholders that aren’t space-padded (that is,
0and#but not?). It’s used to decide which digit positions are filled and which are left blank.
-
field number_of_non_space_decimal_placeholder_digits : int =
0¶ The number of decimal-side digit placeholders that aren’t space-padded (that is,
0and#but not?).
-
field index_from_right_of_last_digit_placeholder : int =
0¶ The position of the rightmost digit placeholder, counted from the right of the
format_string. It’s used to locate where digits stop and trailing literal text begins.
-
field number_of_hash_decimal_placeholders : int =
0¶ The number of
#placeholders after the decimal point, which suppress trailing zeros.
-
field total_number_of_decimal_placeholders_in_format : int =
0¶ The total number of decimal-side digit placeholders:
0,#, and?combined.
-
field currency_code : str | None =
None¶ The ISO 4217 currency code, such as
USDorEUR, when theformat_stringcontains a currency symbol token. It determines the symbol that’s shown.
-
field show_thousands_separator : bool =
False¶ Whether the
format_stringincludes a thousands separator (typically a,between integer placeholders).
-
field use_accounting_style : bool =
False¶ Whether to render in accounting style: currency symbol left-aligned with padding, negative values in parentheses.
-
field requires_fraction_replacement : bool =
False¶ Whether the
format_stringcontains a fraction token, such as?/?, that must be replaced with a computed fraction at render time.
-
field format_contains_integer_token : bool =
False¶ Whether the
format_stringincludes at least one integer-side digit placeholder (0,#, or?before the decimal point).
-
field is_complex_format : bool =
False¶ Whether the format needs custom rendering rather than a standard number formatter (for fractions, space-padded placeholders, or interstitial literal strings).
-
field scale_factor : float =
CustomFormatCondition¶
-
class creator_studio_doc_format.core.CustomFormatCondition(*, preset_identifier=
'', condition_type, condition_value, format_string, number_format_data=None, **extra_data)[source]¶ A conditional rule on a custom number format.
The rule swaps in a different
format_stringwhen the comparison of the cell value withcondition_valueis true, for example, to show negative values in parentheses.- field condition_type : ConditionType [Required]¶
The comparison operator (
equal,less_than,greater_than,less_than_or_equal_to, orgreater_than_or_equal_to) applied between the cell value andcondition_value.
- field condition_value : float [Required]¶
The numeric threshold the cell value is compared against using
condition_type(for example,0to test for negative values).
- field format_string : str [Required]¶
The format pattern applied when the condition is true. It uses the same syntax as
Table.CustomFormat.format_string.
-
field number_format_data : NumberFormatData | None =
None¶ The precomputed parse details of
format_string, used at render time when this condition is active. SeeTable.CustomFormat.NumberFormatData.
ConditionType¶
- class creator_studio_doc_format.core.ConditionType(str, Enum)[source]¶
A comparison operator used by a custom-format condition.
A field accepts a member or its value, so
ConditionType.EQUALand'equal'are the same. The member’s name as a string isn’t accepted.-
EQUAL =
'equal'¶ Cell value equals
condition_value.
-
GREATER_THAN =
'greater_than'¶ Cell value is greater than
condition_value.
-
GREATER_THAN_OR_EQUAL_TO =
'greater_than_or_equal_to'¶ Cell value is greater than or equal to
condition_value.
-
LESS_THAN =
'less_than'¶ Cell value is less than
condition_value.
-
LESS_THAN_OR_EQUAL_TO =
'less_than_or_equal_to'¶ Cell value is less than or equal to
condition_value.
-
EQUAL =