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_dumpwrites itstype_identifierandversionitself, 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 = xvalidates as strictly as construction does. A change in place, such asm.items.append(bad)orm.mapping[k] = bad, skips validation. Reassign the whole field to revalidate it.The model handles the envelope and preset inheritance itself, so
model_dumpandmodel_dump_jsonraiseValueErrorfor the options that filter fields, such asexclude_unsetandexclude_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
matchonunion_primary()that ends inassert_never, so a case added later is a type error. Anif … is not Nonechain 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 withunion_of.- classmethod union_of(primary, **cases)[source]¶
Creates a value from its cases, with one designated as the primary case.
- 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_casethatmodel_dumpwrites 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_dumprejects 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_nameplusgetattr: the payload comes back resolved, asTruefor a valueless case, and the pair destructures in amatch. The primary is the case the document designates, so pick another representation, such as plain text, fromunion_cases(). The payload is the live model, not a copy.- Returns:
The
(case_name, payload)pair, orNoneif no case is set.- Return type:
tuple[str, Any] | 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 valuex.
A field uses
OverridebecauseT | Nonecan’t tell an omitted property from a null one. The JSON keeps the two apart. Assigning a bare value to anOverridefield wraps it.Nonebecomes.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]
- 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.
PayloadT¶
- creator_studio_doc_format.core.PayloadT¶
The type variable for the root model of a
Package, bound toObjectModel.KeyxDocumentbinds it toPresentation.
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_identifierthat an object carries in the JSON.
- Returns:
The generated model class, or
Noneif no model has thattype_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
1equals1.0.TrueandFalsenever equal1and0. Anulldiffers from an absent key.
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.