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

status

str

One of the values under Status values. Present in every result.

committed

bool

True only when status is "committed".

dry_run

bool

The dry_run argument. Slot, layout and transfer results do not have this key.

pm_uid

str

The menu UID, in results of most operations on one menu.

before, after

dict or None

Saved values read before and after the call. Shape and presence are described with each function.

expected

dict

The value to pass as expected to a later call, in operations whose guard is a snapshot (Guards).

pending

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.

recovery

dict, str or None

Restore details after a failed write. Shape described with each function.

diagnostics

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¶

status

Meaning

committed

The requested change is saved in memory, as read back after the editor’s normal normalization. For update_slots(), clear_slots() and update_pm(): at least one requested part was saved and none was rejected; single parts can be unchanged. When every part already has the requested value, the result is unchanged.

partial

Part of the request was saved, then a later part was rejected or failed. The parts that were not attempted are in pending. Returned only by update_slots(), clear_slots(), update_pm() and update_property().

validated

dry_run=True and the request passes every check. Nothing was written.

ready

The same as validated, returned by update_hotkey() and delete_pms().

unchanged

The request already matches the saved values. Nothing was written. Router and Property Stack dry runs return validated instead.

rejected

The requested change is not saved. diagnostics names the cause. A slot operation that ran an editor callback can still leave the callback’s changes, shown in after and side_effects.

restored_failure

A write failed. The saved values were written back, and the readback matches the values from before the call. Blender registration is observed separately.

unknown

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:

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 diagnostics or 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

expected_version

The menu’s session-local version (int). Stale code stale_version, with expected and actual.

read_pm()["version"], or version in an earlier slot or layout result.

expected

Saved values, in one of the three forms below.

read_pm(), or expected in an earlier result.

expected_digest

A hash (str) of the saved storage of a Router, Property Stack or Property.

read_pm()["router"]["digest"], read_pm()["property_stack"]["digest"] or read_pm()["property"]["digest"].

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

update_pm() (metadata), update_settings() (settings), update_slots() and clear_slots() (slot UID to slot fields), remove_slot() on menus other than Pop-up Dialog and Floating Panel (the slot’s fields)

Any subset of the keys read_pm() returns for that part. A key whose value differs rejects the call. A key the saved values do not have is stale too, except in update_pm(), which raises ValueError for an unknown field. update_slots() and clear_slots() raise ValueError for a slot UID that is not being edited.

Complete saved values

update_hotkey() (exactly the 13 fields of read_pm()["hotkey"]), set_enabled() (every requested UID mapped to its saved bool)

Missing or extra keys raise ValueError.

Snapshot from an earlier call

add_slot(); remove_slot(), move_slot(), swap_slots() and the row, spacer and panel operations on a Pop-up Dialog or Floating Panel; transfer_slot(), update_tags(), duplicate_pm(), delete_pms()

result["expected"] from an earlier call, usually the dry run, passed back unchanged. Any difference rejects the call.

move_slot() and swap_slots() raise TypeError for expected on menus other than Pop-up Dialog and Floating Panel.

dry_run¶

  • dry_run=True runs 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 (ready for update_hotkey() and delete_pms()), or unchanged where Results by operation lists it.

  • before and after, where present, report saved values, not a prediction. A predicted value, where returned, is proposed (update_hotkey()) or candidate (update_property(), Router and Property Stack operations).

  • The expected of a dry run can be passed to the applying call.

  • The applying call resolves the UIDs and repeats every check. validated does not reserve success and does not test editor hooks, refresh or Blender registration.

  • update_slots(), clear_slots() and update_pm() have no dry_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

pme.create_pm()

accepted is True (object, not a dict)

none

accepted False with diagnostics

none

update_slots(), clear_slots()

committed

no dry_run

unchanged, partial, rejected

expected_version; expected (slot UID to subset of slot fields). stale_version, stale_slot

update_pm()

committed

no dry_run

unchanged, partial, rejected

expected (subset of the metadata). stale_metadata

update_settings()

committed

validated, unchanged

unchanged, rejected, restored_failure, unknown

expected (subset of the settings). stale_settings

update_hotkey()

committed

ready, unchanged

unchanged, rejected

expected (all 13 hotkey fields). stale_hotkey

set_enabled()

committed

validated, unchanged

