Chart axes

Configure the category and value axes of a chart.

ChartAxisCommon

class creator_studio_doc_format.core.ChartAxisCommon(*, preset_identifier='', chartCategoryAxis=None, chartValueAxis=None, genericChartAxisCommon=None, **extra_data)[source]

The properties every chart axis shares, flattened into both the category axis and the value axis.

They cover the axis’s title, its tick labels and their rotation, and its tick marks. What differs by kind of axis is on ChartCategoryAxis and ChartValueAxis themselves: the axis line and its gridlines, a category axis’s label spacing, and a value axis’s scale and bounds.

field chartCategoryAxis : ChartCategoryAxis | None = None
field chartValueAxis : ChartValueAxis | None = None
field genericChartAxisCommon : GenericChartAxisCommon | None = None

AxisLabelOrientation

class creator_studio_doc_format.core.AxisLabelOrientation(*, preset_identifier='', custom=None, horizontal=None, left_diagonal=None, left_vertical=None, parallel=None, perpendicular=None, right_diagonal=None, right_vertical=None, **extra_data)[source]

The orientation of an axis’s labels relative to the axis.

Rotating the labels lets long labels stay legible without widening the chart.

field custom : float | None = None

Labels rotated by the given number of degrees, measured counterclockwise. The value is written in the range 0 to 360; a value outside that range is read as the equivalent angle within it. An angle that matches one of the five named straight-axis orientations is written as that case instead.

field horizontal : Literal[True] | None = None

Labels drawn horizontally, with no rotation.

field left_diagonal : Literal[True] | None = None

Labels rotated diagonally, at 45 degrees.

field left_vertical : Literal[True] | None = None

Labels rotated to vertical, at 90 degrees.

field parallel : Literal[True] | None = None

Radar charts only: labels drawn along the spoke they label.

field perpendicular : Literal[True] | None = None

Radar charts only: labels drawn at right angles to the spoke they label.

field right_diagonal : Literal[True] | None = None

Labels rotated diagonally the opposite way from left_diagonal, at 315 degrees (equivalently -45 degrees).

field right_vertical : Literal[True] | None = None

Labels rotated to vertical the opposite way from left_vertical, at 270 degrees (equivalently -90 degrees).

GenericChartAxisCommon

class creator_studio_doc_format.core.GenericChartAxisCommon(*, preset_identifier='', title=None, title_text_style=None, label_text_style=None, show_labels=True, show_title=False, show_major_tickmarks=True, show_minor_tickmarks=True, labels_orientation=None, **extra_data)[source]

A stand-in for a chart axis, when the reader doesn’t recognize its kind.

Every set of shared properties has one, to stand in for an object whose kind isn’t recognized. Nothing in the format has the type ChartAxisCommon, though, so this object never appears in a document; its properties appear only as part of the types that adopt ChartAxisCommon.

field title : str | None = None

The text of the axis title. Whether the title is shown is controlled separately by show_title.

field title_text_style : ParagraphProperties | None = None

The text style of the axis title, such as its font, size, and alignment.

field label_text_style : ParagraphProperties | None = None

The text style of the axis labels, such as their font, size, and alignment.

field show_labels : bool = True

Whether the axis’s tick labels are shown.

field show_title : bool = False

Whether the axis title is shown.

field show_major_tickmarks : bool = True

Whether major tick marks are shown along the axis.

field show_minor_tickmarks : bool = True

Whether minor tick marks are shown along the axis.

field labels_orientation : AxisLabelOrientation | None = None

The rotation of the axis’s labels. The five straight-axis orientations correspond to rotations of 0, 45, 90, 270, and 315 degrees, custom carries any other rotation, and parallel and perpendicular apply to radar charts.

ChartCategoryAxis

class creator_studio_doc_format.core.ChartCategoryAxis(*, preset_identifier='', title=None, title_text_style=None, label_text_style=None, show_labels=True, show_title=False, show_major_tickmarks=True, show_minor_tickmarks=True, labels_orientation=None, label_format_type=None, label_date_format=None, label_duration_format=None, label_number_format=None, label_currency_format=None, label_spacing=None, show_axis=True, show_major_gridlines=False, show_clustered_series_labels=False, show_last_label=False, **extra_data)[source]

