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, see Package.open(), Package.open_lazy(), Package.save(), and Package.close().

Parameters:
payload : PayloadT

The presentation, written to main.json.

presets : list[Preset] | None

The presets, written to presets.json.

manifest : Manifest | None

The manifest, written to manifest.json.

resources : Mapping[str, bytes] | None

The Data/ resources, as a map from filename to bytes.

payload_model

Presentation, the model that main.json is validated against.

property presentation : Presentation

The document’s presentation, decoded from the main JSON file.

presentation and payload return 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 : PayloadT

The document’s root model, written to main.json.

presets : list[Preset] | None

The presets, written to presets.json.

manifest : Manifest | None

The manifest, written to manifest.json.

resources : Mapping[str, bytes] | None

The Data/ resources, as a map from filename to bytes.

payload_model

The model class that open and open_lazy validate main.json against by default. Each subclass sets it. Package sets none, so opening one directly needs payload_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.json at the root of the archive.

Parameters:
source : str | PathLike[str] | BinaryIO

A path to a ZIP package, or an open, seekable binary stream.

payload_model : type[PayloadT] | None

The model class that validates the payload in main.json. Defaults to the class’s payload_model.

Returns:

The package, with every resource already read.

Return type:

Self

Raises:
  • DocumentPackageError – source isn’t a valid package, and kind names the defect.

  • DocumentVersionError – source declares a package or object version this library doesn’t implement.

  • pydantic.ValidationError – main.json doesn’t match payload_model.

  • ValueError – source is a stream that can’t seek.

  • OSError – source can’t be read, such as a path that doesn’t exist.

  • TypeError – neither payload_model nor the class’s payload_model is set.

classmethod open_lazy(source, *, payload_model=None)[source]

Opens a package and reads each resource only on first access.

pkg.resources is a lazy ResourceStore, and the JSON parts are read up front. dict(pkg.resources), items(), and save() 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 a with block. The method reads a stream eagerly, because its lifetime belongs to the caller.

Parameters:
source : str | PathLike[str] | BinaryIO

A path to a ZIP package, or an open, seekable binary stream.

payload_model : type[PayloadT] | None

The model class that validates the payload in main.json. Defaults to the class’s payload_model.

Returns:

The package, with its resources still unread.

Return type:

Self

Raises:
  • DocumentPackageError – source isn’t a valid package, as for open.

  • DocumentVersionError – source declares a package or object version this library doesn’t implement.

  • pydantic.ValidationError – main.json doesn’t match payload_model.

  • ValueError – source is a stream that can’t seek.

  • OSError – source can’t be read, such as a path that doesn’t exist.

  • TypeError – neither payload_model nor the class’s payload_model is set.

save(destination, *, validate_resources=True, pre_save_hooks=())[source]

Writes the package to a path as a ZIP archive.

save calls each hook as hook(self, main), where main is the exact value it writes to main.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_json compares two JSON values while ignoring key order and number spelling, such as 1 and 1.0.

Parameters:
destination : str | PathLike[str]

The destination path.

validate_resources : bool

If True, save checks that every indirect resource the payload references resolves in self.resources before 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 destination untouched.

Raises:
  • ValueError – validate_resources is set and the payload references an indirect resource missing from self.resources, or the presets’ parent_identifier chain has a cycle.

  • IsADirectoryError – destination is an existing directory. save checks 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 – destination can’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 close again does nothing, and so does calling it on an eagerly opened package, so with Package.open(...) as pkg: is always safe. A lazily opened package keeps only the resources already read, so a later save drops the rest or, with validate_resources, raises for one the payload references. Save before closing, or read every resource first with dict(pkg.resources).