Documents¶
Open, create, and save a document.
KeyxDocument¶
-
class creator_studio_doc_format.core.KeyxDocument(payload, *, presets=
None, manifest=None, resources=None)[source]¶ Bases:
Package[Presentation]A document that holds a presentation with its presets, manifest, and resources.
Opening, saving, and closing are inherited from
Package. For more information, seePackage.open(),Package.open_lazy(),Package.save(), andPackage.close().- Parameters:
- payload_model¶
Presentation, the model thatmain.jsonis validated against.
- property presentation : Presentation¶
The document’s presentation, decoded from the main JSON file.
presentationandpayloadreturn the same object.
Package¶
-
class creator_studio_doc_format.core.Package(payload, *, presets=
None, manifest=None, resources=None)[source]¶ A document package in memory, with its payload, presets, manifest, and resources.
- Parameters:
- payload_model¶
The model class that
openandopen_lazyvalidatemain.jsonagainst by default. Each subclass sets it.Packagesets none, so opening one directly needspayload_model=.
-
classmethod open(source, *, payload_model=
None)[source]¶ Opens a package from a ZIP archive or a readable stream.
The method doesn’t accept an unzipped package directory. Zip it with
main.jsonat the root of the archive.- Parameters:
- Returns:
The package, with every resource already read.
- Return type:
Self- Raises:
DocumentPackageError–sourceisn’t a valid package, andkindnames the defect.DocumentVersionError–sourcedeclares a package or object version this library doesn’t implement.pydantic.ValidationError–main.jsondoesn’t matchpayload_model.ValueError–sourceis a stream that can’t seek.OSError–sourcecan’t be read, such as a path that doesn’t exist.TypeError– neitherpayload_modelnor the class’spayload_modelis set.
-
classmethod open_lazy(source, *, payload_model=
None)[source]¶ Opens a package and reads each resource only on first access.
pkg.resourcesis a lazyResourceStore, and the JSON parts are read up front.dict(pkg.resources),items(), andsave()read every resource, so laziness pays off only when a caller reads a subset, such as just the payload of a document with large media.The package holds a file handle until
close()runs, so open it in awithblock. The method reads a stream eagerly, because its lifetime belongs to the caller.- Parameters:
- Returns:
The package, with its resources still unread.
- Return type:
Self- Raises:
DocumentPackageError–sourceisn’t a valid package, as foropen.DocumentVersionError–sourcedeclares a package or object version this library doesn’t implement.pydantic.ValidationError–main.jsondoesn’t matchpayload_model.ValueError–sourceis a stream that can’t seek.OSError–sourcecan’t be read, such as a path that doesn’t exist.TypeError– neitherpayload_modelnor the class’spayload_modelis set.
-
save(destination, *, validate_resources=
True, pre_save_hooks=())[source]¶ Writes the package to a path as a ZIP archive.
savecalls each hook ashook(self, main), wheremainis the exact value it writes tomain.json. A hook is the only supported way to reach that value, and it must not mutate it.A saved package doesn’t match the one it came from, or an earlier save, byte for byte, but it’s semantically the same.
same_jsoncompares two JSON values while ignoring key order and number spelling, such as1and1.0.- Parameters:
- destination : str | PathLike[str]¶
The destination path.
- validate_resources : bool¶
If
True,savechecks that every indirect resource the payload references resolves inself.resourcesbefore writing anything.- pre_save_hooks : Iterable[Callable[[Package[PayloadT], dict[str, Any]], None]]¶
The functions to call, in order, before the write. A hook that raises stops the save and leaves
destinationuntouched.
- Raises:
ValueError–validate_resourcesis set and the payload references an indirect resource missing fromself.resources, or the presets’parent_identifierchain has a cycle.IsADirectoryError–destinationis an existing directory.savechecks this before calling any hook, and leaves the directory in place.DocumentPackageError– a lazily opened package has a corrupt resource.DocumentVersionError– a union’s only case comes from a preset value too new for this library to read.OSError–destinationcan’t be written, such as a missing parent directory.
Any exception a hook raises propagates unchanged.
- close()[source]¶
Releases the file handle that a lazily opened package holds.
Calling
closeagain does nothing, and so does calling it on an eagerly opened package, sowith Package.open(...) as pkg:is always safe. A lazily opened package keeps only the resources already read, so a latersavedrops the rest or, withvalidate_resources, raises for one the payload references. Save before closing, or read every resource first withdict(pkg.resources).