The axis along which a chart’s categories are laid out, on the chart types that have one.

Pie, donut, scatter, and bubble charts have no category axis. A category axis describes only its own appearance; the category names themselves come from the data grid’s row or column labels, whichever ChartData.plot_direction leaves as the category direction.

field title : str | None = None

The text of the axis title. Whether the title is shown is controlled separately by show_title.

field title_text_style : ParagraphProperties | None = None

The text style of the axis title, such as its font, size, and alignment.

field label_text_style : ParagraphProperties | None = None

The text style of the axis labels, such as their font, size, and alignment.

field show_labels : bool = True

Whether the axis’s tick labels are shown.

field show_title : bool = False

Whether the axis title is shown.

field show_major_tickmarks : bool = True

Whether major tick marks are shown along the axis.

field show_minor_tickmarks : bool = True

Whether minor tick marks are shown along the axis.

field labels_orientation : AxisLabelOrientation | None = None

The rotation of the axis’s labels. The five straight-axis orientations correspond to rotations of 0, 45, 90, 270, and 315 degrees, custom carries any other rotation, and parallel and perpendicular apply to radar charts.

field label_format_type : FormatType | None = None

The kind of formatting applied to the label’s value. It also selects which of label_number_format, label_currency_format, label_date_format, and label_duration_format applies. text, boolean, and base have no equivalent for chart labels and behave like number, which is also what omitting this property means.

field label_date_format : DateTimeFormat | None = None

The date and time format of the label, used when label_format_type is date_time. An empty format string is treated as no format at all and isn’t preserved.

field label_duration_format : DurationFormat | None = None

The label’s duration format, used when label_format_type is duration. It covers automatic units, the smallest and largest unit, and the style.

field label_number_format : NumberFormat | None = None

The decimal places, negative-number style, and thousands separator of the label, used for number, percentage, and scientific labels. A value of 253 for decimal places means automatic. It’s omitted for fraction, base, and custom labels, which have none of these attributes; a prefix or suffix, a fraction accuracy, and a custom format string aren’t preserved. Currency labels use label_currency_format instead. On a stacked chart whose value axis has a ChartValueAxis.scale of percent, the value labels of each series don’t use this format, and their decimal places, negative-number style, and thousands separator aren’t preserved.

field label_currency_format : CurrencyFormat | None = None

The currency code, accounting style, decimal places, negative-number style, and thousands separator of the label, used when label_format_type is currency. It takes the place of label_number_format for currency labels, and it’s what preserves the currency code; a prefix or suffix and a custom format string aren’t preserved.

field label_spacing : LabelSpacing | None = None

The spacing of the category labels. auto_fit lets the chart pick the spacing, show_all shows a label for every category, and custom shows every Nth label. none is never written.

field show_axis : bool = True

Whether the category axis line itself is shown.

field show_major_gridlines : bool = False

Whether a gridline is shown at each category division.

field show_clustered_series_labels : bool = False

Whether each series’ name is shown on the category axis of a clustered bar or column chart.

field show_last_label : bool = False

Whether the last category’s label is always shown, even when label_spacing would skip it.

LabelSpacing

class creator_studio_doc_format.core.LabelSpacing(*, preset_identifier='', auto_fit=None, custom=None, none=None, show_all=None, **extra_data)[source]

The spacing of the category labels along the axis.

A label can be shown for every category, or for a reduced set chosen to fit the space available.

field auto_fit : Literal[True] | None = None
field custom : int | None = None

Every Nth category label is shown, where N is the given value. An N of 0 is written as auto_fit instead, and an N of 1 as show_all.

field none : Literal[True] | None = None
field show_all : Literal[True] | None = None

ChartValueAxis

class creator_studio_doc_format.core.ChartValueAxis(*, preset_identifier='', title=None, title_text_style=None, label_text_style=None, show_labels=True, show_title=False, show_major_tickmarks=True, show_minor_tickmarks=True, labels_orientation=None, label_format_type=None, label_date_format=None, label_duration_format=None, label_number_format=None, label_currency_format=None, scale=None, max=None, min=None, show_axis=False, show_major_gridlines=True, show_minimum_label=True, number_of_major_gridlines=None, number_of_decades=None, number_of_minor_gridlines=None, show_minor_gridlines=False, **extra_data)[source]

