vibesketcher.document.build_review¶
Preview, revision-checked apply and undo for periodic build recipes (#201).
vibesketcher.document.solid_build.build() adds a structure directly.
This module puts the same recipes (every kind in AnyRecipe) behind the
preview -> apply -> undo contract of the other reviewed features
(vibesketcher.document.guest_loading,
vibesketcher.document.periodic_prepare):
preview_build()runs the recipe against a document and returns what would be added (formula, site count, cell, builder warnings), refusals with stable codes, the recipe digest and the digests of the document structures and species the recipe reads. The document is not changed.apply_build()adds the structure only when the document revision, the recipe digest and (optionally) the input digest still match the preview. The structure equalsbuild()’s except for aprovenance["build_review"]record that makes it undoable.undo_build()removes such a structure again while it is unchanged since the build and nothing else in the document refers to it.
The document schema does not change: the record lives in the provenance.
Module Attributes
The provenance key of the record an applied build carries. |
|
Stable refusal and notice codes of build preview, apply and undo. |
Functions
|
Add a previewed build to a copy of |
|
Where else the document names periodic structure |
|
Digests of the document structures and species the recipe names. |
|
The would-be structure's summary, refusals and digests; |
|
SHA-256 of the parsed recipe with every default filled in. |
|
What a reviewer reads before adding a structure. |
|
Remove a reviewed build again, while it is unchanged and nothing depends on it. |
Exceptions
|
A preview, apply or undo the build review refuses; |
- vibesketcher.document.build_review.RECORD = 'build_review'¶
The provenance key of the record an applied build carries.
- vibesketcher.document.build_review.CODES: dict[str, str] = {'build.identifier_exists': 'a periodic structure with the new ID already exists', 'build.inputs_changed': 'a structure or species the recipe reads changed since the preview', 'build.invalid': 'the recipe cannot be built as given; the message says why', 'build.recipe_changed': 'the recipe differs from the previewed one', 'build.refused': 'the builder refused these parameters; the message says why', 'build.source_not_found': 'the recipe names a periodic structure the document does not have', 'build.stale_revision': 'the document changed since the preview', 'build.unavailable': 'the recipe needs an optional extra that is not installed', 'build.undo.changed': 'the structure changed after it was built', 'build.undo.dependents': 'other parts of the document refer to the structure', 'build.undo.not_found': 'no periodic structure with that ID', 'build.undo.not_reviewed': 'the structure was not added through a reviewed build', 'build.warning': 'the builder recorded a warning for the result'}¶
Stable refusal and notice codes of build preview, apply and undo.
- exception vibesketcher.document.build_review.BuildReviewRefused(code, message)[source]¶
Bases:
ValueErrorA preview, apply or undo the build review refuses;
codeis stable.
- vibesketcher.document.build_review.recipe_digest(recipe)[source]¶
SHA-256 of the parsed recipe with every default filled in.
Two requests that parse to the same recipe have the same digest, so a client may omit defaults in one and spell them out in the other.
- Parameters:
recipe (CrystalRecipe | CellRecipe | SlabRecipe | AdsorbateRecipe | DefectRecipe | NanotubeRecipe | FrameworkRecipe | RolledNanotubeRecipe | HoneycombStackRecipe | TwistedBilayerRecipe | ReticularRecipe | InterfaceRecipe | StackingFaultRecipe | PorousCarbonRecipe | CntJunctionRecipe)
- Return type:
- vibesketcher.document.build_review.inputs(document, recipe)[source]¶
Digests of the document structures and species the recipe names.
Every string in the recipe (other than its own
identifier) that is the ID of a periodic structure or a species counts as an input; naming one more than the builder reads only makes the check stricter.- Parameters:
document (Document)
recipe (CrystalRecipe | CellRecipe | SlabRecipe | AdsorbateRecipe | DefectRecipe | NanotubeRecipe | FrameworkRecipe | RolledNanotubeRecipe | HoneycombStackRecipe | TwistedBilayerRecipe | ReticularRecipe | InterfaceRecipe | StackingFaultRecipe | PorousCarbonRecipe | CntJunctionRecipe)
- Return type:
- vibesketcher.document.build_review.summary(structure)[source]¶
What a reviewer reads before adding a structure.
- Parameters:
structure (PeriodicStructure)
- Return type:
- vibesketcher.document.build_review.preview_build(document, recipe, *, structure=False)[source]¶
The would-be structure’s summary, refusals and digests;
documentis unchanged.structure=Trueadds the full derived structure asderived(the browser draws it); the summary is always there when the build succeeds.- Parameters:
document (Document)
recipe (CrystalRecipe | CellRecipe | SlabRecipe | AdsorbateRecipe | DefectRecipe | NanotubeRecipe | FrameworkRecipe | RolledNanotubeRecipe | HoneycombStackRecipe | TwistedBilayerRecipe | ReticularRecipe | InterfaceRecipe | StackingFaultRecipe | PorousCarbonRecipe | CntJunctionRecipe)
structure (bool)
- Return type:
- vibesketcher.document.build_review.apply_build(document, recipe, *, recipe_sha256, revision=None, inputs_sha256=None)[source]¶
Add a previewed build to a copy of
document.Refused (
BuildReviewRefused) whenrevisionis given and is not the document’s, when the recipe’s digest is notrecipe_sha256, wheninputs_sha256is given and the inputs changed, or when the preview would refuse. The added structure is the plain build’s plus the recordundo_build()checks.- Parameters:
document (Document)
recipe (CrystalRecipe | CellRecipe | SlabRecipe | AdsorbateRecipe | DefectRecipe | NanotubeRecipe | FrameworkRecipe | RolledNanotubeRecipe | HoneycombStackRecipe | TwistedBilayerRecipe | ReticularRecipe | InterfaceRecipe | StackingFaultRecipe | PorousCarbonRecipe | CntJunctionRecipe)
recipe_sha256 (str)
revision (int | None)
inputs_sha256 (str | None)
- Return type:
- vibesketcher.document.build_review.dependents(document, identifier)[source]¶
Where else the document names periodic structure
identifier.Other structures’
parentand provenance (derived cells, slabs, preparations, loadings, interfaces), surfaces and the solid-state reaction scheme. Each entry is a readable location.