Execution, user properties and identity¶

Names on the top-level pme package that run Python code in PME’s standard namespace, read and write user properties, and identify the running add-on. Names available inside slot code (Command, Custom, Poll) are listed in Scripting.

Name

Purpose

execute()

Runs code and returns ExecuteResult.

evaluate()

Evaluates one expression and returns its value.

check_syntax()

Checks syntax without running the code. Returns SyntaxResult.

props()

Reads or writes user properties stored in Addon Preferences.

ADDON_ID

Module name of the running PME add-on.

preferences

PME’s add-on preferences.

validate_uid()

Checks the format of a menu UID.

context

PME1 execution context, kept for backward compatibility.

Standard namespace¶

execute() and evaluate() run code in a dictionary built from PME’s execution context on each call.

Names

Value

C, D, O, T, P, bpy, U, pme, props and the other global names

Every name in pme.context.globals: the globals that slot code receives, the helper functions listed in Scripting, and names added with pme.context.add_global(), including those of autorun scripts.

PREFS

PME’s add-on preferences, the same object as preferences.

PME

bpy.context.window_manager.pme, PME’s session data, or None.

text, icon, icon_value

The current values of pme.context.text, pme.context.icon and pme.context.icon_value.

E

The event PME is handling. Absent when PME is not handling an event.

Names in extra_globals

Added last. A name in extra_globals replaces a standard name.

  • Each call builds a new dictionary. Names that the code assigns at top level are not kept for the next call. Objects reached through the namespace keep their changes, for example attributes set on U.

  • Neither function sets an event, a layout or a slot. Names that describe a menu invocation, such as L, delta, drag_x and drag_y, hold the values left in PME’s execution context, or are absent.

  • While PME runs the startup scripts in scripts/autorun and scripts/register during add-on loading, neither function runs code. PME records the call as a failure of the running startup script and does not run the remaining startup scripts.

Code execution¶

pme.execute(code, *, extra_globals=None)¶

Run Python code in the standard namespace and report whether it completed.

An exception raised by the code is caught and returned as text. It is not printed, and no traceback is kept.

Parameters:
  • code (str) – Python statements. Several lines are accepted.

  • extra_globals (dict or None) – Names added to the namespace after the standard names. A name that already exists is replaced.

Returns:

The outcome of the run.

Return type:

ExecuteResult

Example

result = pme.execute("bpy.ops.mesh.primitive_cube_add()")
if not result.success:
    print(result.error_message)

Notes

  • error_message is str() of the exception and does not name its type: raise KeyError('a') gives "'a'", 1/0 gives "division by zero".

  • A syntax error in code is returned the same way: "x = " gives "invalid syntax (<string>, line 1)".

  • Only subclasses of Exception are caught. SystemExit and KeyboardInterrupt propagate.

  • During the startup scripts, success is False and error_message is "Host operations are unavailable during boot script data phase". The code is not run. See Standard namespace.

pme.evaluate(expr, *, extra_globals=None)¶

Evaluate one Python expression in the standard namespace and return its value.

Exceptions are not caught.

Parameters:
  • expr (str) – One expression. A statement such as x = 1 raises SyntaxError.

  • extra_globals (dict or None) – Names added to the namespace after the standard names. A name that already exists is replaced.

Returns:

The value of the expression.

Return type:

object

Raises:
  • SyntaxError – expr is not a single expression.

  • NameError – expr uses a name that is not in the namespace.

  • RuntimeError – Called during the startup scripts. The message is "Host operations are unavailable during boot script data phase".

  • Exception – Any other exception raised while evaluating expr.

Example

count = pme.evaluate("len(C.selected_objects)")
pme.check_syntax(code, *, mode='exec')¶

Check that code parses as Python, without running it.

Parameters:
  • code (str) – Python source. Empty or whitespace-only code is valid.

  • mode (str) – "exec" for statements, "eval" for one expression. The value is passed to ast.parse(), which also accepts "single" and "func_type".

Returns:

The parse result.

Return type:

SyntaxResult

Raises:

ValueError – mode is not a mode that ast.parse() accepts.

Example

>>> pme.check_syntax("x = ")
SyntaxResult(valid=False, error='invalid syntax', line=1, column=5)
>>> pme.check_syntax("2 + 2", mode="eval").valid
True

Notes

  • Only syntax is checked. Undefined names and errors that occur when the code runs are not detected.

Result types¶

Both classes are dataclasses in pme.types.

class pme.types.ExecuteResult¶

Outcome of pme.execute().

Attribute

Type

Value

success

bool

True when the code ran to the end without raising.

error_message

str or None

str() of the exception when success is False; None otherwise.

class pme.types.SyntaxResult¶

Outcome of pme.check_syntax().

Attribute

Type

Value

valid

bool

True when the code parses.

error

str or None

The parser’s message, such as "invalid syntax" or "'(' was never closed". None when valid.

