:orphan:

(public_api)=

# Public API

PME2 では、外部スクリプトやアドオンから PME の機能を利用するための公開 API を提供しています。

## クイックスタート

```python
import pme

# 実行中のpackage identity（Legacy add-on／Blender Extension）
addon_id = pme.ADDON_ID

# メニューを探す
pm = pme.find_pm("My Pie Menu")
pm = pme.find_pm(uid="pm_9f7c2k3h")

# メニューを呼び出す
pme.invoke_pm("My Pie Menu")
pme.invoke_pm(uid="pm_9f7c2k3h")

# メニュー一覧
all_menus = pme.list_pms()
pie_menus = pme.list_pms(mode="PMENU", enabled_only=True)
tags = pme.list_tags()

# コード実行
result = pme.execute("bpy.ops.mesh.primitive_cube_add()")
print(result.ok, result.error)

# 式評価
value = pme.evaluate("len(C.selected_objects)")

# JSON 検証
result = pme.validate_json(json_string)
for err in result.errors:
    print(err.code, err.message)
```

## PME1 からの変更点

| 観点 | PME1 | PME2 |
|------|------|------|
| インポート | `from pie_menu_editor import pme` | `import pme` |
| runtime add-on ID | `"pie_menu_editor"` の固定値 | `pme.ADDON_ID` |
| 設計 | 内部モジュールの露出 | 公開 API ファサード |
| メニュー呼び出し | `pme.context.open_menu(name)` | `pme.invoke_pm(name)` / `pme.invoke_pm(uid=...)` |
| コード実行 | `pme.context.exe(code)` | `pme.execute(code)` → `ExecuteResult` |
| メニュー検索 | なし | `pme.find_pm()`, `pme.list_pms()` |
| JSON 検証 | なし | `pme.validate_json()` |
| 型・定数 | なし | `pme.types`, `pme.constants` |

## API リファレンス

### メニュー操作

```{list-table}
:header-rows: 1
:widths: 30 70

* - 関数
  - 説明
* - `find_pm(name=None, *, uid=None)`
  - 名前または uid でメニューを検索。見つからなければ `None`
* - `invoke_pm(pm_or_name=None, *, name=None, uid=None)`
  - メニューを呼び出す。成功時 `True`
* - `list_pms(mode=None, *, enabled_only=False)`
  - メニュー一覧を `PMHandle` のリストで返す
* - `list_tags()`
  - 使用中のタグ一覧を返す
```

### コード実行

```{list-table}
:header-rows: 1
:widths: 30 70

* - 関数
  - 説明
* - `execute(code, *, extra_globals=None)`
  - コードを実行し `ExecuteResult` を返す
* - `evaluate(expr, *, extra_globals=None)`
  - 式を評価して結果を返す。失敗時は例外
* - `check_syntax(code, *, mode="exec")`
  - 構文チェックのみ。`SyntaxResult` を返す
```

### 検証

```{list-table}
:header-rows: 1
:widths: 30 70

* - 関数
  - 説明
* - `validate_json(json_string, *, strict=False, check_references=True)`
  - JSON Schema v2 に対する検証。`ValidationResult` を返す
* - `validate_uid(uid)`
  - uid 文字列のフォーマットを検証
```

### ユーザープロパティ

Property Editor で作成したユーザープロパティには、Command 内の `props()` と
`import pme` の `pme.props()` のどちらからも同じ方法でアクセスできます。

```python
import pme

# PropertyGroup を取得して属性として読み書きする
pme.props().MyCounter = 10
value = pme.props().MyCounter

# 登録済みstorage IDを指定して読み書きする
value = pme.props("MyCounter")
written = pme.props("MyCounter", 10)
```

`pme.props(name, None)` は従来どおり読み取りです。`None` を値として書き込む
操作にはなりません。名前によるアクセスはPMEが登録したproperty専用です。
未登録名は読み取り時に `None`、書き込み時に `False` を返し、scratch storageを
作成しません。以前の Experimental API で使えた
`pme.props.MyCounter` は `pme.props().MyCounter` に変更してください。

### Runtime add-on identity

Blender APIへ実行中のadd-on module IDを渡す必要がある場合は
`pme.ADDON_ID`を使います。Blender Extensionでは
`bl_ext.<repository>.<package>`を含む現在のpackage identityを返します。

```python
import bpy
import pme

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

PMEのPreferences objectだけが必要な場合は`pme.preferences`を使ってください。
新しいscriptで`"pie_menu_editor"`を固定値として書かないでください。

### 後方互換

PME1 の `pme.context` と Command global の `props()` は引き続き利用可能です。
既存の Command タブ内の `props()` スクリプトはそのまま動作します。

```python
# これらは PME2 でもそのまま使える
pme.context.open_menu("My Menu")
pme.context.event.mouse_x
pme.context.add_global("my_var", value)
props("MyCounter", 10)
```

新規コードでは `pme.execute()` / `pme.invoke_pm()` の利用を推奨します。

```{note}
Public API は現在 **Experimental** です。基本的なインターフェースは安定していますが、細部は今後のバージョンで変更される可能性があります。
```

```{seealso}
`import pme` を利用するには事前の有効化が必要です。手順は [起動オプション](boot_options.md) を参照してください。
```