vibesketch.document.io¶

Read and write .vsk files.

A document is UTF-8 JSON, indented by two spaces, with a trailing newline, so a .vsk diffs cleanly under version control. Writing is atomic: the file is written beside its target and renamed over it, so an interrupted save never leaves half a document.

Module Attributes

`SUFFIX`	The file extension of a vibe-sketch document.
`ABSENT`	What `digest_of()` says of a file that does not exist.

Functions

`check_output`(path)	Refuse a protected QVF destination before an operation with side effects.
`digest_of`(path)	The SHA-256 of a file's bytes, or `ABSENT` when there is no file.
`dumps`(document)	The document as `.vsk` text.
`from_data`(data)	Validate already-parsed JSON data as a document, within `vibesketch.limits`.
`load`(path)	Read and validate a document: a `.qvf` archive or a `.vsk` file.
`loads`(text)	Parse and validate a document from JSON text, within `vibesketch.limits`.
`new_document`([app])	An empty document stamped with this application and the current time.
`save`(document, path, *[, expect])	Write `document` to `path` atomically; returns the path written.
`validation_errors`(error)	Readable `location: message` lines for a pydantic validation error.
`with_edit`(document, *, actor, client, summary)	`document` with an edit recorded for its next revision.
`write_output`(path, content, *[, expect])	Atomically write exported bytes, protecting existing QVF result files.

Exceptions

`DocumentError`(errors)	A document that is not valid JSON or not a valid vibe-sketch document.
`SaveRefused`	Writing would discard QVF result data or replace a changed target.

vibesketch.document.io.ABSENT = 'absent'¶: What digest_of() says of a file that does not exist.

exception vibesketch.document.io.DocumentError(errors)[source]¶

Bases: ValueError

A document that is not valid JSON or not a valid vibe-sketch document.

errors lists every problem as "location: message", the form the CLI prints and the REST API returns.

Parameters:: errors (list[str])
Return type:: None

exception vibesketch.document.io.SaveRefused[source]¶

Bases: ValueError

Writing would discard QVF result data or replace a changed target.

vibesketch.document.io.check_output(path)[source]¶

Refuse a protected QVF destination before an operation with side effects.

write_output() checks again at the actual write; this preflight is useful before submitting jobs whose run records must be saved in place.

Parameters:: path (str | PathLike[str])
Return type:: None

vibesketch.document.io.digest_of(path)[source]¶

The SHA-256 of a file’s bytes, or ABSENT when there is no file.

Parameters:: path (str | PathLike[str])
Return type:: str

vibesketch.document.io.dumps(document)[source]¶

The document as .vsk text.

Parameters:: document (Document)
Return type:: str

vibesketch.document.io.load(path)[source]¶

Read and validate a document: a .qvf archive or a .vsk file.

Parameters:: path (str | PathLike[str])
Return type:: Document

vibesketch.document.io.loads(text)[source]¶

Parse and validate a document from JSON text, within vibesketch.limits.

Parameters:: text (str)
Return type:: Document

vibesketch.document.io.new_document(app=None)[source]¶

An empty document stamped with this application and the current time.

Parameters:: app (str | None)
Return type:: Document

vibesketch.document.io.save(document, path, *, expect=None)[source]¶

Write document to path atomically; returns the path written.

A .qvf path gets a QVF archive (raising QvfUnavailable without qvf-writer), any other a .vsk. A file that exists keeps its permissions; a new one gets the umask’s. QVF results and archives with data outside the native sketch raise SaveRefused; save the sketch to another path instead. With expect (a digest_of()), a file that no longer holds those bytes is not replaced either.

Parameters:

document (Document)
path (str | PathLike[str])
expect (str | None)

Return type:

Path

vibesketch.document.io.validation_errors(error)[source]¶

Readable location: message lines for a pydantic validation error.

Parameters:: error (ValidationError)
Return type:: list[str]

vibesketch.document.io.with_edit(document, *, actor, client, summary)[source]¶

document with an edit recorded for its next revision.

A run of alike edits (same actor, client and summary) folds into one entry, so a drawing session does not leave hundreds. The revision itself is the caller’s to advance: the server’s store does it on commit.

Parameters:

document (Document)
actor (str)
client (str)
summary (str)

Return type:

Document

vibesketch.document.io.write_output(path, content, *, expect=None)[source]¶

Atomically write exported bytes, protecting existing QVF result files.

This also guards explicit format overrides (such as SVG sent to a QVF filename). Symlinks retain their link and write through to their target. With expect, the file must still hold the bytes that digest_of() measured (or still be absent), before writing and again at the rename; otherwise SaveRefused, and the file is left as it is.

The new bytes reach the disk before they replace the old ones, and the directory entry after, so a crash or a full disk leaves either the old file or the new one, never a mixture. A crash at the wrong moment can leave a hidden .NAME.*.tmp beside it, which is safe to delete.

Parameters:

path (str | PathLike[str])
content (bytes)
expect (str | None)

Return type:

Path