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_type selects 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 as number or date_time, and opens set to that format rather than to Automatic, unless that format is text.

field number_format : NumberFormat | None = None

The options for the number, percentage, and scientific format types.

field currency_format : CurrencyFormat | None = None

The options for the currency format type (such as the currency code and accounting style).

field fraction_format : FractionFormat | None = None

The options for the fraction format 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 base format type (numeric base 2 through 36; for example, binary, octal, or hexadecimal).

field bool_format : BoolFormat | None = None

The options for the boolean format type (the strings to display for true and false).

field duration_format : DurationFormat | None = None

The options for the duration format type (its unit range and style).

field date_time_format : DateTimeFormat | None = None

The options for the date_time format 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 when format_type is custom and is ignored for built-in format types.

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.AUTOMATIC and '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 automatic format instead.

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, 0 through 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).

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.MINUS and '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.

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, 0 through 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, or JPY) that determines the symbol shown.

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.

field accuracy : Accuracy = Accuracy.UP_TO_THREE_DIGITS

The precision to use for the fraction representation.

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.CONFLICTING and '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).

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 0 to 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.

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’s format_type is boolean.

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’s format_type is boolean.

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_unit and largest_unit are used.

field smallest_unit : Unit = Unit.SECOND

The smallest unit to include in the displayed duration. It’s used only when use_automatic_units is false.

field largest_unit : Unit = Unit.HOUR

The largest unit to include in the displayed duration. It’s used only when use_automatic_units is false.

field style : Style = Style.SHORT

The formatting style, which can be compact (“1h”), short (“1 hr”), or long (“1 hour”).

Unit

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

A duration unit.

A field accepts a member or its value, so Unit.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

NONE = 'none'

No unit

SECOND = 'second'

Seconds

WEEK = 'week'

Weeks

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.COMPACT and '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”).

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_type is custom. Custom formats are stored in Table.custom_formats, and individual cells refer to one through cell_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 #,###.00 or #,###K, date and time formats use Unicode date patterns such as MMM 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_string is 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 when format_type is number.

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_type is number.

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_TIME and '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_string applies.

NUMBER = 'number'

Custom format for numeric values; number_format_data and conditions may be set.

TEXT = 'text'

Custom format for text values; only format_string applies.

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 between Table.CustomFormat and Table.CustomFormat.CustomFormatCondition.

field scale_factor : float = 1

The multiplier applied to the value before it’s rendered, used for unit-suffixed formats. For example, #,###K has a scale_factor of 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_string includes 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 ,, the K, or any quoted text). They’re indexed against interstitial_string_insertion_indexes.

field interstitial_string_insertion_indexes : list[int] | None = None

The digit positions at which each interstitial_strings entry is inserted. It parallels interstitial_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, 0000 displays 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, 0 and # 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, 0 and # 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 USD or EUR, when the format_string contains a currency symbol token. It determines the symbol that’s shown.

field show_thousands_separator : bool = False

Whether the format_string includes 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_string contains 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_string includes 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).

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_string when the comparison of the cell value with condition_value is 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, or greater_than_or_equal_to) applied between the cell value and condition_value.

field condition_value : float [Required]

The numeric threshold the cell value is compared against using condition_type (for example, 0 to 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. See Table.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.EQUAL and '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.