unchanged, rejected, restored_failure, unknown

expected (UID to saved bool, every target). pm_availability_expected_mismatch

update_tags()

committed

validated; unchanged for an empty request

unchanged, rejected, unknown

expected (snapshot). tag_expected_stale

duplicate_pm()

committed

validated

rejected, restored_failure, unknown

expected (snapshot). pm_duplicate_stale_expected

delete_pms()

committed

ready

rejected, restored_failure, unknown

expected (snapshot). pm_remove_saved_state_stale

read_pm(), read_slot_inputs(), slot_fields(), resolve_auto_icons(), setting_fields(), find_references()

Read-only: no status, nothing is written

none

none

none

add_slot()

committed

validated

rejected; on a Pop-up Dialog or Floating Panel also restored_failure, unknown

expected_version; expected (snapshot). stale_version, stale_snapshot, stale_popup (Pop-up)

remove_slot()

committed

validated

rejected; on a Pop-up Dialog or Floating Panel also restored_failure, unknown

expected_version; expected (the slot’s fields, or a snapshot on a Pop-up). stale_version, stale_slot, stale_popup

move_slot(), swap_slots()

committed

validated, unchanged

unchanged, rejected; on a Pop-up Dialog or Floating Panel also restored_failure, unknown

expected_version; expected (snapshot, Pop-up only). stale_version, stale_popup

transfer_slot()

committed

validated

rejected, restored_failure, unknown

expected (snapshot); no expected_version. stale_transfer

add_row(), add_panel(), remove_row(), split_row(), join_rows()

committed

validated

rejected, restored_failure, unknown

expected_version; expected (snapshot). stale_version, stale_popup

move_row(), update_row(), update_spacer(), align_slot()

committed

validated, unchanged

unchanged, rejected, restored_failure, unknown

expected_version; expected (snapshot). stale_version, stale_popup

update_property()

committed

validated, unchanged

unchanged, partial, rejected, restored_failure, unknown

expected_digest. stale_property

remove_router_branch()

committed

validated

rejected, unknown

expected_digest. stale_router_digest

update_router(), move_router_branch(), reorder_router_branches()

committed

validated

unchanged, rejected, unknown

expected_digest. stale_router_digest

update_property_stack()

committed

validated

unchanged, rejected, unknown

expected_digest. stale_property_stack_digest

add_property_stack_row(), update_property_stack_row(), remove_property_stack_row()

committed

validated

unchanged, rejected, unknown

expected_digest. stale_property_stack_digest

update_property_stack_hud()

committed

validated, unchanged

unchanged, rejected, restored_failure, unknown

expected (subset of while_true_hud). stale_property_stack_hud

Diagnostics¶

diagnostics is a list of dicts. Every entry has code; the other keys depend on the entry.

Key

Present in

Value

code

every entry

Machine-readable identifier, such as stale_settings.

message

most entries

Human-readable description.

field / fields

entries about named inputs

The input name, or a list of names. Stale guards list the differing names in fields.

pmi_uid

slot operations

The slot the entry concerns.

path

Router and Property Stack operations

Location in the input or logic, such as logic.branches[0].target.

severity

some entries

"error" or "warning". Property Stack entries always have it. Elsewhere it marks warnings, such as hotkey collisions, references left after a deletion and unresolved Router menu targets.

exception_type

entries for a caught exception

Class name of the exception. The traceback is printed to Blender’s console.

phase

update_tags(), delete_pms(), set_enabled()

The step that produced the entry, such as preflight or readback.

expected, actual

stale_version

The supplied and the current version.

line, column

invalid_syntax (slot operations)

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. status decides; a committed result can carry diagnostics.

  • Codes specific to a function are listed with that function.

Exceptions¶

Exception

Raised when

Saved state

RuntimeError

Called off Blender’s main thread, before PME finished loading, or without PME preferences (Concepts).

Not touched.

TypeError

An argument has the wrong type, such as changes that is not a mapping or a dry_run that is not a bool.

Not written: raised before the first write.

ValueError

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 TypeError or ValueError after 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:

  • Router and Property Stack operations do not raise for malformed input. They return rejected with a diagnostic such as dry_run_must_be_a_boolean, expected_digest_must_be_a_string or branches_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, return restored_failure or unknown (update_tags(): rejected or unknown), and describe the failure in diagnostics.