書き出しと検証¶
export_menus() は、メニューを PME の JSON 文書として書き出します。
検証関数は、文書を変更も実行もせずに、同梱の JSON Schema v2 と PME の UID
規則に照らして検査します。
関数 |
用途 |
|---|---|
メニューを JSON 文書として書き出します。指定すればファイルにも書き込みます。 |
|
JSON 文字列を検証します。
|
|
解析済みの JSON データを検証します。 |
|
UTF-8 の JSON ファイルを検証します。 |
|
メニュー UID の形式を確認します。コード実行・ユーザープロパティ・identity で説明しています。 |
メニューを書き出す¶
- pme.export_menus(pm_uids=None, *, include_referenced_menus=True, export_tags=True, filepath=None)¶
メニューを PME の JSON 文書として書き出します。
書き出し処理とファイルの書き込みには、Export Menus ダイアログと同じものを使います。選択中のメニュー、Select Mode、一覧のフィルターは読まず、 変更もしません。
- パラメータ:
pm_uids (iterable of str or None) -- 書き出すメニューの UID。文字列以外の iterable で渡します。
Noneはすべてのメニューを書き出します。include_referenced_menus (bool) -- 指定したメニューが参照するメニューも書き出します。参照先のメニュー を参照。
pm_uidsがNoneの場合は効果がありません。export_tags (bool) -- タグ名、タグ UID、タグレジストリを含めます。
filepath (str or None) -- JSON テキストを書き込むファイル。パスが
.jsonで終わらない場合は.jsonを付けます(大文字と小文字を区別)。既存のファイルは置き換えます。
- 戻り値:
下記の結果。
- 戻り値の型:
- 例外:
TypeError --
pm_uidsが文字列、bytes、または iterable でない場合、include_referenced_menusまたはexport_tagsが bool でない場合、filepathが空でない文字列ではない場合。ValueError --
pm_uidsが空の場合、その中の UID が拒否された場合、またはデータを書き出せない場合。エラー を参照。RuntimeError -- Blender のメインスレッド以外から呼び出された場合 (
"Menu export requires Blender's main thread")、PME が起動スクリプトを実行している間に呼び出された場合 ("Menu export requires PME to finish loading")、preferencesがNoneの間に呼び出された場合 ("PME preferences are unavailable")。KeyError --
preferencesと同じく、ADDON_IDがbpy.context.preferences.addonsにない場合。OSError -- ファイルを書き込めない場合。例: ディレクトリが存在しない場合の
FileNotFoundError。
結果
キー
型
値
datadict
文書。書き出される文書 を参照。
textstr
ファイルに書き込むものと同一の、
dataの JSON テキスト。pm_uidslist[str]
書き出したメニューの UID。文書内の順序です。
warningslist[str]
書き出しを止めなかった問題。警告 を参照。
filepathstr or None
書き込んだファイルのパス。付け足した
.jsonを含みます。filepathを指定しなかった場合はNone。エラー
どのエラーも
ValueErrorです。pm_uidsの確認は指定順に行い、 最初に失敗した UID を示します。メッセージ
原因
pm_uids must name at least one menu; pass None to export allpm_uidsが空です。Menu UID is invalid: <uid>validate_uid()が受け付ける形式のメニュー UID ではありません。UID はrepr()で表示します。Menu UID is listed more than once in pm_uids: <uid>pm_uidsに同じ UID が 2 回現れます。Menu UID is missing: <uid>その UID を持つ保存済みメニューがありません。
Menu UID is ambiguous: <n> saved menus share <uid>複数の保存済みメニューがその UID を持ちます。
PME: Context Router logic export failed for menu '<name>': <source> refers to <target>, which is outside the exported menu setContext Router の分岐先メニューが書き出されません。
<source>はbranch '<label>'、otherwise '<label>'、condition '<label>'のいずれか。<target>はmenu '<current name>'またはa menu that is not in Preferences (UID <uid>)。PME: Context Router logic export failed for menu '<name>': <codes>Context Router の保存されたロジックを読めない、または書き出せません。
PME: <mode> export requires at most <n> slots: <name>スロット数が固定されたメニューの種類で、スロットが多すぎます。
PME: Export blocked by invalid menu identity (<reason>, count=<n>)保存済みメニューが PME のメニュー識別の確認に失敗しました。メニュー UID の欠落、不正、重複などです。
<reason>が確認の名前を示します。tag_registry_export_plan_failedなどのタグレジストリのコードタグレジストリを書き出せません。
データのエラー(Context Router とスロット数)は
ExportDataErrorです。警告を集めた後に送出されたエラーはExportErrorで、そのwarnings属性が警告を保持します。どちらのクラスもValueErrorのサブクラスで、pmeの公開名には含まれません。警告はgetattr(error, "warnings", ())で読みます。警告
メッセージ
原因
PME: <n> Command/Custom slot(s) call menus that could not be resolved, so those menus were not included: <slots>Command または Custom スロットが、特定できないメニューを呼び出しています。スロットごとの理由は
menu not found、duplicate menu name、target not staticのいずれか。PME: <n> Command/Custom slot(s) reference properties that could not be resolved, so those properties were not included: <slots>Command または Custom スロットの
props()参照を特定できません。 スロットごとの理由はprop id not found、display name ambiguous、target not staticのいずれか。PME: Property Stack logic omitted for menu '<name>': <codes>保存されたロジックを読めません。メニューはロジックなしで書き出します。
PME: Property Stack logic repaired for menu '<name>': <codes>保存されたロジックを正規化してから読みました。
<slots>は最大 10 個のスロットを'<menu>' slot <position> '<slot name>' (<reasons>)の形で列挙し、続けてand <n> moreを付けます。 スロットに関する二つの警告は、pm_uidsとinclude_referenced_menus=Trueを指定したときだけ出ます。例
result = pme.export_menus([pm_uid], filepath="C:/exports/shading_pie") print(result["filepath"], result["pm_uids"], result["warnings"])
補足
Context Router の分岐先は、
include_referenced_menusがTrueの場合、またはその UID がpm_uidsにある場合に書き出されます。このとき、その分岐先について「outside the exported menu set」のエラーは起きません。書き出しの前に、書き出すメニューのスロットのうち、スロット UID がない、 不正、またはそのメニュー内で重複しているものに新しい UID を割り当てます。新しい UID は保存済みメニューに残ります。
メニューは
pm_uidsの順ではなく、メニュー一覧の順に書き出します。 開発者オプション Sort Exported Menus by Name は名前順に並べます。
書き出される文書¶
文書は JSON Schema v2 に従います。書き出したメニューのホットキーは文書に含まれます。スロットが呼び出すスクリプトファイルは含まれないため、受け取る側には別のファイルとして必要です。
キー |
値 |
|---|---|
|
|
|
|
|
PME のバージョン。例: |
|
書き出した時刻(UTC)。例: |
|
メニューごとに一つのオブジェクト。 |
|
|
|
書き出したメニューが使うすべてのタグ名。 |
hotkey は key、ctrl、shift、alt、oskey、any、
key_mod、chord、keymaps、activation、drag_direction を持ち、設定されている場合は repeat と tweak_direction も持ちます。
参照先のメニュー¶
pm_uids と include_referenced_menus=True を指定すると、書き出す集合は、指定したメニューと、そこから次の参照でたどれるすべてのメニューです。
追加されるメニューがなくなるまで繰り返します。
Menu スロット。無効なスロットも含みます。
Property Stack と Context Router から、ほかのメニューへの参照。
Command と Custom スロットのテキスト内のメニュー呼び出しと
props()参照。UID、または一つのメニューだけが持つ名前で、一つのメニューに解決できる場合に限ります。
解決できない参照は何も追加しません。そのような Command と Custom スロットの参照は warnings に列挙します。include_referenced_menus=False では、
指定したメニューだけを書き出します。
検証¶
valid=True は、要求した検査に合格したことを表します。現在の Blender
環境での import の成功や、保存されたコマンドの実行は保証しません。
検証の段階¶
テキスト (
validate_json()のみ)。空の文字列、空白だけの文字列、NoneはE102になります。JSON でないテキストはE101になります。ルート。 空または偽の値(
{}、[]、""、0、null)はE102になります。$schemaまたはschema_versionを持つオブジェクトは Schema v2 として検査します(段階 3 から 5)。リスト、 またはmenusのリストと、"1.18.7"のようなドット区切りの整数によるversion文字列を持つオブジェクトは PME1 の文書です。結果には警告W301が付き、それ以上の検査は行いません。それ以外はE206になります。Schema。 文書を同梱のスキーマ
pme2-2.0.jsonに照らして検査します。一度の呼び出しで報告する失敗は一つです。その失敗が必須項目の欠落である場合、そのオブジェクトで欠落している各項目が、同じメッセージの問題になります。型と必須項目の失敗は、条件付き規則の失敗より先に報告します。次の失敗は、最初の失敗を修正した後に現れます。UID。 Schema の検査に合格したときに行います。メニュー UID は有効で、 メニューの
modeと一致し、文書内で一意である必要があります。スロット UID は有効で、そのメニュー内で一意である必要があります。複数の問題を報告する場合があります。参照。
check_referencesがTrueのとき、UID の段階の後に行います。複数の問題を報告する場合があります。メニュー UID を対象とする Menu スロットでは、その UID が同じ文書内にある必要があります。名前で指定した対象は検査しません。
Property Stack(
CONDITION)または Context Router(ROUTER)のロジックを解読し、それが依存するメニュー UID が同じ文書内にある必要があります。ロジックのないCONDITIONは飛ばします。
strict=True では、警告が一つでもある結果は valid=False になります。
警告は warnings に残ります。
- pme.validate_json(json_string, *, strict=False, check_references=True)¶
テキストで渡した PME の JSON 文書を検証します。
pme.validation.validate_jsonと同じ関数です。文書は読むだけです。 変更せず、その Python コードを実行せず、$schemaの URL もダウンロードしません。- パラメータ:
- 戻り値:
見つかった問題と、文書のメタデータ。
- 戻り値の型:
- 例外:
TypeError --
json_stringがintや解析済みのdictなど、ほかの型の場合。メッセージは型を示します。例:"json_string must be str, bytes, bytearray or None, not dict"。 解析済みのデータはpme.validation.validate()で検証します。
例
result = pme.validate_json(pme.export_menus([pm_uid])["text"]) if not result.valid: print(result.format_report())
補足
文書内の問題は、例外ではなく問題として返します。
check_references=Falseは、書き出しの一部など、参照先のメニューを別の文書で用意する文書に適します。旧形式の名前参照と Blender のメニュー型名は、実行中の Blender に照会して解決しません。
W301は、PME1 文書の項目の内容と名前参照を Schema v2 で検証していないことを表します。import には独自の検査があります。Extension には fastjsonschema 2.22.2 を同梱しています。同じ Python プロセスで Blender が自身の 2.21 をすでに読み込んでいる場合があり、 実際に使う版は異なる場合があります。検証は両者に共通の API を使い、 読み込まれたライブラリを置き換えません。
- pme.validation.validate(data, *, strict=False, check_references=True)¶
解析済みの JSON データを検証します。
ルート の段階から始めます。
dataは変更しません。- パラメータ:
- 戻り値:
見つかった問題と、文書のメタデータ。
- 戻り値の型:
- pme.validation.validate_file(filepath, *, strict=False, check_references=True)¶
UTF-8 の JSON ファイルを読み、そのテキストを
pme.validate_json()と同じように検証します。- パラメータ:
- 戻り値:
見つかった問題と、文書のメタデータ。
- 戻り値の型:
補足
読めないファイルは、メッセージ
"File not found: <path>"、"Permission denied: <path>"、"Failed to read file: <error>"のいずれかとともにE101になります。UTF-8 でないファイルは最後の形式になります。例外は送出しません。
- class pme.validation.ValidationResult¶
検証関数の結果。dataclass で、
pme.types.ValidationResultとしても公開しています。属性
型
値
validbool
errorsが空のときTrue。strict=Trueではwarningsも空のとき。errorslist[ValidationIssue]
重大度が
"error"の問題。warningslist[ValidationIssue]
重大度が
"warning"の問題。strict=Trueで結果が無効になっても残ります。schema_versionstr or None
文書の
schema_versionが文字列ならその値。それ以外は、PME1 文書の場合も含めてNone。menu_countint
文書の
menusリストの長さ。文書が無効な場合も同じです。 リストがない場合は 0。has_warningsbool
読み取り専用。
warningsが空でないときTrue。issue_countint
読み取り専用。エラーと警告の合計数。
- format_report(*, include_warnings=True, max_issues=50)¶
結果を読みやすいテキストで返します。
- パラメータ:
- 戻り値:
複数行のテキスト。1 行目は
✓ Valid (<n> menus)で、 その後にSchema version: <version>が続きます。無効な場合の 1 行目は✗ Invalid (<n> errors)です。問題はErrors:とWarnings:の下に、1 行に一つずつ[<code>] <path>: <message>の形で続きます。max_issuesに達すると... and <n> more errorsが付きます。- 戻り値の型:
- class pme.validation.ValidationIssue¶
一つの問題。dataclass で、
pme.types.ValidationIssueとしても公開しています。属性
型
値
severitystr
"error"または"warning"。codestr
問題のコード を参照。
pathstr
文書内の位置。例:
menus[0].items[0].action.value。文書全体では""。messagestr
説明。Schema の問題では、
data must contain ['addon_version'] propertiesのような、 スキーマライブラリのメッセージが入ります。suggestionstr or None
現在の検証が返す問題では
None。ValidationIssue(severity='error', code='E601', path='menus[0].items[0].action.value', message='PM UID reference is not present in this document: rm_6sshkekp', suggestion=None)
問題のコード¶
menus[i] はメニュー、items[j] はそのスロットの一つです。
|
段階 |
|
原因 |
|---|---|---|---|
|
テキスト |
|
JSON ではありません。メッセージは
|
|
テキスト、ルート |
|
空のテキスト( |
|
ルート、Schema |
|
ルートが認識できる文書ではありません。メッセージが問題を示します。
例: |
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
必須の |
|
Schema、UID |
|
UID が Schema に違反しています。または有効な UID ではありません
( |
|
UID |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
Schema |
|
|
|
参照 |
|
|
|
参照 |
|
ロジックを解読できません。メッセージは
|
|
参照 |
|
ロジックの解読に正規化が必要でした。診断コードごとに一つの警告になります。メッセージは
|
|
ルート |
|
PME1 文書と認識しました。内容は検証していません。 |