Concepts¶
Rules that every function of pme.editing follows: where it can run, what it
acts on, what it does not do, and what is stable. Result statuses, guards and
exceptions are described in Results and guards.
Where the functions run¶
The functions run in Blender’s main Python thread after PME has finished loading: the Python Console, the Text Editor, another add-on, or an external tool that runs Python there.
Requirement |
When it is not met |
|---|---|
Blender’s main thread |
|
PME has finished loading |
|
PME preferences exist |
|
A GUI session |
With |
No public function reports PME’s initialization state or waits for it.
A fixed startup delay, or a retry after an arbitrary
RuntimeError, does not prove readiness.PME is ready for authoring code once its Preferences editor is available.
What the functions act on¶
Saved definitions. The functions read and write the menu definitions in PME’s Preferences data in memory, through the same owners as the editor.
Addressed by UID. Every editing function takes UIDs. A name finds a menu (
pme.find_pm()); the UID addresses it afterwards. Renaming a menu keeps its UID.Plain values. Read results are ordinary Python dicts, lists, strings and numbers, not live Blender data (RNA). They do not change when the menu changes.
Session version.
read_pm()["version"]is a counter kept for the current session. It is not saved, and it does not detect every raw Python write. Theexpectedguards compare saved values instead.Unique targets. A menu UID that is missing, malformed, or shared by several saved menus raises
ValueError("Menu UID is missing, invalid or ambiguous: ..."). The functions never pick one of several menus with the same UID. Router and Property Stack operations returnstatus"rejected"with a diagnostic instead.
Other identifiers¶
Identifier |
Format |
Scope |
|---|---|---|
Slot UID |
|
Its menu. A slot is addressed by its menu’s UID and its own UID. |
Context Router branch UID |
Assigned as |
Its Router. |
Context Router condition UID |
Assigned as |
Its Router branch. |
Property Stack condition UID |
Assigned with the prefix |
Its Property Stack. |
Layout |
|
The current head of a row in a Pop-up Dialog or Floating Panel. Not a persistent ID: it is read again after a structural change. |
What the functions do not do¶
Guarantee |
Provided? |
|---|---|
Save Preferences to disk |
No. Changes stay in memory until Blender saves Preferences (Save Preferences, or auto-save). A restart verifies what was saved. |
Add a Blender Undo step |
No. |
Run what was authored |
No. Commands, Custom scripts, Poll, Router conditions and targets are not run, and the menu is not invoked. Reading a Property does not evaluate its Getter or run its Setter. |
Prove that the authored menu works |
No. A committed result describes the saved definition. Display and actions are separate observations in the editor and mode the menu targets. |
Change the selected menu |
No. Menus are addressed by UID, not by the editor selection.
|
Apply a batch atomically |
No. |
Detect concurrent changes |
Only when a guard is passed: |
Update Blender registration |
Yes. Hotkeys, extend targets, Panel Group placement and Property registration are updated inside the call, as in the editor. |
Stability¶
The whole API is Experimental. The basic interface is intended to stay stable. Smaller details can change in future versions.
The compatibility boundary is the UID-addressed operation: its documented inputs, its conflict checks and its observable result.
Internal implementations can change while keeping the saved format and the editor’s normal normalization.
A change to what a failure leaves behind, or to stale detection, is an observable behavior change, even when the function signature stays the same.
Working in batches¶
The result and its diagnostics distinguish completion, rejection, partial application and an unknown outcome (Results and guards).
After an unexpected exception or an
unknownstatus, the target is read again before any retry.An external tool that edits many menus sends small batches and keeps each result and its progress between calls.
A tool timeout does not cancel Blender’s work and does not prove that nothing changed. The running call finishes first; the target menus are then read to decide which changes, if any, to retry.