vibesketch.document.qvf

QVF, the vibyverse’s file format, as vibe-sketch’s document format.

Every program of the vibe family keeps its files as QVF (the qvf repository’s spec/qvf-format-spec.md, toolkit release 0.4). A vibe-sketch QVF holds:

  • a vendor section x_vibesketch.document, not critical, its namespace declared in the manifest’s extensions, with the members document (the vibe-sketch document, schema vibe-sketch/1, drawing included), species (each species’ identifiers, including those without a 3D structure) and sdf (the species as an SD file);

  • a preview (spec § 5.15): a PNG of the species as the thumbnail, at most 1024 pixels on its longest side, and the scheme as SVG;

  • one structure section per species that has a 3D conformer, named structure_<species id>, with its bonds and its identity (§ 5.1): charge, multiplicity, SMILES, InChI, InChIKey, a checked name and the compound number as label;

  • a reaction.scheme (§ 5.14) with the steps whose reactants and products all have a structure section;

  • a job.spec (§ 5.9) for each calculation on such a species, a job set whose jobs name their structure.

So any QVF reader shows the molecules, knows which is which and what the scheme and its calculations are, without knowing vibe-sketch.

Reading takes the document from x_vibesketch.document when there is one. A QVF from another program, such as a vibe-qc result, contributes its structure sections as species: bonds perceived from the 3D coordinates with the charge the section states (or its SMILES implies), a 2D layout for the drawing, the coordinates kept as the conformer, and the section’s multiplicity, label and name. qvf-writer, which provides the qvf_writer and qvf_reader modules, is an optional dependency installed from the qvf checkout.

Module Attributes

EXTENSION_VERSION

The version of the x_vibesketch extension this module writes.

QVF_WRITER_MINIMUM

the qvf extra's floor and CI's QVF_TAG name the same one (tests/test_qvf.py holds them together).

MEDIA_TYPE

QVF's registered media type (the qvf repository's spec/file-type).

Functions

from_qvf(data)

The document a QVF archive holds; raises QvfError.

qvf_available()

Whether qvf-writer is installed, so QVF can be read and written.

species_qvf(document, species_id)

One species as a QVF of its own: one structure with its identity.

to_qvf(document, *[, preview])

The document as a QVF archive; raises QvfUnavailable.

Exceptions

QvfError

A QVF that vibe-sketch cannot read, or cannot write.

QvfUnavailable([found])

qvf-writer is not installed, or is older than the supported toolkit release.
vibesketch.document.qvf.MEDIA_TYPE = 'application/vnd.vibe-qc.qvf+zip'

QVF’s registered media type (the qvf repository’s spec/file-type).

exception vibesketch.document.qvf.QvfError

Bases: ValueError

A QVF that vibe-sketch cannot read, or cannot write.

exception vibesketch.document.qvf.QvfUnavailable(found='QVF needs qvf-writer')

Bases: QvfError

qvf-writer is not installed, or is older than the supported toolkit release.

Parameters:

found (str)

Return type:

None

vibesketch.document.qvf.from_qvf(data)

The document a QVF archive holds; raises QvfError.

Parameters:

data (bytes)

Return type:

Derivation

vibesketch.document.qvf.qvf_available()

Whether qvf-writer is installed, so QVF can be read and written.

Return type:

bool

vibesketch.document.qvf.species_qvf(document, species_id)

One species as a QVF of its own: one structure with its identity.

This is the file a 3D viewer opens. The charge and multiplicity are on the structure section and, as the spec asks of a single structure, in provenance too. Raises KeyError for an unknown species, QvfError for one without a conformer.

Parameters:
Return type:

bytes

vibesketch.document.qvf.to_qvf(document, *, preview=True)

The document as a QVF archive; raises QvfUnavailable.

Parameters:
Return type:

bytes