Authoring API¶
The Authoring API creates, reads, edits and exports PME menus from Python
through the pme package and its pme.editing module. It is called from
the Python Console, the Text Editor, another add-on, or an AI agent driving
Blender. Code written inside a slot (Command, Custom, Poll) is a different
subject, described in Scripting.
Pages¶
Every page can be read on its own. Concepts and Results and guards define the rules that every editing function follows. The whole API is Experimental.
Page |
Covers |
|---|---|
Where the editing functions run, what they act on, what they do not do, and what is stable. |
|
|
|
Create, find, list, invoke, read, rename, enable, tag, duplicate and delete menus; find what refers to a menu. |
|
Read slot inputs; edit, clear, add, remove, move, exchange and transfer slots. |
|
Rows, spacers, alignment and Layout Panels of Pop-up Dialogs and Floating Panels. |
|
Settings that belong to a menu’s type, such as a Pop-up Dialog’s Mode and width. |
|
Read and change a menu’s hotkey binding. |
|
Author a Property: type, arguments, Enum items, callbacks, storage and Property ID. |
|
Author a Property Stack and edit its condition rows. |
|
Add, update, remove and reorder Context Router branches. |
|
Export menus as PME’s JSON document; validate a document. |
|
Registered script and icon locations; script reference checks. |
|
Run code, read and write user properties, identify the running add-on package, check a UID’s format. |
Importing¶
The examples use import pme, the optional short alias configured in
Boot Options. When the alias is disabled, the enabled add-on’s package
is imported by name. This needs no change to the startup configuration and no
reload of Blender:
import bpy
import importlib
packages = [
addon.module for addon in bpy.context.preferences.addons
if addon.module.rsplit(".", 1)[-1].replace("-", "_") == "pie_menu_editor"
]
if len(packages) != 1:
raise RuntimeError(f"Select the enabled PME package: {packages}")
pme = importlib.import_module(packages[0] + ".api")
print(pme.ADDON_ID)
The snippet also finds a Blender Extension installed as
bl_ext.<repository>.pie_menu_editor, and one whose extension ID uses hyphens (bl_ext.<repository>.pie-menu-editor). The module name follows the repository’s ID, so the comparison ignores the hyphen / underscore difference.When several packages are listed, the intended installation is identified before any edit. The snippet raises
RuntimeErrorwith the list.The
pmevariable from the explicit import is the same API as the alias. Code that uses it omitsimport pme.
Quick start¶
import pme
# Runtime package identity (Legacy add-on or Blender Extension)
addon_id = pme.ADDON_ID
# Find a menu
pm = pme.find_pm("My Pie Menu")
pm = pme.find_pm(uid="pm_7f3c2k3h")
# Invoke a menu
pme.invoke_pm("My Pie Menu")
pme.invoke_pm(uid="pm_7f3c2k3h")
# List menus
all_menus = pme.list_pms()
pie_menus = pme.list_pms(mode="PMENU", enabled_only=True)
tags = pme.list_tags()
# Execute code
result = pme.execute("bpy.ops.mesh.primitive_cube_add()")
print(result.success, result.error_message)
# Evaluate an expression
value = pme.evaluate("len(C.selected_objects)")
# Validate JSON
result = pme.validate_json(json_string)
for err in result.errors:
print(err.code, err.message)
Function index¶
pme¶
Function |
Purpose |
Page |
|---|---|---|
Create a menu with the editor’s default contents from a
|
||
Return a |
||
Return |
||
Return the tag names in use, in Tag Registry order. |
||
Request a menu invocation, as its hotkey would. |
||
Export menus as PME’s JSON document, optionally writing a file. |
||
Validate a PME JSON string statically; returns |
||
Return whether a string has the format of a menu UID. |
||
Run code in PME’s standard namespace; returns |
||
Evaluate an expression in PME’s standard namespace; raises on failure. |
||
Check Python syntax without running the code; returns
|
||
Read or write a user property registered by PME. |
Other names exported by pme:
Name |
Purpose |
Page |
|---|---|---|
Creation request for |
||
Result of |
||
Slot entry of |
||
Module ID of the running add-on package, such as |
||
PME’s add-on preferences object. |
||
PME1 execution context, kept for backward compatibility (Backward compatibility). |
Submodules:
Module |
Purpose |
Page |
|---|---|---|
Read and edit saved menu definitions by UID. Functions are listed below. |
This page |
|
Static validation of PME JSON: |
||
Read-only discovery of registered script and icon folders and files; script reference checks. |
||
|
Result and handle types: |
Per type |
|
Menu type and slot mode identifiers ( |
(none) |
|
Namespace introspection for tool authors: |
(none) |
pme.editing¶
Function |
Purpose |
Page |
|---|---|---|
Change a menu’s name, description, description format or Poll source. |
||
Enable or disable menus through the bulk owner. |
||
Add and remove tag names across menus in one batch. |
||
Copy one menu immediately after its source. |
||
Delete menus, or preview the deletion and its references. |
||
List the saved places that refer to menus. Read-only. |
||
Return one menu’s saved definition, optionally for selected slot UIDs. |
||
Return slots under the input names |
||
Describe the Slot Editor input fields: names, types, Enum values. |
||
Report whether each Auto Icon slot finds an icon in this Blender session. Read-only. |
||
Change slot contents by slot UID through normal Slot Editor saves. |
||
Clear slot contents, keeping their UIDs and positions. |
||
Add one default item next to a slot, at the end, or into a Panel header. |
||
Remove one item. |
||
Move one item before or after another, or to a row end, a new row or a Panel header. |
||
Exchange two fixed-slot items or two Pop-up items. |
||
Move one item’s contents to another menu. |
||
Add a layout row with a default button. |
||
Add a Layout Panel row with its default anchor. |
||
Remove a whole layout row and its contents. |
||
Move a whole layout row before or after another row. |
||
Split a layout row before one of its items. |
||
Join two adjacent layout rows. |
||
Change saved row settings for one row, aligned rows or all rows. |
||
Change one spacer setting, creating an adjacent spacer when needed. |
||
Place an item in a row’s LEFT, CENTER or RIGHT section, or clear it. |
||
Describe the settings the menu’s type accepts. |
||
Change settings of the menu’s type. |
||
Change a menu’s hotkey binding, or preview the change. |
||
Change a Property’s type, arguments, Enum items, callbacks, storage and Property ID. |
||
Replace a Property Stack’s complete logic. |
||
Append an empty condition row. |
||
Change one condition row and its related SET entry. |
||
Remove one condition row and its related SET entry. |
||
Change a Property Stack’s While True HUD. |
||
Change, append and keep Context Router branches and Otherwise. |
||
Remove one branch, keeping Otherwise. |
||
Move one branch before or after another. |
||
Put every branch in the given order with one save. |
Changes from PME1¶
Topic |
PME1 |
PME2 |
|---|---|---|
Import |
|
|
Runtime add-on ID |
Hard-coded |
|
Design |
Exposed internal module |
Public API facade |
Menu invocation |
|
|
Code execution |
|
|
Menu lookup |
None |
|
JSON validation |
None |
|
Types and constants |
None |
|
Backward compatibility¶
PME1’s pme.context and the props() command global remain available.
Existing props() scripts inside PME command slots keep working.
# These still work in PME2
pme.context.open_menu("My Menu")
pme.context.event.mouse_x
pme.context.add_global("my_var", value)
props("MyCounter", 10)
New code uses pme.execute() and pme.invoke_pm().