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

Concepts

Where the editing functions run, what they act on, what they do not do, and what is stable.

Results and guards

status values, dry_run, the expected / expected_version / expected_digest guards, diagnostics and exceptions, per operation.

Menus

Create, find, list, invoke, read, rename, enable, tag, duplicate and delete menus; find what refers to a menu.

Slots

Read slot inputs; edit, clear, add, remove, move, exchange and transfer slots.

Layout rows and panels

Rows, spacers, alignment and Layout Panels of Pop-up Dialogs and Floating Panels.

Menu type settings

Settings that belong to a menu’s type, such as a Pop-up Dialog’s Mode and width.

Hotkeys

Read and change a menu’s hotkey binding.

Property

Author a Property: type, arguments, Enum items, callbacks, storage and Property ID.

Property Stack

Author a Property Stack and edit its condition rows.

Context Router

Add, update, remove and reorder Context Router branches.

Export and validation

Export menus as PME’s JSON document; validate a document.

Resources

Registered script and icon locations; script reference checks.

Execution, user properties and identity

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 RuntimeError with the list.

  • The pme variable from the explicit import is the same API as the alias. Code that uses it omits import 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_pm()

Create a menu with the editor’s default contents from a PmCreationSpec; returns PmCreationResult.

Menus

find_pm()

Return a PMHandle for a menu found by name or UID, or None.

Menus

list_pms()

Return PMHandle objects, optionally filtered by menu type and enabled state.

Menus

list_tags()

Return the tag names in use, in Tag Registry order.

Menus

invoke_pm()

Request a menu invocation, as its hotkey would.

Menus

export_menus()

Export menus as PME’s JSON document, optionally writing a file.

Export and validation

validate_json()

Validate a PME JSON string statically; returns ValidationResult.

Export and validation

validate_uid()

Return whether a string has the format of a menu UID.

Execution, user properties and identity

execute()

Run code in PME’s standard namespace; returns ExecuteResult.

Execution, user properties and identity

evaluate()

Evaluate an expression in PME’s standard namespace; raises on failure.

Execution, user properties and identity

check_syntax()

Check Python syntax without running the code; returns SyntaxResult.

Execution, user properties and identity

props()

Read or write a user property registered by PME.

Execution, user properties and identity

Other names exported by pme:

Name

Purpose

Page

PmCreationSpec

Creation request for create_pm(): mode_id, name, slots, data.

Menus

PmCreationResult

Result of create_pm(): accepted, pm_uid, diagnostics.

Menus

PmiSlotSpec

Slot entry of PmCreationSpec.slots (mode, name, text, icon). create_pm() rejects explicit slots with slots_unsupported_by_create_pm.

Menus

ADDON_ID

Module ID of the running add-on package, such as pie_menu_editor or bl_ext.<repository>.<package>.

Execution, user properties and identity

preferences

PME’s add-on preferences object. None while the add-on entry exists without PME’s preferences class; reading it raises KeyError when PME is not enabled.

Execution, user properties and identity

context

PME1 execution context, kept for backward compatibility (Backward compatibility).

Execution, user properties and identity

Submodules:

Module

Purpose

Page

pme.editing

Read and edit saved menu definitions by UID. Functions are listed below.

This page

pme.validation

Static validation of PME JSON: validate, validate_json, validate_file, ERROR_CODES.

Export and validation

pme.resources

Read-only discovery of registered script and icon folders and files; script reference checks.

Resources

pme.types

Result and handle types: ExecuteResult and SyntaxResult (Execution, user properties and identity), PMHandle and PmCreationResult (Menus), ValidationIssue and ValidationResult (Export and validation).

Per type

pme.constants

Menu type and slot mode identifiers (MENU_MODES, ITEM_MODES, UNTAGGED) and get_mode_label(), get_mode_icon(), is_valid_mode(). MENU_MODES does not include FPANEL.

(none)

pme.dev

