結果とガード¶
pme.editing のすべての編集関数は dict を返します。
このページは、それらの結果に共通する要素を定義します。
status の値、古い入力を拒否するガード、dry_run、診断の項目、例外です。
1 つの関数だけが持つキーは、その関数の説明に記載します。
成功、事前確認、古い入力を表す値の名前は、操作ごとに決まっています。 操作ごとの結果とガードの語彙 に一覧があります。 呼び出し側は、1 つの綴りを仮定せず、そこに挙げた値で判定します。
共通の結果キー¶
キー |
型 |
値 |
|---|---|---|
|
str |
ステータスの値 のいずれかの値。 すべての結果にあります。 |
|
bool |
|
|
bool |
|
|
str |
メニュー UID。1 つのメニューに対する大半の操作の結果にあります。 |
|
dict または None |
呼び出しの前と後に読んだ保存値。 形と有無は各関数の説明に記載します。 |
|
dict |
後の呼び出しに |
|
list |
保存を試みていない部分(スロット UID、メタデータのフィールド名、Property のグループ)。 エディターのコールバックなど、先の段階がそれらを変更している場合があります。 pending は未変更を意味しません。 |
|
dict、str または None |
書き込み失敗後の復元の詳細。 形は各関数の説明に記載します。 |
|
list[dict] |
診断 で説明する項目。 すべての結果にあります。 |
pme.create_pm() は dict ではなく PmCreationResult オブジェクトを返します。
属性は accepted (bool)、pm_uid (str。拒否時は空)、
diagnostics (コード文字列の tuple)です。
accepted が True で refresh_failed がある場合、
メニューは作成済みで、表示の更新だけが失敗しています。
update_slots() と clear_slots() は、スロットごとの slots、
side_effects、structure_changes も返します。説明は update_slots() にあります。
ステータスの値¶
|
意味 |
|---|---|
|
確定(メモリ内に保存済み)。
要求した変更は、エディターの通常の正規化を経て読み戻したとおり、メモリ内に保存されています。
|
|
一部だけ保存。要求の一部を保存した後、後続の部分が拒否されたか失敗しました。
試みていない部分は |
|
dry run の受理。 |
|
実行可能と確認済み。 |
|
変更なし(書き込まない)。要求は保存値とすでに一致しています。何も書き込んでいません。
Router と Property Stack の dry run は、代わりに |
|
拒否。要求した変更は保存されていません。 |
|
失敗後に復元済み。書き込みが失敗しました。保存値を書き戻し、 読み戻しが呼び出し前の値と一致しています。Blender の登録は別に観測します。 |
|
状態不明(読み直す)。書き込みが失敗し、保存状態を確認できませんでした。 再試行の前に対象を読み直します。 |
結果の中の項目は、それぞれ独自の status を持ちます:
slotsの項目(スロット操作)とfieldsの項目(update_pm()):committed、unchanged、rejected。groupsの項目(update_property()):committed、rejected、restored_failure、unknown。registration(update_hotkey()、set_enabled()):registered、not_required、partial、unknown。visibility(set_enabled()):observedまたはunknown。
登録と可視性は Blender の現在の状態の観測であり、操作の結果ではありません。
確定ステータスが示す範囲¶
メモリ内の保存定義。Preferences はディスクに保存されません(基本事項)。
表示や動作は含みません。読み戻しで確認できるのは保存定義です。 表示と動作は、メニューが対象とするエディターとモードで別に観測します。 たとえば、Knife ツールを有効にする Command スロットが確定した場合、 そのスロットを実行するとアクティブツールが変わります。それだけで形状を切断するわけではありません。
問題がないことは示しません。
committedに診断が付く場合があります。 正規化の注記、警告、確認が必要な保存定義などです。保存後の refresh が失敗しても、確定は取り消されません。 失敗は
diagnosticsまたは例外の注記で報告します。
ガード¶
ガードは、何かを書き込む前に、呼び出し側が持つ保存状態の写しと現在の状態を比較します。
一致しない場合は、status "rejected" と、その操作の stale 診断を返します。
stale 診断は 操作ごとの結果とガードの語彙 に一覧があります。
入力 |
比較するもの |
値の取得元 |
|---|---|---|
|
メニューのセッション内のバージョン(int)。
stale のコードは |
|
|
保存値。下の 3 つの形式のいずれか。 |
|
|
Router、Property Stack、Property の保存データのハッシュ(str)。 |
|
expected_version と expected は互いに独立しています。
version は、Python からの直接の書き込みをすべて検出するものではありません。
expected は保存値を比較するため、それらも検出します。
expected_version を受け付けるのは、update_slots()、
clear_slots()、add_slot()、remove_slot()、
move_slot()、swap_slots() と、行・spacer・panel の操作です。
transfer_slot() は受け付けません。
expected の形式¶
形式 |
操作 |
規則 |
|---|---|---|
保存値の一部 |
|
その部分について |
保存値の全体 |
|
キーの不足や余分は |
以前の呼び出しのスナップショット |
|
以前の呼び出し(通常は dry run)が返した |
move_slot() と swap_slots() は、Pop-up Dialog と Floating Panel 以外のメニューで
expected を渡すと TypeError を送出します。
dry_run¶
dry_run=Trueは、実際の呼び出しと同じ検査を現在の保存値に対して実行し、何も書き込みません。 保存値、バージョン、UID は元のままです。エディターの hook と refresh は実行しません。受理された dry run は
validated(update_hotkey()とdelete_pms()ではready)を返します。 操作ごとの結果とガードの語彙 に記載がある操作では、unchangedを返す場合もあります。beforeとafterがある場合、それらは予測ではなく保存値を示します。 予測値を返す場合、それはproposed(update_hotkey())、 またはcandidate(update_property()、Router と Property Stack の操作)です。dry run の
expectedは、適用する呼び出しに渡せます。適用する呼び出しは UID を解決し直し、すべての検査を繰り返します。
validatedは成功を予約せず、エディターの hook、refresh、Blender の登録も検査しません。update_slots()、clear_slots()、update_pm()にはdry_runがありません。
操作ごとの結果とガードの語彙¶
その他のステータス は、確定と dry run の値以外の値を挙げます。 ガードの入力 は、ガードの引数と stale 診断のコードを示します。
操作 |
確定 |
dry run の受理 |
その他のステータス |
ガードの入力 |
|---|---|---|---|---|
|
なし |
|
なし |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
読み取り専用。 |
なし |
なし |
なし |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
診断¶
diagnostics は dict の list です。すべての項目が code を持ちます。
その他のキーは項目によって異なります。
キー |
含まれる項目 |
値 |
|---|---|---|
|
すべての項目 |
|
|
大半の項目 |
人が読むための説明。 |
|
名前のある入力に関する項目 |
入力名、または名前の list。
stale のガードは、異なる名前を |
|
スロット操作 |
その項目が関係するスロット。 |
|
Router と Property Stack の操作 |
|
|
一部の項目 |
|
|
捕捉した例外の項目 |
例外のクラス名。traceback は Blender のコンソールに出力します。 |
|
|
|
|
|
渡したバージョンと現在のバージョン。 |
|
|
渡したテキスト内の構文エラーの位置。 検査の前に、テキストの空白除去や字下げの変更は行いません。 |
診断があること自体は失敗を意味しません。判定は
statusで行います。committedの結果にも診断が付く場合があります。関数固有のコードは、その関数の説明に記載します。
例外¶
例外 |
送出する条件 |
保存状態 |
|---|---|---|
|
Blender のメインスレッド以外からの呼び出し、PME の読み込み完了前の呼び出し、 または PME の Preferences がない状態での呼び出し(基本事項)。 |
触れません。 |
|
引数の型が誤っている。マッピングでない |
書き込みません。最初の書き込みの前に送出します。 |
|
未知のフィールド、不正な値、矛盾する引数、 または存在しない・不正・曖昧なメニュー UID。 |
書き込みません。最初の書き込みの前に送出します。 |
書き込み開始後の任意の例外 |
書き込み、エディターのコールバック、setter、refresh のいずれかが例外を送出した。 |
一部が変更されている場合があります。traceback を保持し、注記を追加します。 |
書き込み開始後に、エディターやコールバックが
TypeErrorやValueErrorを送出する場合もあります。 例外のクラスは、何も変わっていないことの証明になりません。 traceback と注記を保持し、再試行の前に対象を読み直します。注記は例外の
__notes__にあり、traceback とともに出力します。 注記は、確定した内容または読むべき対象を示します:update_slots()、clear_slots(): 確定したスロット UID と、保存中だったスロット。update_pm():確定したフィールドと、例外を送出した段階。update_hotkey():保存値の読み戻し、変更したフィールド、登録の読み戻し。Pop-up Dialog と Floating Panel 以外のメニューでの
add_slot()、remove_slot()、move_slot()、swap_slots():呼び出し前のスロットの順序。update_property():保存定義を復元したかどうか。Router と Property Stack の操作:再試行の前にメニューを読むよう求める指示。 Property Stack の注記は、最後に報告したステータスも示します。
Router と Property Stack の操作は、不正な形式の入力に対して例外を送出しません。
dry_run_must_be_a_boolean、expected_digest_must_be_a_string、branches_must_be_a_sequenceなどの診断とともにrejectedを返します。update_settings()、set_enabled()、update_tags()、duplicate_pm()、delete_pms()、transfer_slot()と、 Pop-up Dialog または Floating Panel でのスロット操作・レイアウト操作は、 書き込みの失敗を例外として送出せずに捕捉します。 traceback を出力し、restored_failureまたはunknownを返し (update_tags()はrejectedまたはunknown)、 失敗をdiagnosticsで説明します。