line

int or None

Line of the error, counted from 1. None when valid.

column

int or None

Column of the error, counted from 1. None when valid.

User properties¶

pme.props(name=None, value=None)¶

Read or write the user properties stored in Addon Preferences.

Only Properties whose storage is Addon Preferences, and Property Stacks, are reached. A Property stored on an ID type such as Object keeps one value per data-block, as an attribute of that data-block; props() does not hold it. See Property.

Parameters:
  • name (str or None) – Property ID or menu name to resolve, converted with str(). None returns the PropertyGroup.

  • value – Value to write. None reads instead of writing.

Returns:

See Call forms.

Raises:
  • RuntimeError – PME has not finished loading the Property Editor. The message is "PME user properties are unavailable until the add-on finishes loading".

  • TypeError – A write gives a value the property does not accept. Raised by Blender, for example expected True/False or 0/1, not str.

Call forms

Call

Operation

Returns

props()

none

The PropertyGroup that holds the values. Its attributes are the registered Property IDs; reading and assigning them reads and writes the values.

props(name), props(name, None)

read

The value, or None when name does not resolve.

props(name, value)

write

True when the value was written. False when name does not resolve to a writable name.

Name resolution

name is compared with the rows in this order. The first match decides.

name

Read

Write

The registered Property ID of a Property or Property Stack: registered_property_id in read_pm()["property"] or read_pm()["property_stack"].

The value

Writes, returns True

The menu name of exactly one enabled Property stored in Addon Preferences or enabled Property Stack whose Property ID is registered.

The value under that ID

False

The menu name of several such menus.

None

False

Anything else.

None

False

Example

import pme

# Get the PropertyGroup and access a property as an attribute
pme.props().MyCounter = 10
value = pme.props().MyCounter

# Read or write by registered Property ID
value = pme.props("MyCounter")
written = pme.props("MyCounter", 10)

Notes

  • Inside slot code, the same function is the global props. User properties created with the Property Editor use the same call forms in both places.

  • props(name, None) reads. It does not write None.

  • A name that does not resolve is not created as scratch storage.

  • Attribute names of the PropertyGroup itself, such as bl_rna, keys or __class__, are not Property IDs: props("bl_rna") returns None and props("bl_rna", 1) returns False. Read them from the PropertyGroup, pme.props().bl_rna.

  • A write by menu name returns False even when a read by the same name returns a value.

  • Earlier Experimental builds exposed the PropertyGroup as pme.props.MyCounter. The current form is pme.props().MyCounter.

Add-on identity¶

pme.ADDON_ID: str¶

Module name of the running PME add-on: "pie_menu_editor" for an add-on installed in scripts/addons, "bl_ext.<repository>.<package>" for a Blender Extension. It is the key of PME’s entry in bpy.context.preferences.addons.

Reading it before PME’s addon module is loaded raises RuntimeError with the message "PME add-on identity is unavailable until the add-on finishes loading". A hard-coded "pie_menu_editor" does not match a Blender Extension installation.

import bpy
import pme

addon_preferences = bpy.context.preferences.addons[pme.ADDON_ID].preferences
pme.preferences¶

PME’s add-on preferences (PMEPreferences): the same object as bpy.context.preferences.addons[pme.ADDON_ID].preferences. Looked up on each access.

Reading it raises KeyError when ADDON_ID is not in bpy.context.preferences.addons. It is None while that entry exists but PME’s preferences class is not registered, for example while the add-on is being enabled, or after addon_utils.disable() without default_set=True.

pme.validate_uid(uid)¶

Return whether uid has the format of a menu UID.

The check covers the format only. It does not look for a saved menu.

Parameters:

uid (str) – The string to check.

Returns:

True for <prefix>_<id>, where <prefix> is a menu type’s prefix below and <id> is 8 characters from a-z and 2-7. False otherwise, including for non-strings, upper case and slot UIDs (pmi_<id>).

Return type:

bool

Prefix

Menu type

mode

pm

Pie Menu

PMENU

vm

Vector Menu

VMENU

rm

Regular Menu

RMENU

pd

Pop-up Dialog

DIALOG

fp

Floating Panel

FPANEL

s

Stack Key

SCRIPT

pg

Panel Group

PANEL

hpg

Hidden Panel Group

HPANEL

sk

Sticky Key

STICKY

mc

Macro Operator

MACRO

md

Modal Operator

MODAL

pr

Property

PROPERTY

cn

Property Stack

CONDITION

rt

Context Router

ROUTER

>>> pme.validate_uid("pm_a2b3c4d5")
True
>>> pme.validate_uid("pmi_a2b3c4d5")
False
pme.context

PME’s execution context (PMEContext), kept for PME1 scripts. pme.context.globals is the dictionary behind the standard namespace, and pme.context.add_global(name, value) adds a name to it. Described in Scripting.