コード実行・ユーザープロパティ・identity¶
トップレベルの pme パッケージにある名前のうち、PME の標準名前空間で
Python コードを実行するもの、ユーザープロパティを読み書きするもの、実行中のアドオンを特定するものを扱います。スロットのコード(Command、Custom、Poll)
の中で使える名前は スクリプティング に挙げています。
名前 |
用途 |
|---|---|
コードを実行し、 |
|
一つの式を評価し、その値を返します。 |
|
コードを実行せずに構文を確認します。
|
|
Addon Preferences に保存されたユーザープロパティを読み書きします。 |
|
実行中の PME アドオンのモジュール名。 |
|
PME のアドオン Preferences。 |
|
メニュー UID の形式を確認します。 |
|
|
後方互換のために残している PME1 の実行コンテキスト。 |
標準名前空間¶
execute() と evaluate() は、呼び出しのたびに PME の実行コンテキストから作る辞書の中でコードを実行します。
名前 |
値 |
|---|---|
|
|
|
PME のアドオン Preferences。 |
|
PME のセッションデータである |
|
|
|
PME が処理中のイベント。PME がイベントを処理していないときは存在しません。 |
|
最後に追加します。 |
呼び出しごとに新しい辞書を作ります。コードがトップレベルで代入した名前は、 次の呼び出しに残りません。名前空間を通じて到達したオブジェクトへの変更は残ります。例:
Uに設定した属性。どちらの関数も、イベント、レイアウト、スロットを設定しません。
L、delta、drag_x、drag_yなど、メニューの呼び出しを表す名前は、 PME の実行コンテキストに残っている値を持つか、存在しません。アドオンの読み込み中に PME が
scripts/autorunとscripts/registerの起動スクリプトを実行している間は、どちらの関数もコードを実行しません。 PME はその呼び出しを実行中の起動スクリプトの失敗として記録し、残りの起動スクリプトを実行しません。
コード実行¶
- pme.execute(code, *, extra_globals=None)¶
標準名前空間で Python コードを実行し、完了したかどうかを報告します。
コードが送出した例外は捕捉し、テキストとして返します。例外は表示せず、 traceback も残しません。
- パラメータ:
- 戻り値:
実行の結果。
- 戻り値の型:
例
result = pme.execute("bpy.ops.mesh.primitive_cube_add()") if not result.success: print(result.error_message)
補足
error_messageは例外のstr()で、例外の型名を含みません。raise KeyError('a')では"'a'"、1/0では"division by zero"になります。codeの構文エラーも同じように返します。"x = "では"invalid syntax (<string>, line 1)"になります。捕捉するのは
Exceptionのサブクラスだけです。SystemExitとKeyboardInterruptは伝播します。起動スクリプトの実行中は、
successがFalse、error_messageが"Host operations are unavailable during boot script data phase"になります。コードは実行しません。標準名前空間 を参照。
- pme.evaluate(expr, *, extra_globals=None)¶
標準名前空間で一つの Python の式を評価し、その値を返します。
例外は捕捉しません。
- パラメータ:
- 戻り値:
式の値。
- 戻り値の型:
- 例外:
SyntaxError --
exprが単一の式でない場合。NameError --
exprが名前空間にない名前を使っている場合。RuntimeError -- 起動スクリプトの実行中に呼び出された場合。 メッセージは
"Host operations are unavailable during boot script data phase"。Exception --
exprの評価中に送出されたその他の例外。
例
count = pme.evaluate("len(C.selected_objects)")
- pme.check_syntax(code, *, mode='exec')¶
codeを実行せずに、Python として構文解析できるかを確認します。- パラメータ:
code (str) -- Python のソース。空のコードや空白だけのコードは有効です。
mode (str) -- 文には
"exec"、一つの式には"eval"。値はast.parse()に渡し、"single"と"func_type"も受け付けます。
- 戻り値:
構文解析の結果。
- 戻り値の型:
- 例外:
ValueError --
modeがast.parse()の受け付けるモードでない場合。
例
>>> pme.check_syntax("x = ") SyntaxResult(valid=False, error='invalid syntax', line=1, column=5) >>> pme.check_syntax("2 + 2", mode="eval").valid True
補足
確認するのは構文だけです。未定義の名前や、コードの実行時に起きるエラーは検出しません。
結果の型¶
どちらのクラスも pme.types の dataclass です。
- class pme.types.ExecuteResult¶
pme.execute()の結果。属性
型
値
successbool
コードが例外を送出せずに最後まで実行されたとき
True。error_messagestr or None
successがFalseのときは例外のstr()。それ以外はNone。
- class pme.types.SyntaxResult¶
pme.check_syntax()の結果。属性
型
値
validbool
コードを構文解析できたとき
True。errorstr or None
パーサーのメッセージ。例:
"invalid syntax"、"'(' was never closed"。有効な場合はNone。lineint or None
エラーの行(1 から数えます)。有効な場合は
None。columnint or None
エラーの列(1 から数えます)。有効な場合は
None。
ユーザープロパティ¶
- pme.props(name=None, value=None)¶
Addon Preferences に保存されたユーザープロパティを読み書きします。
対象は、保存先が Addon Preferences の Property と、Property Stack だけです。
Objectなどの ID 型に保存する Property は、データブロックごとに一つの値を、そのデータブロックの属性として持ちます。props()はその値を保持しません。Property を参照。- パラメータ:
name (str or None) -- 解決する Property ID またはメニュー名。
str()で変換します。Noneでは PropertyGroup を返します。value -- 書き込む値。
Noneでは書き込まずに読み取ります。
- 戻り値:
呼び出し形式 を参照。
- 例外:
RuntimeError -- PME が Property Editor の読み込みを終えていない場合。メッセージは
"PME user properties are unavailable until the add-on finishes loading"。TypeError -- 書き込みで、プロパティが受け付けない値を渡した場合。 Blender が送出します。例:
expected True/False or 0/1, not str。
呼び出し形式
呼び出し
操作
戻り値
props()なし
値を保持する PropertyGroup。その属性は登録された Property ID で、属性の読み取りと代入で値を読み書きします。
props(name),props(name, None)読み取り
値。
nameを解決できない場合はNone。props(name, value)書き込み
値を書き込んだとき
True。nameが書き込み可能な名前に解決できない場合はFalse。名前の解決
nameを次の行の順に照合します。最初に一致した行で決まります。name読み取り
書き込み
Property または Property Stack の登録済み Property ID。
read_pm()["property"]またはread_pm()["property_stack"]のregistered_property_id。値
書き込み、
Trueを返すProperty ID が登録されている有効なメニュー(Addon Preferences に保存する Property、または Property Stack)のうち、ちょうど一つが持つメニュー名。
その ID の値
Falseそのようなメニューの複数が持つメニュー名。
NoneFalseそれ以外。
NoneFalse例
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)
補足
スロットのコードでは、同じ関数がグローバルの
propsです。Property Editor で作成したユーザープロパティは、どちらでも同じ呼び出し形式を使います。props(name, None)は読み取りです。Noneを書き込みません。解決できない名前を、一時的な保存領域として作成することはありません。
bl_rna、keys、__class__など、PropertyGroup 自体の属性名は Property ID ではありません。props("bl_rna")はNone、props("bl_rna", 1)はFalseを返します。これらは PropertyGroup からpme.props().bl_rnaのように読みます。メニュー名による書き込みは、同じ名前による読み取りが値を返す場合でも
Falseを返します。以前の Experimental ビルドでは、PropertyGroup を
pme.props.MyCounterとして公開していました。現在の形式はpme.props().MyCounterです。
アドオンの identity¶
- pme.ADDON_ID: str¶
実行中の PME アドオンのモジュール名。
scripts/addonsにインストールしたアドオンでは"pie_menu_editor"、Blender Extension では"bl_ext.<repository>.<package>"です。bpy.context.preferences.addonsでの PME のエントリのキーです。PME の
addonモジュールの読み込み前に読むと、メッセージ"PME add-on identity is unavailable until the add-on finishes loading"とともにRuntimeErrorを送出します。固定値の"pie_menu_editor"は、Blender Extension としてのインストールと一致しません。import bpy import pme addon_preferences = bpy.context.preferences.addons[pme.ADDON_ID].preferences
- pme.preferences¶
PME のアドオン Preferences(
PMEPreferences)。bpy.context.preferences.addons[pme.ADDON_ID].preferencesと同じオブジェクトです。アクセスのたびに参照し直します。ADDON_IDがbpy.context.preferences.addonsにない場合、 読み取るとKeyErrorを送出します。そのエントリが存在しても PME の Preferences クラスが登録されていない間はNoneです。例: アドオンを有効にしている途中、またはdefault_set=Trueなしでaddon_utils.disable()を呼んだ後。
- pme.validate_uid(uid)¶
uidがメニュー UID の形式かどうかを返します。確認するのは形式だけです。保存済みのメニューは探しません。
- パラメータ:
uid (str) -- 確認する文字列。
- 戻り値:
<prefix>_<id>の形式ならTrue。<prefix>は下表のメニューの種類の接頭辞、<id>はa-zと2-7からなる 8 文字です。それ以外はFalseです。文字列でない値、大文字、 スロット UID(pmi_<id>)もこれに含まれます。- 戻り値の型:
接頭辞
メニューの種類
modepmPie Menu
PMENUvmVector Menu
VMENUrmRegular Menu
RMENUpdPop-up Dialog
DIALOGfpFloating Panel
FPANELsStack Key
SCRIPTpgPanel Group
PANELhpgHidden Panel Group
HPANELskSticky Key
STICKYmcMacro Operator
MACROmdModal Operator
MODALprProperty
PROPERTYcnProperty Stack
CONDITIONrtContext Router
ROUTER>>> pme.validate_uid("pm_a2b3c4d5") True >>> pme.validate_uid("pmi_a2b3c4d5") False