A numeric axis that a chart’s values are measured against.

The same type serves every value axis a chart has, so a property takes effect only where that axis supports it.

field title : str | None = None

The text of the axis title. Whether the title is shown is controlled separately by show_title.

field title_text_style : ParagraphProperties | None = None

The text style of the axis title, such as its font, size, and alignment.

field label_text_style : ParagraphProperties | None = None

The text style of the axis labels, such as their font, size, and alignment.

field show_labels : bool = True

Whether the axis’s tick labels are shown.

field show_title : bool = False

Whether the axis title is shown.

field show_major_tickmarks : bool = True

Whether major tick marks are shown along the axis.

field show_minor_tickmarks : bool = True

Whether minor tick marks are shown along the axis.

field labels_orientation : AxisLabelOrientation | None = None

The rotation of the axis’s labels. The five straight-axis orientations correspond to rotations of 0, 45, 90, 270, and 315 degrees, custom carries any other rotation, and parallel and perpendicular apply to radar charts.

field label_format_type : FormatType | None = None

The kind of formatting applied to the label’s value. It also selects which of label_number_format, label_currency_format, label_date_format, and label_duration_format applies. text, boolean, and base have no equivalent for chart labels and behave like number, which is also what omitting this property means.

field label_date_format : DateTimeFormat | None = None

The date and time format of the label, used when label_format_type is date_time. An empty format string is treated as no format at all and isn’t preserved.

field label_duration_format : DurationFormat | None = None

The label’s duration format, used when label_format_type is duration. It covers automatic units, the smallest and largest unit, and the style.

field label_number_format : NumberFormat | None = None

The decimal places, negative-number style, and thousands separator of the label, used for number, percentage, and scientific labels. A value of 253 for decimal places means automatic. It’s omitted for fraction, base, and custom labels, which have none of these attributes; a prefix or suffix, a fraction accuracy, and a custom format string aren’t preserved. Currency labels use label_currency_format instead. On a stacked chart whose value axis has a ChartValueAxis.scale of percent, the value labels of each series don’t use this format, and their decimal places, negative-number style, and thousands separator aren’t preserved.

field label_currency_format : CurrencyFormat | None = None

The currency code, accounting style, decimal places, negative-number style, and thousands separator of the label, used when label_format_type is currency. It takes the place of label_number_format for currency labels, and it’s what preserves the currency code; a prefix or suffix and a custom format string aren’t preserved.

field scale : AxisScale | None = None

The scale of the axis: linear, log for a logarithmic axis, or percent. If it’s omitted, the scale is linear.

field max : ChartDataValue | None = None

The upper bound of the axis, which must be above min. A date or duration bound takes effect but isn’t written back out, so only a numeric bound is kept when Keynote exports the presentation. If it’s omitted, the axis scales itself to the data.

field min : ChartDataValue | None = None

The lower bound of the axis, which must be below max. A date or duration bound takes effect but isn’t written back out, so only a numeric bound is kept when Keynote exports the presentation. If it’s omitted, the axis scales itself to the data.

field show_axis : bool = False

Whether the value axis line itself is shown.

field show_major_gridlines : bool = True

Whether a gridline is shown at each major step of the axis.

field show_minimum_label : bool = True

Whether the label for the axis’s lowest value is shown.

field number_of_major_gridlines : int | None = None

The number of major steps the axis is divided into, each marked by a major gridline. Omit it, or set it to 0, to let the chart choose the number of steps automatically.

field number_of_decades : int | None = None

The number of powers of ten the axis is divided into, for logarithmic axes only. Omit it, or set it to 0, to let the chart choose the number automatically.

field number_of_minor_gridlines : int | None = None

The number of minor steps between each pair of major gridlines. Omit it, or set it to 0, to keep the chart’s own minor spacing.

field show_minor_gridlines : bool = False

Whether minor gridlines are shown.

AxisScale

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

How values are spaced along the axis: evenly, or by order of magnitude so that a wide range stays readable.

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

LINEAR = 'linear'
LOG = 'log'
PERCENT = 'percent'

Values are shown as a percentage of the total, as used by charts that stack their series to 100%.