Model bases

Set union cases and override values through the base classes that every model derives from.

ObjectModel

class creator_studio_doc_format.core.ObjectModel(*, preset_identifier='', **extra_data)[source]

The base for the model of every object that isn’t a tagged union.

Besides the fields, the JSON carries an envelope that keeps documents compatible across versions, backward and forward. model_dump writes its type_identifier and version itself, so neither is a field. Dumping a whole document isn’t recommended, because it’s large as JSON, but a small model like this one is fine:

>>> from creator_studio_doc_format.core import Size
>>> dumped = Size(width=100.0, height=50.0).model_dump(mode="json")
>>> dumped["type_identifier"], dumped["version"]
('com.apple.apps.content-language.size', '1.0')

An assignment such as m.field = x validates as strictly as construction does. A change in place, such as m.items.append(bad) or m.mapping[k] = bad, skips validation. Reassign the whole field to revalidate it.

The model handles the envelope and preset inheritance itself, so model_dump and model_dump_json raise ValueError for the options that filter fields, such as exclude_unset and exclude_none.

TaggedUnionModel

class creator_studio_doc_format.core.TaggedUnionModel(*, preset_identifier='', **extra_data)[source]

The base for every tagged union, a property that holds one of several cases.

A subclass declares one optional attribute per case: the payload type, or Literal[True] for a case with no payload. A document can also hold a second case, such as a newer encoding beside an older one. The primary case is the one a reader acts on, and editing only the primary leaves the others stale.

Read a value with a match on union_primary() that ends in assert_never, so a case added later is a type error. An if … is not None chain would skip it instead.

A union adopts a preset through preset_identifier, as an object does. Without a designation, the preset can supply the primary, so pin it with union_of.

classmethod union_of(primary, **cases)[source]

Creates a value from its cases, with one designated as the primary case.

Parameters:
primary : str

The name of the case a reader acts on. cases must set it.

**cases : Any

The payload of each case, keyed by case name.

Returns:

The value, with primary designated.

Return type:

_E

Raises:

ValueError – primary names no case of the class.

union_cases()[source]

Returns the cases that a value holds, primary first, then the others by name.

The primary is the designated case, else the newest. The first entry is the primary_case that model_dump writes when all of these hold:

  • The primary is a case this build knows.

  • The value holds every case its preset supplies.

  • The value has a designation, or holds no unknown case.

Cases this build doesn’t know are left out, though a round trip still preserves them. The result is empty only for a value with no case set, which model_dump rejects unless the value adopts a preset.

Returns:

A (case_name, payload) pair for each present case.

Return type:

tuple[tuple[str, Any], …]

union_primary()[source]

Returns the case that a reader acts on, with its payload.

Prefer it to union_primary_name plus getattr: the payload comes back resolved, as True for a valueless case, and the pair destructures in a match. The primary is the case the document designates, so pick another representation, such as plain text, from union_cases(). The payload is the live model, not a copy.

Returns:

The (case_name, payload) pair, or None if no case is set.

Return type:

tuple[str, Any] | None

union_primary_name()[source]

Returns the name of the case that a reader acts on.

The name is also the attribute name, so it suits classifying a value without touching the payload.

Returns:

The case name, or None if no case is set.

Return type:

str | None

Override

class creator_studio_doc_format.core.Override(state, value=None)[source]

A property value that tells an omitted property, a null, and a value apart.

  • Override.not_set(): omitted from the JSON, so the property can inherit a value.

  • Override.cleared(): an explicit null, which blocks inheritance and clears the value.

  • Override.value(x): the value x.

A field uses Override because T | None can’t tell an omitted property from a null one. The JSON keeps the two apart. Assigning a bare value to an Override field wraps it. None becomes .cleared(), and any other value becomes .value(x).

>>> from creator_studio_doc_format.core import CellProperties
>>> CellProperties.model_validate({"fill": None}).fill.is_cleared
True
state
classmethod not_set()[source]

Returns an override for an omitted property.

Returns:

An override that leaves the property free to inherit a value.

Return type:

Override[_OT]

classmethod cleared()[source]

Returns an override for an explicit null.

Returns:

An override that blocks inheritance and clears the value.

Return type:

Override[_OT]

classmethod value(value)[source]

Returns an override that holds a value.

Parameters:
value : _OT

The property’s value.

Returns:

An override that holds value.

Return type:

Override[_OT]

property is_not_set : bool

A Boolean value that indicates whether the property is omitted.

property is_cleared : bool

A Boolean value that indicates whether the property is an explicit null.

property is_value : bool

A Boolean value that indicates whether the property has a value.

get()[source]

Returns the property’s value.

Returns:

The value, or None if the property is omitted or cleared.

Return type:

_OT | None

PayloadT

creator_studio_doc_format.core.PayloadT

The type variable for the root model of a Package, bound to ObjectModel. KeyxDocument binds it to Presentation.

Model lookup and comparison

creator_studio_doc_format.core.model_for(type_identifier)[source]

Returns the model class for a type identifier.

Parameters:
type_identifier : str

The type_identifier that an object carries in the JSON.

Returns:

The generated model class, or None if no model has that type_identifier.

Return type:

type[ObjectModel | TaggedUnionModel] | None

creator_studio_doc_format.core.same_json(a, b)[source]

Returns a Boolean value that indicates whether two parsed JSON values are equal.

Two strings of JSON text compare only as strings, so parse the text first. Key order doesn’t matter, but array order does. Numbers compare by value, so 1 equals 1.0. True and False never equal 1 and 0. A null differs from an absent key.

Parameters:
a : Any

A parsed JSON value.

b : Any

A parsed JSON value.

Returns:

True if a and b are the same JSON, or False if they aren’t.

Return type:

bool

See also

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