Presets

Store reusable styles as presets, and resolve the values an object inherits from them.

Preset

class creator_studio_doc_format.core.Preset(identifier, properties, *, display_name=None, parent_identifier=None)[source]

A preset, as one entry in the presets file stores it.

PresetRegistry resolves inheritance along parent_identifier.

Parameters:
identifier : str

The name that an adopting object’s preset_identifier refers to.

properties : dict[str, Any]

The properties that adopting objects inherit, as raw JSON.

display_name : str | None

The name that Keynote shows.

parent_identifier : str | None

The identifier of the preset this one inherits from.

classmethod from_dict(data)[source]

Creates a preset from a decoded entry of the presets file.

Parameters:
data : dict[str, Any]

One decoded entry of the presets.json array.

Returns:

The preset, with its properties as raw JSON.

Return type:

Preset

Raises:

KeyError – data has no identifier or no properties.

to_dict()[source]

Returns the preset in the form that the presets file stores.

Returns:

The entry, without any optional key that holds None.

Return type:

dict[str, Any]

PresetRegistry

class creator_studio_doc_format.core.PresetRegistry(presets)[source]

A resolver of preset inheritance for decoding and encoding.

The registry walks the parent_identifier chain and merges each child’s properties over its parent’s. A cycle raises ValueError. A missing preset or parent adds an entry to warnings and contributes no properties. A model takes the registry as its context["wire_presets"] resolver.

Parameters:
presets : list[Preset]

The presets to resolve against. A later preset replaces an earlier one with the same identifier.

>>> from creator_studio_doc_format.core import (
...     CellProperties,
...     Preset,
...     PresetRegistry,
... )
>>> registry = PresetRegistry(
...     [
...         Preset("base", {"text_wrap": True, "vertical_alignment": "top"}),
...         Preset(
...             "wrapped",
...             {"vertical_alignment": "middle"},
...             parent_identifier="base",
...         ),
...     ]
... )
>>> registry.resolved_properties("wrapped")
{'text_wrap': True, 'vertical_alignment': 'middle'}

When the JSON omits a field, decoding takes its value from the preset. Encoding with the same registry leaves out a value that still matches the preset, so the value stays linked to it. A value that differs is written:

>>> context = {"wire_presets": registry}
>>> cell = CellProperties.model_validate(
...     {"preset_identifier": "wrapped"}, context=context
... )
>>> cell.text_wrap
True
>>> "text_wrap" in cell.model_dump(mode="json", context=context)
False
>>> cell.text_wrap = False
>>> cell.model_dump(mode="json", context=context)["text_wrap"]
False
resolved_properties(identifier)[source]

Returns the properties of a preset, merged over its ancestors’ properties.

Every call for an identifier returns the same dictionary, so don’t mutate it.

Parameters:
identifier : str

The identifier of the preset to resolve.

Returns:

The merged properties, or an empty dictionary when the preset is missing.

Return type:

dict[str, Any]

Raises:

ValueError – the parent_identifier chain has a cycle.

See also

Declare presets and Write nulls only where you mean them in the format’s authoring requirements, and Turn off an inherited value for what a null means.