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.

Functions

`dumps`(document)	The document as `.vsk` text.
`from_data`(data)	Validate already-parsed JSON data as a document.
`load`(path)	Read and validate a document: a `.qvf` archive or a `.vsk` file.
`loads`(text)	Parse and validate a document from JSON text.
`new_document`([app])	An empty document stamped with this application and the current time.
`save`(document, path)	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.

Exceptions

DocumentError(errors)

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

exception vibesketch.document.io.DocumentError(errors)¶

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

vibesketch.document.io.dumps(document)¶

The document as .vsk text.

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

vibesketch.document.io.load(path)¶

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)¶

Parse and validate a document from JSON text.

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

vibesketch.document.io.new_document(app=None)¶

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

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

vibesketch.document.io.save(document, path)¶

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.

Parameters:

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

Return type:

Path

vibesketch.document.io.validation_errors(error)¶

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)¶

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