Menus¶
Whole-menu operations: create, find, list and invoke menus (pme); read a
menu’s saved definition, change its name, description, Poll, enabled state and
tags, duplicate and delete menus, and find what refers to a menu
(pme.editing). Slots, layout rows, type settings, hotkeys and the
definitions of Properties, Property Stacks and Context Routers have their own
pages. Exporting menus is export_menus() on
Export and validation.
Function |
Purpose |
|---|---|
Creates a menu with the default contents of its type. |
|
Returns a handle to one menu, found by UID or name. |
|
Returns handles to all menus, optionally filtered. |
|
Returns the tag names that menus use. |
|
Requests that a menu opens. |
|
Returns a menu’s saved definition. |
|
Changes the name, description, description format and Poll. |
|
Enables or disables menus. |
|
Adds and removes tag names on menus. |
|
Copies a menu. |
|
Deletes menus. |
|
Lists the saved places that refer to menus. |
Calling rules¶
Menus are addressed by UID. A name can change; find a menu by name with
find_pm()and keep its UID for later calls.Every
pme.editingfunction on this page raisesRuntimeErrorwhen it is called off Blender’s main thread, before PME has finished loading, or when PME’s Preferences are unavailable.No function on this page saves Preferences to disk or adds a Blender Undo step. Only
invoke_pm()opens a menu; no function runs a menu’s actions.statusvalues are defined on Results and guards. General rules for editing are on Concepts.
Menu type identifiers¶
The identifier is the mode_id of PmCreationSpec, the mode
of PMHandle and read_pm()["mode"]. A menu UID starts
with its type’s prefix and _, for example pm_a2b3c4d5. Hotkey tells
whether the type has a hotkey. editable_slots is the value
read_pm() returns: False types are edited with their
own operations, not the slot operations.
|
Name |
UID prefix |
Hotkey |
|
|---|---|---|---|---|
|
Pie Menu |
|
yes |
|
|
Vector Menu |
|
yes |
|
|
Regular Menu |
|
yes |
|
|
Pop-up Dialog |
|
yes |
|
|
Floating Panel |
|
yes |
|
|
Stack Key |
|
yes |
|
|
Panel Group |
|
no |
|
|
Hidden Panel Group |
|
no |
|
|
Sticky Key |
|
yes |
|
|
Macro Operator |
|
yes |
|
|
Modal Operator |
|
yes |
|
|
Property |
|
no |
|
|
Property Stack |
|
no |
|
|
Context Router |
|
yes |
|
Shared result structures¶
Saved menu snapshot¶
duplicate_pm() and delete_pms()
report a menu’s saved state as a detached dictionary. It is the value their
expected digests are computed from.
Key |
Type |
Value |
|---|---|---|
|
dict |
The menu’s saved properties. Its |
|
list[dict] |
One entry per slot: |
|
bool |
Whether Property Stack HUD settings are stored on the menu. |
|
dict |
The Property Stack HUD settings. |
Selection snapshot¶
duplicate_pm(), delete_pms() and
update_tags() report the editor’s menu selection before
and after the call. A snapshot that could not be read is None.
Key |
Type |
Value |
|---|---|---|
|
str or None |
UID of the active menu. |
|
int |
Collection index of the active menu. |
|
list[str] |
UIDs of the selected menus. |
|
bool |
Whether Select Mode is on. |
|
dict or None |
The selected Tree row: |
|
bool or None |
Whether the active menu was in the list region when it last drew.
|
|
str |
|
Finding and invoking menus¶
- pme.find_pm(name=None, *, uid=None)¶
Return a handle to one menu, found by UID or by exact name.
- Parameters:
- Returns:
A handle, or
Nonewhen no menu matches.- Return type:
PMHandleor None
Example
handle = pme.find_pm("Mesh Tools") if handle: pm_uid = handle.uid
Notes
A UID that is not found returns
None. The name is not tried.A UID search returns the first menu with that UID. It does not detect a UID shared by several menus.
Returns
Nonewhen PME’s Preferences are unavailable or pending Tag changes cannot be applied.The handle is a copy taken at the call. It does not follow later changes.
- pme.list_pms(mode=None, *, enabled_only=False)¶
Return handles to all menus in collection order.
- Parameters:
mode (str or None) – A menu type identifier (Menu type identifiers). Only menus of that type are returned.
Nonereturns all types. An unknown identifier returns[].enabled_only (bool) – Return only enabled menus.
- Returns:
One handle per menu.
[]when PME’s Preferences are unavailable or pending Tag changes cannot be applied.- Return type:
list[
PMHandle]
Example
for handle in pme.list_pms(mode="PMENU", enabled_only=True): print(handle.uid, handle.name, handle.tag)
- pme.list_tags()¶
Return the tag names that menus use.
- Returns:
Each used tag name once: in Tag Registry order when the registry is active, otherwise sorted by exact case.
Untaggedis not included.[]when PME’s Preferences are unavailable or pending Tag changes cannot be applied.- Return type:
Example
>>> pme.list_tags() ['Modeling', 'Sculpt', 'UV']
- pme.invoke_pm(pm_or_name=None, *, name=None, uid=None)¶
Request that a menu opens, as its hotkey does.
Truemeans the request was sent without an error. It does not confirm that the menu was displayed or that an action ran.- Parameters:
pm_or_name (
PMHandle, str or None) – A handle or a menu name. Takes precedence overnameanduid. A handle is resolved by itsuid, so it opens the same menu after the menu or another menu is renamed. A handle with an emptyuidis resolved by itsname.name (str or None) – Menu name. Used when
pm_or_nameanduidare not given.uid (str or None) – Menu UID. Used when
pm_or_nameis not given. Takes precedence overname.
- Returns:
Whether the request was sent.
- Return type:
Example
opened = pme.invoke_pm(uid=pm_uid)
Notes
Returns
Falsewithout raising when:no menu matches;
the menu is disabled;
the menu’s Poll or the current context does not allow it;
the call to Blender’s operator raises;
PME is running its startup scripts (
scripts/autorun/,scripts/register/).
- class pme.types.PMHandle(name, mode=None, enabled=True, uid='', tag='')¶
A copy of one menu’s identity, returned by
find_pm()andlist_pms(). Changing its fields changes nothing in PME. The class ispme.types.PMHandle; it is not available aspme.PMHandle.- mode: str or None¶
Menu type identifier (Menu type identifiers).
Creating menus¶
- pme.create_pm(spec, *, request_refresh=None)¶
Create a menu with the default contents of its type.
The menu is created as New in the editor creates it. Its slots and settings are edited afterwards: slots with
update_slots(), type settings withupdate_settings(), a Property withupdate_property().- Parameters:
spec (PmCreationSpec) – The menu to create.
slotsmust be empty anddatamust beNone.request_refresh (callable or None) – Called once with the argument
"global"after the menu is created and the Tree is updated, to redraw the editor.Nonerequests no redraw.
- Returns:
The UID of the new menu, or the rejection codes.
- Return type:
Diagnostics
diagnosticsof the result holds codes, not dictionaries. The checks run in the order of the table. The spec checks report every failing code together. Later checks run only when the earlier ones pass. Every code exceptrefresh_failedmeans that no menu was created.Code
Cause
spec_shape_invalidspecis not aPmCreationSpec, or a field has the wrong type:mode_idornameis not a str,datais not a str orNone,slotsis not a tuple or list, or a slot field is not a str. Reported alone.unknown_modemode_idis not in Menu type identifiers.logic_envelope_mode_unsupportedCONDITIONorROUTERwithslotsordata.slot_count_exceeds_fixedMore slots than the type’s fixed count (
PMENUandVMENU10,STICKY2,CONDITIONandROUTER0).slot_count_below_fixedSTICKYwith one slot.PMENUandVMENUaccept fewer slots.data_marker_mismatchThe part of
databefore?is not the type’s data marker.data_query_malformedA pair after
?indatais notkey=value.unknown_slot_modeA slot’s
modeis notEMPTY,COMMAND,PROP,MENU,HOTKEY,CUSTOM,INVOKE,FINISH,CANCELorUPDATE.slots_unsupported_by_create_pmslotsis not empty.data_unsupported_by_create_pmdatais notNone.boot_worker_thread_unsupportedCalled off Blender’s main thread while PME runs its startup scripts.
boot_refresh_callback_unsupportedrequest_refreshgiven while PME runs its startup scripts.route_pm_identity_*The saved menus fail the UID check, for example
route_pm_identity_uid_duplicatewhen several menus share a UID.route_target_rejectedThe creation target could not be prepared.
route_dry_run_rejectedThe menu collection changed, or the new UID collided, between preparation and writing.
route_apply_failedCreating the menu raised. The added entry was removed again. The original exception is printed to Blender’s console.
route_receipt_invalidThe creation step returned no valid result.
refresh_failedNot a rejection:
acceptedisTrue. The menu was created, but the Tree update orrequest_refreshraised. The exception is printed to Blender’s console.Example
created = pme.create_pm(pme.PmCreationSpec(mode_id="VMENU", name="Mesh Tools")) print(created.accepted, created.pm_uid, created.diagnostics) if created.accepted: menu = pme.editing.read_pm(created.pm_uid)
Notes
accepted=Truemeans the menu exists in Preferences. It does not mean that Preferences were saved to disk, that the menu was invoked, or that it is available at run time immediately.After
refresh_failed, read the returned UID instead of creating the menu again.Placement, Auto Tag and keymap inheritance follow New in the editor with the current list state. The new menu becomes the active menu.
An empty
nameuses the type’s default name. A name that is in use receives a suffix such as.001.A request rejected before the
route_*checks does not read or change Preferences.From a startup script on the main thread, only the saved menu is created: no hotkey or editor registration and no display refresh run in the call.
- class pme.PmCreationSpec(mode_id, name='', slots=(), data=None)¶
Frozen dataclass describing a menu for
create_pm().- mode_id: str¶
Menu type identifier (Menu type identifiers).
- slots: tuple[PmiSlotSpec, ...]¶
Slots of the menu.
create_pm()accepts only an empty tuple.
- data: str or None¶
The raw saved settings string, in the form of
read_pm()["data"].create_pm()accepts onlyNone.
- class pme.PmiSlotSpec(mode='EMPTY', name='', text='', icon='')¶
Frozen dataclass describing one entry of
PmCreationSpec.slots.create_pm()rejects a spec with slots (slots_unsupported_by_create_pm); add and edit slots after creation.
- class pme.PmCreationResult(accepted, pm_uid, diagnostics)¶
Frozen dataclass returned by
create_pm(). Also available aspme.types.PmCreationResult.- diagnostics: tuple[str, ...]¶
Rejection codes,
("refresh_failed",)after a creation whose display refresh failed, or(). Seecreate_pm().
Reading a menu¶
- pme.editing.read_pm(pm_uid, *, slot_uids=None)¶
Return one menu’s saved definition as plain Python values.
Reading runs nothing: no Poll, description expression, Getter or Setter is evaluated, and tags are not synchronized.
- Parameters:
- Returns:
The definition described below.
- Return type:
- Raises:
ValueError – The UID is missing, invalid or ambiguous, or a UID in
slot_uidsis not a slot of the menu.
Result
Key
Type
Present for
Value
uidstr
all
UID of the menu.
namestr
all
Menu name.
modestr
all
Menu type identifier (Menu type identifiers).
enabledbool
all
Whether the menu is enabled.
descriptionstr
all
The menu’s description, or the expression that returns it.
description_is_exprbool
all
Truewhendescriptionis a Python expression.poll_cmdstr
all
Poll source, the body of
def poll(cls, context):. Seeupdate_pm().tagslist[str]
all
Tag names in the saved tag text, sorted, each once.
[]for an untagged menu.hotkeydict
all
The saved hotkey binding. See Hotkeys.
datastr
all
The raw saved settings string: the type’s marker, then
?andkey=valuepairs joined by&. Read values fromsettings.settingsdict
all
Setting name mapped to its current value.
{}for a type without settings. See Menu type settings.settings_diagnosticslist[dict]
unreadable
dataPresent only when
datacannot be parsed. One entry with the codesettings_data_unreadable;settingsis then{}. See Menu type settings.versionint
all
The menu’s edit counter, passed as
expected_versionto slot and layout operations. Session-local;0when the menu has no version yet. It does not detect every raw Python write.editable_slotsbool
all
Falsefor types edited with their own operations (Menu type identifiers).slotslist[dict]
all
One entry per slot in saved order, or only the slots named in
slot_uids. Each entry is described in Slot snapshot.rowslist[dict]
DIALOG,FPANELThe layout rows, always complete. See Rows.
routerdict
ROUTERThe Context Router definition. See Context Router.
property_stackdict
CONDITIONThe Property Stack definition. See Property Stack.
propertydict
PROPERTYThe Property definition. See Property.
Example
menu = pme.editing.read_pm(pm_uid) print(menu["mode"], menu["name"], [slot["uid"] for slot in menu["slots"]])
Notes
The returned values are detached copies. Changing them changes nothing.
A slot’s
textis the stored text.read_slot_inputs()returns the same slots under the input names thatupdate_slots()accepts.tagsreads the saved tag text without synchronization. A saved empty-name membership ("") and a literal"Untagged"stay distinct.PMHandle.tag,list_tags()andPMItem.get_tags()keep their own formats.
Name, description and Poll¶
- pme.editing.update_pm(pm_uid, changes, *, expected=None)¶
Change a menu’s name, description, description format or Poll source.
Fields are saved one at a time; the call is not atomic. The first rejected field stops the sequence. Fields saved before it stay saved.
- Parameters:
pm_uid (str) – UID of the menu.
changes (dict) – Field name mapped to its new value. Accepted names:
name,description,description_is_expr,poll_cmd. Fields that are not named keep their values.expected (dict or None) – Field name mapped to the value it must have now. Any subset of the four fields. On a mismatch nothing is written (
stale_metadata).
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
changesorexpectedis not a mapping,description_is_expris not a bool, or another value is not a str.ValueError – A field name is not one of the four, a string contains a NUL character or text that cannot be encoded as UTF-8, or the UID is missing, invalid or ambiguous.
Result
Key
Type
Value
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".pm_uidstr
The
pm_uidargument.beforedict
The four fields read before the call.
afterdict
The four fields read after the call.
changed_fieldslist[str]
Fields whose value differs between
beforeandafter, including changes made by editor callbacks.fieldslist[dict]
One entry per attempted field, in save order:
field,status(committed,unchangedorrejected),before,afteranddiagnostics.pendinglist[str]
Fields that were not attempted.
side_effectslist[dict]
Present only when
nameis inchangesand a slot of any menu changed. One entry per slot:pm_uid,pmi_uid,before,after.diagnosticslist[dict]
The diagnostics of all fields, or the
stale_metadataentry.Status
statusMeaning
committedAt least one field was saved and none was rejected. Other fields can be
unchanged.unchangedEvery field already had the requested value, or
changesis empty. Nothing was written.partialA field was rejected after an earlier field or a callback changed saved values. Inspect
fields,pending,before/afterandside_effectsbefore retrying.rejectedNothing changed:
expecteddid not match, or a field was rejected before any value changed.Diagnostics
codeCause, and extra keys
stale_metadataA value in
expecteddiffers from the saved value.fieldslists the names.rename_rejectedThe editor kept the old name for a different, non-empty name.
name_adjustedThe saved name differs from the requested one:
@was removed, or a suffix such as.001was added because the name is in use.requestedandactualgive both names.metadata_value_not_retainedA setter did not keep the requested
description,description_is_exprorpoll_cmd.poll_compile_errorpoll_cmdwas saved but does not compile.messagegives the error. The field status is not changed by this diagnostic.Example
Add a plain-text menu description, checking that the four fields are unchanged since they were read:
before = pme.editing.read_pm(pm_uid) fields = ("name", "description", "description_is_expr", "poll_cmd") result = pme.editing.update_pm(pm_uid, { "description_is_expr": False, "description": "Mesh tools. Unmatched contexts keep Blender's shortcut.", }, expected={key: before[key] for key in fields}) print(result["status"], result["after"], result["diagnostics"])
Notes
When both
descriptionanddescription_is_exprare given,description_is_expris saved first, so the format conversion does not rewrite the supplied description. Other editor callbacks can also change saved values; they appear inchanged_fields.Renaming uses the editor’s rename: Menu slots that link the menu, Panel Group items named after a renamed Pop-up Dialog, the Tree and hotkey registration are updated. Command, Custom and Poll source text and a Router target’s
fallback_nameare not rewritten and not listed inside_effects; name-based calls in them keep the old name.@is removed from a requested name. An empty name, or the current name, leaves the name unchanged.Renaming a Property Stack whose Property ID is not locked can generate a new ID. Read
property_stack["registered_property_id"]again after renaming; widgets that embed the old ID are not rewritten.poll_cmdis appended todef poll(cls, context):. A single-line body such as"return context.mode == 'EDIT_MESH'"is valid as it is. A multi-line body starts with a newline and indents its lines.Poll source that does not compile is saved, as in the editor, with
poll_compile_error. Slotcmd,propandcustomsyntax errors are instead rejected before the slot is saved. Neither check proves run-time behavior.Enabled state, hotkeys and type settings are not fields of this function. The Poll and description sources are not evaluated.
An unexpected exception keeps its traceback and gains a note naming the committed fields. Read the menu and the menus that refer to it before retrying.
Enabling and disabling¶
- pme.editing.set_enabled(pm_uids, enabled, *, expected=None, dry_run=False)¶
Enable or disable menus, as the editor’s batch Enable and Disable do.
All targets are checked before the first write. If a write fails, the enabled values already written are restored.
- Parameters:
pm_uids (non-string iterable of str) – Unique menu UIDs. Targets are processed in collection order. An empty iterable returns
unchanged.enabled (bool) – The value for every target.
expected (dict[str, bool] or None) – Each requested UID mapped to the saved value it must have now; exactly the requested UIDs. On a mismatch the call is rejected before writing.
Noneuses the values read at the start of the call.dry_run (bool) – Check and return without writing.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
enabledordry_runis not a bool (an int is not accepted),pm_uidsis a string, orexpectedis not a mapping of bools.ValueError –
pm_uidscontains an invalid or duplicate UID, orexpecteddoes not name exactly the requested UIDs.
Result
Key
Type
Value
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".dry_runbool
The
dry_runargument.target_uidslist[str]
The targets in collection order, or as given when they could not be resolved.
beforedict[str, bool]
Saved values at the start of the call.
{}when the targets could not be resolved.afterdict[str, bool]
Values read after the call. A target that could not be read is omitted and named in
diagnostics. After a dry run, the current values.expecteddict[str, bool]
A copy of
before, to pass asexpected. It is not the new state, also after a commit.planned_uidslist[str]
Targets whose saved value differs from
enabled.attempted_uidslist[str]
Targets whose setter was called.
[]after a dry run.changed_uidslist[str]
Targets changed by the call.
[]after a dry run and after a confirmed restore.registrationdict[str, dict]
Per target, the hotkey registration observed after the call:
scope("hotkey"),status(not_required,registered,partialorunknown),required,lanesanddiagnostics. See Hotkeys.selectiondict
beforeandafter:active_pm_uid,active_index,selected_pm_uids,select_mode_active,tree_cursorandmode, orNonewhen unreadable.visibilitydict
beforeandafter:scope("last_rendered_region"),status(observedorunknown),visible_uidsandtargets(UID mapped to bool orNone).owner_statusstr
Status of the shared batch operation:
APPLIED,VALIDATED,NO_CHANGE,REJECTED,RESTORED_FAILUREorROLLBACK_FAILED.reasonstr
The rejection or failure code.
""when there is none.rollback_reasonstr
Why a restore was not confirmed.
""when there is none.diagnosticslist[dict]
See Diagnostics below.
Status
statusMeaning
validateddry_run=Trueand at least one value would change. Nothing was written.unchangedEvery target already has the value, or
pm_uidsis empty. No setter ran and hotkey registration was not repaired.committedEvery value was written and read back.
rejectedNothing was written.
diagnosticsnames the cause.restored_failureA write failed and the restored enabled values were confirmed.
unknownA write failed and the restore could not be confirmed. Read the menus before retrying.
Diagnostics
The rejection or failure entry has
code(thereason) androllback_reason.codeCause, and extra keys
pm_availability_target_missingA UID is not in the menu collection.
pm_availability_live_identity_invalidThe saved menus fail the UID check, for example when several menus share a UID. The check covers the whole collection, not only the targets.
pm_availability_expected_mismatchA value in
expecteddiffers from the saved value.beforeholds the saved values.pm_availability_target_state_unavailableA target’s enabled value could not be read.
pm_availability_collection_staleThe menu collection changed during the call. Also a
rollback_reason.pm_availability_target_staleA target’s value changed before its write.
pm_availability_apply_failedA setter raised.
pm_availability_apply_readback_mismatchA setter did not keep the value.
pm_availability_post_apply_mismatchThe final read differs from the requested value.
pm_availability_rollback_incompleteOnly as
rollback_reason: the restored values could not all be confirmed.pm_availability_target_unavailableAfter the call, a target could not be resolved.
pm_uid,phaseandreason(the resolver status).pm_availability_readback_unavailableReading a target after the call raised.
pm_uid,phase,exception_type.pm_availability_registration_unavailableReading a target’s hotkey registration raised.
pm_uid,phase,exception_type.pm_availability_context_unavailableSelection and visibility could not be read.
phase(beforeorafter),exception_type.Example
preview = pme.editing.set_enabled([pm_uid], False, dry_run=True) print(preview["status"], preview["before"], preview["planned_uids"]) if preview["status"] == "validated": result = pme.editing.set_enabled( [pm_uid], False, expected=preview["expected"], ) print(result["status"], result["after"], result["registration"]) print(result["diagnostics"])
Notes
committedconfirms the saved enabled values only.registrationreports the current hotkey state. It does not check Macro, Property, Property Stack or Panel resources, Poll, Getter or Setter, or whether actions run. A registration warning orunknownobservation does not change a committedstatus.A disabled menu, a menu without a key, a type without a hotkey and a Vector Menu with Open Mode
CLICKrequire no hotkey registration (not_required).After a dry run,
registrationis the current registration, not a prediction.A dry run does not reserve the targets or prove that their callbacks will succeed. A later call resolves and checks again.
A restore covers enabled values only, not other saved fields or editor resources. After a failure, read
before,after,attempted_uids,changed_uids,reason,rollback_reasonanddiagnosticstogether.The selection, open drafts (also one owned by a target) and list filters stay as they are, even when a target becomes hidden.
visibilityis the last-rendered region’s evidence, can beunknown, and does not prove that a new frame has drawn.
Tags¶
- pme.editing.update_tags(pm_uids, *, add=(), remove=(), expected=None, dry_run=False)¶
Add and remove tag names on several menus in one batch.
The call has two phases: the normal Tag synchronization, then the batch write that the editor’s tag operations use. They are not one atomic transaction.
- Parameters:
pm_uids (non-string iterable of str) – Unique menu UIDs.
add (non-string iterable of str) – Names to add. Each is trimmed. A comma separates several names. An empty name and
Untaggedare ignored and listed inignored_names.remove (non-string iterable of str) – Exact names to remove. Not trimmed, not split at commas.
expected (dict or None) – The complete
expectedof an earlier result of this function, passed unchanged:activated,targets_digestanddefinitions_digest. It is compared before synchronization.dry_run (bool) – Check and return without synchronizing or writing.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
dry_runis not a bool,pm_uids,addorremoveis a string or contains a non-string, orexpected["activated"]is not a bool.ValueError –
pm_uidscontains an invalid or duplicate UID, a UID is missing or ambiguous,removecontains a name twice, a name occurs twice acrossaddor in bothaddandremove, orexpectedis not a mapping with exactly the three keys or has a digest that is not a lowercase SHA-256 hex string.
Result
Key
Type
Value
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".dry_runbool
The
dry_runargument.target_uidslist[str]
The
pm_uidsargument.expecteddict or None
activated,targets_digestanddefinitions_digestof the state read at the start.Nonewhen that read failed.beforedict or None
Per target, read before synchronization:
raw(saved tag text),tags,ref_uidsandprojection_stamp.afterdict or None
The same keys, read after the call.
Nonewhen unreadable.changed_uidslist[str] or None
Targets whose values differ between synchronization and the final read.
Noneafter a failed phase.synchronizeddict or None
Changes made by the normal synchronization, to any menu or tag definition:
pms,definitions,versionandactivated, as present. Can be set whenstatusisunchanged.ignored_nameslist[dict]
Per ignored
addentry:nameandreason("legacy_add_noop").selectiondict
beforeandafter: a selection snapshot withactive_hidden_by_list_filterandlist_filter_scope("mode_tag_new_health").recoverydict or None
Set after a failed phase:
phase,baseline,carrier_matches,attempted(None) andscope("tag_carrier").diagnosticslist[dict]
See Diagnostics below.
Status
statusMeaning
validateddry_run=True, there are targets and changes, andexpectedmatches. Nothing was written.unchangedThere are no targets, or neither
addnorremovehas an entry, or the batch write changed no menu. Inspectsynchronizedseparately.committedThe batch write changed at least one menu.
rejectedSaved tag data is unchanged:
expectedis stale, the start state could not be read, or synchronization failed and the saved tag data still equalsbefore.unknownThe batch write failed, or synchronization failed and the saved tag data differs from
beforeor could not be read. Read the values before retrying.Diagnostics
Each entry has
phaseandcode. Entries caused by an exception also haveexception_typeandmessage.codeCause
tag_expected_staleexpecteddiffers from the current state. Phasepreflight.tag_snapshot_failedThe tag data could not be read at the start.
tag_update_failedSynchronization or the batch write raised. Phase
synchronizeorbatch. An exception that carries its own code reports that code instead.tag_carrier_readback_failed,tag_targets_readback_failedThe values after the call could not be read.
tag_synchronization_readback_failedThe synchronization changes could not be read after a failure.
tag_selection_readback_failed,tag_filter_readback_failedThe selection or the list filter state could not be read.
refresh_pendingThe display refresh was deferred. Phase
refresh.tag_refresh_failedThe display refresh raised. Phase
refresh.Example
targets = [first_pm_uid, second_pm_uid] preview = pme.editing.update_tags( targets, add=["Review"], remove=["Draft"], dry_run=True, ) if preview["status"] == "validated": result = pme.editing.update_tags( targets, add=["Review"], remove=["Draft"], expected=preview["expected"], ) print(result["status"], result["after"], result["synchronized"]) print(pme.editing.read_pm(first_pm_uid)["tags"])
Notes
The batch uses the editor’s tag writer, with the Tag Registry active or inactive. It does not delete tag definitions.
Names keep their case and Unicode.
add=["A,B"], remove=["B"]is a conflict (ValueError). Ignored additions still take part in the duplicate checks. There is no additional name-length limit.The write can normalize the order and duplicates of the saved tag text even when the set of names does not change, for example for an existing membership or a missing removal. Compare the saved values, not name sets.
expectedsurvives a JSON round trip. It covers the targets’ saved tag text, references and projection stamps and the registry definitions. A staleexpectedis rejected without writing.A dry run checks the inputs, the targets and the name transformation. It does not synchronize, allocate UIDs or predict new definitions, and does not prove that a later write succeeds.
Empty changes or an empty target set return
unchangedafter theexpectedcheck, without synchronization or refresh.recovery.carrier_matchescompares saved tag data withbaseline:"before"when synchronization failed,"after_synchronize"when the batch write failed.Trueproves equality of saved data only.attemptedisNonebecause rollback execution is not known; a match is not reported asrestored_failure.A failed readback or refresh after a successful batch write does not change a committed result.
The active menu, the selected menus and the open draft stay as they are. The same Tree row stays selected when it is still available and the refresh succeeds.
active_hidden_by_list_filteris the current mode, tag, new and health filter result, without name search and collapsed rows;Nonewhen unknown.
Duplicating¶
- pme.editing.duplicate_pm(source_pm_uid, *, name=None, expected=None, dry_run=False)¶
Copy one menu and insert the copy immediately after its source.
The copy is made by the editor’s Duplicate. The active menu, the selection and the open draft stay as they are; the editor’s Duplicate selects the copy, this function does not.
- Parameters:
source_pm_uid (str) – UID of the menu to copy.
name (str or None) – Name of the copy.
Noneor""uses the source name as the base. The name goes through the unique-name step without trimming.expected (dict or None) – The complete
expectedof a dry run, passed unchanged:collection_version,source_pm_uidandsource_digest.dry_run (bool) – Check and return without writing.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
source_pm_uidis not a non-empty str,nameis not a str orNone,dry_runis not a bool,expectedis not a mapping, or one of its values has the wrong type.ValueError –
expecteddoes not have exactly the three keys, or itscollection_versionis negative.
Result
Key
Type
Value
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".dry_runbool
The
dry_runargument.source_pm_uidstr
The
source_pm_uidargument.createddict or None
pm_uid,nameand collectionindexof the copy.Noneafter a dry run or when no copy exists.beforedict
pm_uids(collection order),source(a saved menu snapshot) andcreated(alwaysNone).afterdict
The same keys, read after the call.
createdis the copy’s saved snapshot.expecteddict or None
collection_version,source_pm_uidandsource_digest.Nonewhen the source could not be read.collection_version_before,collection_version_afterint or None
Version of the menu collection before and after the call.
selection_before,selection_afterdict or None
not_inheritedlist[str]
key,any,ctrl,shift,alt,oskey,key_mod,enabled.recoverydict
attempted(False,TrueorNonewhen unknown), anduid_order,active_uidandsource_digest: whether each equals its value before the call (bool orNone).data_scopeis"collection_order_active_uid_source_saved_values".diagnosticslist[dict]
See Diagnostics below.
Status
statusMeaning
validateddry_run=Trueand the checks passed. Nothing was written.rejectedNothing was written.
diagnosticsnames the cause.committedThe Duplicate committed.
restored_failureThe Duplicate failed. The original UID order, active UID and source saved values were read back unchanged.
unknownThe outcome or the recovery could not be confirmed. Read the collection before retrying.
Diagnostics
codeCause, and extra keys
pm_identity_*The saved menus fail the UID check, for example
pm_identity_uid_duplicatewhen several menus share a UID.pm_duplicate_source_unavailableNo menu has
source_pm_uid.pm_duplicate_unsupported_modeThe source’s type is not a known menu type.
pm_duplicate_stale_expectedexpecteddiffers from the current collection version or source.pm_duplicate_snapshot_failedReading the state at the start raised.
exception_type,message.target_rejected,dry_run_rejectedThe Duplicate refused before writing, for example because the collection or the source changed.
statusisrejected.apply_failedThe Duplicate raised while writing and ran its rollback.
statusisrestored_failureorunknown.pm_duplicate_failedThe Duplicate raised outside its own handling.
statusisunknown.exception_type,message.pm_duplicate_refresh_failedAfter the commit, the display refresh or the Tree selection restore failed. The commit stands.
pm_duplicate_readback_failedA value after the call could not be read; it is
None.field,exception_type,message.pm_duplicate_readback_unavailableThe source or the copy could not be resolved after the call.
field.Example
preview = pme.editing.duplicate_pm(pm_uid, name="Working copy", dry_run=True) print(preview["status"], preview["not_inherited"]) if preview["status"] == "validated": result = pme.editing.duplicate_pm( pm_uid, name="Working copy", expected=preview["expected"], ) print(result["status"], result["created"], result["diagnostics"])
Notes
The copy is placed after its source in collection order, whatever the active menu or the displayed sort order.
The copy and its slots receive new UIDs. Slot contents, slot
enabled, tags and the editor’s type-specific copy behavior are kept. References in the copy keep their targets.The fields in
not_inheritedare not copied: the copy starts enabled, without a hotkey key.A Property Stack copy keeps the HUD appearance with monitoring off, and does not reuse the source’s Property ID.
A dry run creates no UID, initializes no version, changes no selection, registers nothing and writes no HUD settings. It does not reserve a name or fix the collection order.
expectedsurvives a JSON round trip. It covers the source’s saved values, including edits that do not update a version, and the collection version.The same Tree row stays selected when it still exists. A copy hidden by a filter does not cause another menu to be selected.
A failed refresh or readback does not undo a confirmed commit.
recoverycovers only the Duplicate’s own rollback and its saved-data checks, not editor registration or host resources.
Deleting¶
- pme.editing.delete_pms(pm_uids, *, expected=None, dry_run=False)¶
Delete menus, as the editor’s Selected Remove does.
References to the deleted menus are reported, not removed or rewritten. A surviving menu can keep a link to a deleted menu.
- Parameters:
pm_uids (non-string iterable of str) – One or more unique menu UIDs, including a one-element list for one menu. Targets are processed in collection order.
expected (dict or None) – The complete
expectedof a dry run, passed unchanged:collection_version,collection_digest,target_digestsandreferences_digest.Noneuses the state read at the start of the call.dry_run (bool) – Check and return without deleting.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
pm_uidsis a string, ordry_runis not a bool.ValueError –
pm_uidsis empty or contains an invalid or duplicate UID, orexpectedis malformed: missing keys, a negativecollection_version,target_digestskeys other than the requested UIDs, or a digest that is not a lowercase SHA-256 hex string.
Result
Key
Type
Value
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".dry_runbool
The
dry_runargument.target_uidslist[str]
The targets in collection order, or as given when they could not be resolved.
beforedict
Per target, a saved menu snapshot read at the start.
{}when the targets could not be resolved.afterdict
Per target, the snapshot after the call:
Nonefor a removed target,{"readback_unavailable": True}when unreadable.referenceslist[dict]
Reference rows that point to the targets or could not be read, with
source_survivesandtarget_missing_after.expecteddict or None
The four preconditions of the state read at the start.
Nonewhen that read failed.removed_uidslist[str]
Targets no longer in the collection.
[]when rejected.remaining_target_uidslist[str]
Targets still in the collection.
remaining_uidslist[str] or None
The final collection order.
collection_version_before,collection_version_afterint
Version of the menu collection before and after the call.
selection_before,selection_afterdict or None
planned_active_uidstr or None
The menu planned to be active after the deletion.
Nonewhen the deletion was not planned.recoverydict
status(APPLIED,REJECTED,RESTORED_FAILUREorBLOCKED_RECOVERY),rollback_attempted,rollback_confirmed,rollback_reason,rollback_exception_type,data_scope("owned_menu_saved_values"),host_scope("existing_batch_recovery_postconditions") andhotkey_observation.diagnosticslist[dict]
See Diagnostics below.
Status
statusMeaning
readydry_run=Trueand the checks passed. Nothing was removed.rejectedNothing was removed.
diagnosticsnames the cause.committedThe requested menus were removed from the collection.
restored_failureThe deletion failed and the deletion’s own recovery was confirmed.
unknownThe recovery could not be confirmed, or a target remains or the final read failed after the removal. Read the collection before retrying.
Diagnostics
Every result contains
static_reference_coverage(severity"warning"). Each reference row with awarningadds an entry withcode(the warning),severity,source_pm_uidandpath. A rejection or failure adds an entry withcode,phaseandexception_type.codeCause
static_reference_coverageAlways present. Python that builds a reference at run time cannot be found.
pm_remove_target_missingA UID is not in the menu collection.
pm_remove_live_identity_invalidThe saved menus fail the UID check, for example when several menus share a UID.
pm_remove_host_name_ambiguousAnother menu has the same name as a target.
pm_remove_active_invalidThe active menu index is not valid.
pm_remove_plan_invalidThe selection state or the collection version cannot be used to plan the deletion.
pm_remove_draft_conflictAn open draft belongs to a target.
pm_remove_saved_state_staleexpecteddiffers, or a target’s saved values or the references to it changed during the call.pm_remove_collection_staleThe collection, its version or the selection changed during the call.
pm_remove_target_changedA target’s name, type or position changed before its removal.
pm_remove_snapshot_failedReading the state at the start raised.
pm_remove_apply_failedRemoving a menu raised.
pm_remove_apply_readback_mismatchA removal could not be confirmed by reading the collection.
pm_remove_terminal_failedSetting the final active menu and selection failed.
pm_remove_version_commit_failedThe collection version could not be updated after the removal.
pm_remove_readback_failedThe final read raised.
pm_remove_hotkey_readback_failedrecovery.hotkey_observationcould not be read.pm_remove_refresh_failedA display refresh step raised after the removal.
phasenames the step. The commit stands.pm_remove_recovery_publish_failedA refresh step after a failed recovery raised.
recovery.rollback_reasonispm_remove_rollback_failed(the restored collection or selection differs),pm_remove_host_recovery_unproven(a hotkey or Floating Panel teardown had started), orpm_remove_version_commit_failed.Example
preview = pme.editing.delete_pms([pm_uid], dry_run=True) print(preview["status"], preview["references"], preview["diagnostics"]) if preview["status"] == "ready": result = pme.editing.delete_pms([pm_uid], expected=preview["expected"]) print(result["status"], result["removed_uids"], result["recovery"])
Notes
A dry run changes no saved value, version, selection, draft or host registration.
beforeandafterhold the same values. It returnsplanned_active_uid. It does not reserve the targets or prove that teardown will succeed.expectedcompares the collection’s identity and order, the targets’ saved contents and the saved references to the targets. It detects changes that do not increment the collection version. A stale result needs a new read and a new decision. Withoutexpected, the state at the start is still checked again before each target is removed.referencesincludes Router and Property Stack references that are disabled or incomplete. Python that builds a reference at run time is not found; coverage warnings do not prevent deletion.An open draft of another menu stays intact. An active menu outside the targets keeps its UID. When the active menu is deleted, the next surviving menu after it becomes active, or else the nearest one before it. Filters are not cleared to show a surviving menu.
Recovery of saved data and recovery of host registration are separate: a restored definition does not prove that every editor resource was restored. A failed display refresh after the deletion keeps the committed result.
recovery.hotkey_observationcovers the deletion checkpoint and PME’s own hotkey records only. An absent record does not prove that every Blender keymap item or other editor resource was removed.
References¶
- pme.editing.find_references(pm_uids)¶
List the saved places that refer to the given menus.
Nothing is written. Only static references in saved data are read. An empty result means that no supported reference was found, not that the menu is unused.
- Parameters:
pm_uids (non-string iterable of str) – Unique menu UIDs.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
pm_uidsis a string.ValueError – A UID is invalid or listed twice, or a UID is missing or shared by several saved menus.
Result
Key
Type
Value
target_uidslist[str]
The
pm_uidsargument.referenceslist[dict]
Reference rows whose
target_uidis one of the targets.unscannablelist[dict]
Rows from every menu, not only the targets, whose content could not be read statically.
target_uidisNone.Example
found = pme.editing.find_references([pm_uid]) for row in found["references"]: print(row["kind"], row["source_pm_name"], row["path"]) if found["unscannable"]: print("Possibly referenced:", len(found["unscannable"]), "unreadable places")
Notes
The rows are those of the
delete_pms()preview, withoutsource_survivesandtarget_missing_after.Treat a menu as possibly referenced while
unscannableis not empty.
Reference rows¶
Every row has these keys:
Key |
Type |
Value |
|---|---|---|
|
str |
|
|
str |
The menu that holds the reference. |
|
bool |
Whether that menu is enabled. |
|
str or None |
The referenced target. |
|
list |
Location in the source menu: |
|
any |
The saved value at |
|
str |
On slot rows and |
|
bool |
|
|
bool |
|
Rows from slots also have source_pmi_uid. menu_reference,
text_call and text_property_ref rows also have raw_target (the
name or UID found), item_name, item_mode, item_enabled,
target_pm_uid (the slot’s saved target UID) and flags (the Menu slot’s
display flags, or None).
Rows from Router and Property Stack logic copy the fields that locate them.
target and source rows also have source_segment_index (-1 for
a Router target).
Location |
Extra keys |
|---|---|
Router branch target |
|
Router Otherwise target |
|
Router condition source |
|
Property Stack row source |
|
Property Stack write entry source |
|
Detected references:
Saved place |
Reference found |
|
|---|---|---|
Menu slot, enabled or not |
The linked menu. |
|
Command or Custom slot text, including a Property’s callbacks |
|
|
Command or Custom slot text, including a Property’s callbacks |
|
|
Router branch or Otherwise |
A target that opens a menu. |
|
Router condition, Property Stack row or write entry |
A source that reads a Property or Property Stack. |
|
Listed in unscannable, by warning:
|
Saved place |
|---|---|
|
Command or Custom slot text that is not valid Python. |
|
A menu call or |
|
Router or Property Stack logic that cannot be parsed or has malformed containers. |
|
A Router condition or Property Stack source without the expected shape. |
|
A saved target or source that is not a mapping. |
|
A Router target that cannot be decoded. |
Not read, and not listed in unscannable:
Property slots:
props().idin a Property slot is not found.Router targets that run a command or a custom script.
Property Stack custom Set text.
Menu Poll and description scripts.
Script files, hotkeys and Python outside PME.