Results and guards¶
Every editing function of pme.editing returns a dict. This page defines
what those results share: status values, the guards that reject stale input,
dry_run, diagnostic entries and exceptions. Keys that belong to one function
are described with that function.
The success, preview and stale-input values are named per operation. Results by operation lists them; a caller tests those values rather than one assumed spelling.
Common result keys¶
Key |
Type |
Value |
|---|---|---|
|
str |
One of the values under Status values. Present in every result. |
|
bool |
|
|
bool |
The |
|
str |
The menu UID, in results of most operations on one menu. |
|
dict or None |
Saved values read before and after the call. Shape and presence are described with each function. |
|
dict |
The value to pass as |
|
list |
Parts whose save was not attempted: slot UIDs, metadata field names or Property groups. An earlier step, such as an editor callback, can still have changed them. Pending does not mean unchanged. |
|
dict, str or None |
Restore details after a failed write. Shape described with each function. |
|
list[dict] |
Entries described under Diagnostics. Present in every result. |
pme.create_pm() returns a PmCreationResult object, not a dict:
accepted (bool), pm_uid (str, empty when rejected) and diagnostics
(tuple of code strings). refresh_failed with accepted True means
the menu was created and only the display refresh failed.
update_slots() and clear_slots() also return per-slot
slots, side_effects and structure_changes, described with
update_slots().
Status values¶
|
Meaning |
|---|---|
|
The requested change is saved in memory, as read back after the editor’s
normal normalization. For |
|
Part of the request was saved, then a later part was rejected or
failed. The parts that were not attempted are in |
|
|
|
The same as |
|
The request already matches the saved values. Nothing was written.
Router and Property Stack dry runs return |
|
The requested change is not saved. |
|
A write failed. The saved values were written back, and the readback matches the values from before the call. Blender registration is observed separately. |
|
A write failed and the saved state could not be confirmed. The target is read again before any retry. |
Entries inside a result have their own status:
slotsentries (slot operations) andfieldsentries (update_pm()):committed,unchangedorrejected.groupsentries (update_property()):committed,rejected,restored_failureorunknown.registration(update_hotkey(),set_enabled()):registered,not_required,partialorunknown.visibility(set_enabled()):observedorunknown.
Registration and visibility are observations of Blender’s current state, not the outcome of the operation.
What a committed status covers¶
The saved definition in memory. Preferences are not saved to disk (Concepts).
Not display or action. Readback verifies the saved definition; display and actions are observed separately in the editor and mode the menu targets. For example, a committed Command slot that activates the Knife tool changes the active tool when run; it does not cut geometry by itself.
Not the absence of problems. Diagnostics can accompany
committed: normalization notes, warnings, or a saved definition that still needs attention.A refresh after the save can fail without undoing the commit. The failure is reported in
diagnosticsor in an exception note.
Guards¶
A guard compares the caller’s copy of the saved state with the current state
before anything is written. A mismatch returns status "rejected" with
the operation’s stale diagnostic, listed under
Results by operation.
Input |
Compares |
Value comes from |
|---|---|---|
|
The menu’s session-local version (int). Stale code |
|
|
Saved values, in one of the three forms below. |
|
|
A hash (str) of the saved storage of a Router, Property Stack or Property. |
|
expected_version and expected are independent. version does not
detect every raw Python write; expected compares the saved values and
detects them.
expected_version is accepted by update_slots(),
clear_slots(), add_slot(), remove_slot(),
move_slot(), swap_slots() and the row, spacer and panel
operations. transfer_slot() does not accept it.
Forms of expected¶
Form |
Operations |
Rule |
|---|---|---|
Subset of saved values |
|
Any subset of the keys |
Complete saved values |
|
Missing or extra keys raise |
Snapshot from an earlier call |
|
|
move_slot() and swap_slots() raise TypeError for
expected on menus other than Pop-up Dialog and Floating Panel.
dry_run¶
dry_run=Trueruns the checks of the real call against the current saved values and writes nothing. Saved values, versions and UIDs stay as they were; editor hooks and refresh do not run.An accepted dry run returns
validated(readyforupdate_hotkey()anddelete_pms()), orunchangedwhere Results by operation lists it.beforeandafter, where present, report saved values, not a prediction. A predicted value, where returned, isproposed(update_hotkey()) orcandidate(update_property(), Router and Property Stack operations).The
expectedof a dry run can be passed to the applying call.The applying call resolves the UIDs and repeats every check.
validateddoes not reserve success and does not test editor hooks, refresh or Blender registration.update_slots(),clear_slots()andupdate_pm()have nodry_run.
Results by operation¶
Other statuses lists the values besides the committed and dry-run values. Guard inputs gives the guard parameters and the stale diagnostic code.
Operation |
Committed |
Accepted dry run |
Other statuses |
Guard inputs |
|---|---|---|---|---|
|
none |
|
none |
|
|
no |
|
|
|
|
no |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Read-only: no |
none |
none |
none |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diagnostics¶
diagnostics is a list of dicts. Every entry has code; the other keys
depend on the entry.
Key |
Present in |
Value |
|---|---|---|
|
every entry |
Machine-readable identifier, such as |
|
most entries |
Human-readable description. |
|
entries about named inputs |
The input name, or a list of names. Stale guards list the differing
names in |
|
slot operations |
The slot the entry concerns. |
|
Router and Property Stack operations |
Location in the input or logic, such as
|
|
some entries |
|
|
entries for a caught exception |
Class name of the exception. The traceback is printed to Blender’s console. |
|
The step that produced the entry, such as |
|
|
|
The supplied and the current version. |
|
|
Location of the syntax error in the submitted text. The text is not stripped or reindented before the check. |
A diagnostic does not mean failure by itself.
statusdecides; acommittedresult can carry diagnostics.Codes specific to a function are listed with that function.
Exceptions¶
Exception |
Raised when |
Saved state |
|---|---|---|
|
Called off Blender’s main thread, before PME finished loading, or without PME preferences (Concepts). |
Not touched. |
|
An argument has the wrong type, such as |
Not written: raised before the first write. |
|
An unknown field, an invalid value, conflicting arguments, or a menu UID that is missing, invalid or ambiguous. |
Not written: raised before the first write. |
Any exception after writing started |
A write, editor callback, setter or refresh raised. |
Can be partly changed. The traceback is kept and a note is added. |
An editor or callback can also raise
TypeErrororValueErrorafter writing started. The exception class does not prove that nothing changed. The traceback and notes are kept, and the target is read again before any retry.The note is in the exception’s
__notes__and is printed with the traceback. It names what was committed or what to read:update_slots(),clear_slots(): the committed slot UIDs and the slot being saved.update_pm(): the committed fields and the step that raised.update_hotkey(): the saved readback, the changed fields and the registration readback.add_slot(),remove_slot(),move_slot(),swap_slots()on menus other than Pop-up Dialog and Floating Panel: the slot order before the call.update_property(): whether the saved definition was restored.Router and Property Stack operations: an instruction to read the menu before retrying; Property Stack notes also give the last reported status.
Router and Property Stack operations do not raise for malformed input. They return
rejectedwith a diagnostic such asdry_run_must_be_a_boolean,expected_digest_must_be_a_stringorbranches_must_be_a_sequence.update_settings(),set_enabled(),update_tags(),duplicate_pm(),delete_pms(),transfer_slot()and the slot and layout operations on a Pop-up Dialog or Floating Panel catch a failed write instead of raising. They print the traceback, returnrestored_failureorunknown(update_tags():rejectedorunknown), and describe the failure indiagnostics.