Namespace introspection for tool authors: is_public(), get_stability(), validate_namespace(), namespace_report(), get_logger().

(none)

pme.editing¶

Function

Purpose

Page

update_pm()

Change a menu’s name, description, description format or Poll source.

Menus

set_enabled()

Enable or disable menus through the bulk owner.

Menus

update_tags()

Add and remove tag names across menus in one batch.

Menus

duplicate_pm()

Copy one menu immediately after its source.

Menus

delete_pms()

Delete menus, or preview the deletion and its references.

Menus

find_references()

List the saved places that refer to menus. Read-only.

Menus

read_pm()

Return one menu’s saved definition, optionally for selected slot UIDs.

Menus

read_slot_inputs()

Return slots under the input names update_slots() accepts. Read-only.

Slots

slot_fields()

Describe the Slot Editor input fields: names, types, Enum values.

Slots

resolve_auto_icons()

Report whether each Auto Icon slot finds an icon in this Blender session. Read-only.

Slots

update_slots()

Change slot contents by slot UID through normal Slot Editor saves.

Slots

clear_slots()

Clear slot contents, keeping their UIDs and positions.

Slots

add_slot()

Add one default item next to a slot, at the end, or into a Panel header.

Slots

remove_slot()

Remove one item.

Slots

move_slot()

Move one item before or after another, or to a row end, a new row or a Panel header.

Slots

swap_slots()

Exchange two fixed-slot items or two Pop-up items.

Slots

transfer_slot()

Move one item’s contents to another menu.

Slots

add_row()

Add a layout row with a default button.

Layout rows and panels

add_panel()

Add a Layout Panel row with its default anchor.

Layout rows and panels

remove_row()

Remove a whole layout row and its contents.

Layout rows and panels

move_row()

Move a whole layout row before or after another row.

Layout rows and panels

split_row()

Split a layout row before one of its items.

Layout rows and panels

join_rows()

Join two adjacent layout rows.

Layout rows and panels

update_row()

Change saved row settings for one row, aligned rows or all rows.

Layout rows and panels

update_spacer()

Change one spacer setting, creating an adjacent spacer when needed.

Layout rows and panels

align_slot()

Place an item in a row’s LEFT, CENTER or RIGHT section, or clear it.

Layout rows and panels

setting_fields()

Describe the settings the menu’s type accepts.

Menu type settings

update_settings()

Change settings of the menu’s type.

Menu type settings

update_hotkey()

Change a menu’s hotkey binding, or preview the change.

Hotkeys

update_property()

Change a Property’s type, arguments, Enum items, callbacks, storage and Property ID.

Property

update_property_stack()

Replace a Property Stack’s complete logic.

Property Stack

add_property_stack_row()

Append an empty condition row.

Property Stack

update_property_stack_row()

Change one condition row and its related SET entry.

Property Stack

remove_property_stack_row()

Remove one condition row and its related SET entry.

Property Stack

update_property_stack_hud()

Change a Property Stack’s While True HUD.

Property Stack

update_router()

Change, append and keep Context Router branches and Otherwise.

Context Router

remove_router_branch()

Remove one branch, keeping Otherwise.

Context Router

move_router_branch()

Move one branch before or after another.

Context Router

reorder_router_branches()

Put every branch in the given order with one save.

Context Router

Changes from PME1¶

Topic

PME1

PME2

Import

from pie_menu_editor import pme

import pme

Runtime add-on ID

Hard-coded "pie_menu_editor"

pme.ADDON_ID

Design

Exposed internal module

Public API facade

Menu invocation

pme.context.open_menu(name)

pme.invoke_pm(name) / pme.invoke_pm(uid=...)

Code execution

pme.context.exe(code)

pme.execute(code) returning ExecuteResult

Menu lookup

None

pme.find_pm(), pme.list_pms()

JSON validation

None

pme.validate_json()

Types and constants

None

pme.types, pme.constants

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().