結果とガード

pme.editing のすべての編集関数は dict を返します。 このページは、それらの結果に共通する要素を定義します。 status の値、古い入力を拒否するガード、dry_run、診断の項目、例外です。 1 つの関数だけが持つキーは、その関数の説明に記載します。

成功、事前確認、古い入力を表す値の名前は、操作ごとに決まっています。 操作ごとの結果とガードの語彙 に一覧があります。 呼び出し側は、1 つの綴りを仮定せず、そこに挙げた値で判定します。

共通の結果キー

キー

型

値

status

str

ステータスの値 のいずれかの値。 すべての結果にあります。

committed

bool

status が "committed" のときだけ True。

dry_run

bool

dry_run 引数の値。 スロット、レイアウト、移送の結果にはこのキーがありません。

pm_uid

str

メニュー UID。1 つのメニューに対する大半の操作の結果にあります。

before, after

dict または None

呼び出しの前と後に読んだ保存値。 形と有無は各関数の説明に記載します。

expected

dict

後の呼び出しに expected として渡す値。 ガードがスナップショットである操作にあります(ガード)。

pending

list

保存を試みていない部分(スロット UID、メタデータのフィールド名、Property のグループ)。 エディターのコールバックなど、先の段階がそれらを変更している場合があります。 pending は未変更を意味しません。

recovery

dict、str または None

書き込み失敗後の復元の詳細。 形は各関数の説明に記載します。

diagnostics

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() にあります。

ステータスの値

status

意味

committed

確定(メモリ内に保存済み)。 要求した変更は、エディターの通常の正規化を経て読み戻したとおり、メモリ内に保存されています。 update_slots()、clear_slots()、update_pm() では、 要求した部分のうち少なくとも 1 つが保存され、拒否された部分がない状態です。 個々の部分は unchanged の場合があります。 すべての部分がすでに要求どおりの値なら、結果は unchanged です。

partial

一部だけ保存。要求の一部を保存した後、後続の部分が拒否されたか失敗しました。 試みていない部分は pending にあります。 update_slots()、clear_slots()、 update_pm()、update_property() だけが返します。

validated

dry run の受理。dry_run=True で、要求がすべての検査を通過しました。 何も書き込んでいません。

ready

実行可能と確認済み。validated と同じ意味で、 update_hotkey() と delete_pms() が返します。

unchanged

変更なし(書き込まない)。要求は保存値とすでに一致しています。何も書き込んでいません。 Router と Property Stack の dry run は、代わりに validated を返します。

rejected

拒否。要求した変更は保存されていません。diagnostics が原因を示します。 エディターのコールバックを実行したスロット操作では、コールバックによる変更が残る場合があり、 after と side_effects に示されます。

restored_failure

失敗後に復元済み。書き込みが失敗しました。保存値を書き戻し、 読み戻しが呼び出し前の値と一致しています。Blender の登録は別に観測します。

unknown

状態不明(読み直す)。書き込みが失敗し、保存状態を確認できませんでした。 再試行の前に対象を読み直します。

結果の中の項目は、それぞれ独自の 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 診断は 操作ごとの結果とガードの語彙 に一覧があります。

入力

比較するもの

値の取得元

expected_version

メニューのセッション内のバージョン(int)。 stale のコードは stale_version で、expected と actual を持ちます。

read_pm()["version"]、または以前のスロット操作やレイアウト操作の結果の version。

expected

保存値。下の 3 つの形式のいずれか。

read_pm()、または以前の結果の expected。

expected_digest

Router、Property Stack、Property の保存データのハッシュ(str)。

read_pm()["router"]["digest"]、 read_pm()["property_stack"]["digest"]、 または read_pm()["property"]["digest"]。

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 の形式

形式

操作

規則

保存値の一部

update_pm() (メタデータ)、update_settings() (設定)、 update_slots() と clear_slots() (スロット UID からスロットのフィールドへの対応)、 Pop-up Dialog と Floating Panel 以外のメニューでの remove_slot() (そのスロットのフィールド)

その部分について read_pm() が返すキーの任意の部分集合。 値が異なるキーがあると、呼び出しを拒否します。 保存値にないキーも stale として扱います。 ただし update_pm() は、未知のフィールドに対して ValueError を送出します。 update_slots() と clear_slots() は、 編集対象でないスロット UID に対して ValueError を送出します。

保存値の全体

update_hotkey() (read_pm()["hotkey"] の 13 フィールドちょうど)、 set_enabled() (要求したすべての UID から保存済みの bool への対応)

キーの不足や余分は ValueError を送出します。

以前の呼び出しのスナップショット

add_slot()。 Pop-up Dialog または Floating Panel での remove_slot()、move_slot()、 swap_slots() と、行・spacer・panel の操作。 transfer_slot()、update_tags()、duplicate_pm()、 delete_pms()

以前の呼び出し(通常は dry run)が返した result["expected"] を、変更せずに渡します。 違いがあれば呼び出しを拒否します。

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 の受理

その他のステータス

ガードの入力

pme.create_pm()

accepted が True (dict ではなくオブジェクト)

なし

accepted が False で diagnostics あり

なし

update_slots()、clear_slots()

committed

dry_run なし

unchanged、partial、rejected

expected_version、expected (スロット UID からスロットのフィールドの一部への対応)。 stale_version、stale_slot

update_pm()

committed

dry_run なし

unchanged、partial、rejected

expected (メタデータの一部)。stale_metadata

update_settings()

committed

validated、unchanged

unchanged、rejected、restored_failure、unknown

expected (設定の一部)。stale_settings

update_hotkey()

committed

ready、unchanged

unchanged、rejected

expected (ホットキーの 13 フィールドすべて)。stale_hotkey

set_enabled()

committed

validated、unchanged

unchanged、rejected、restored_failure、unknown

expected (UID から保存済みの bool への対応、全対象)。 pm_availability_expected_mismatch

update_tags()

committed

validated。空の要求では unchanged

unchanged、rejected、unknown

expected (スナップショット)。tag_expected_stale

duplicate_pm()

committed

validated

rejected、restored_failure、unknown

expected (スナップショット)。pm_duplicate_stale_expected

delete_pms()

committed

ready

rejected、restored_failure、unknown

expected (スナップショット)。pm_remove_saved_state_stale

read_pm()、read_slot_inputs()、 slot_fields()、resolve_auto_icons()、 setting_fields()、find_references()

読み取り専用。status はなく、何も書き込みません

なし

なし

なし

add_slot()

committed

validated

rejected。Pop-up Dialog または Floating Panel では restored_failure、unknown も

expected_version、expected (スナップショット)。stale_version、 stale_snapshot、stale_popup (Pop-up)

remove_slot()

committed

validated

rejected。Pop-up Dialog または Floating Panel では restored_failure、unknown も

expected_version、expected (そのスロットのフィールド。Pop-up ではスナップショット)。 stale_version、stale_slot、stale_popup

move_slot()、swap_slots()

committed

validated、unchanged

unchanged、rejected。Pop-up Dialog または Floating Panel では restored_failure、unknown も

expected_version、expected (スナップショット。Pop-up のみ)。 stale_version、stale_popup

transfer_slot()

committed

validated

rejected、restored_failure、unknown

expected (スナップショット)。expected_version なし。stale_transfer

add_row()、add_panel()、remove_row()、 split_row()、join_rows()

committed

validated

rejected、restored_failure、unknown

expected_version、expected (スナップショット)。stale_version、 stale_popup

move_row()、update_row()、update_spacer()、 align_slot()

committed

validated、unchanged

unchanged、rejected、restored_failure、unknown

expected_version、expected (スナップショット)。stale_version、 stale_popup

update_property()

committed

validated、unchanged

unchanged、partial、rejected、restored_failure、 unknown

expected_digest。stale_property

remove_router_branch()

committed

validated

rejected、unknown

expected_digest。stale_router_digest

update_router()、move_router_branch()、 reorder_router_branches()

committed

validated

unchanged、rejected、unknown

expected_digest。stale_router_digest

update_property_stack()

committed

validated

unchanged、rejected、unknown

expected_digest。stale_property_stack_digest

add_property_stack_row()、 update_property_stack_row()、 remove_property_stack_row()

committed

validated

unchanged、rejected、unknown

expected_digest。stale_property_stack_digest

update_property_stack_hud()

committed

validated、unchanged

unchanged、rejected、restored_failure、unknown

expected ( while_true_hud の一部)。stale_property_stack_hud

診断

diagnostics は dict の list です。すべての項目が code を持ちます。 その他のキーは項目によって異なります。

キー

含まれる項目

値

code

すべての項目

stale_settings などの機械可読な識別子。

message

大半の項目

人が読むための説明。

field / fields

名前のある入力に関する項目

入力名、または名前の list。 stale のガードは、異なる名前を fields に挙げます。

pmi_uid

スロット操作

その項目が関係するスロット。

path

Router と Property Stack の操作

logic.branches[0].target など、入力またはロジック内の位置。

severity

一部の項目

"error" または "warning"。Property Stack の項目は常に持ちます。 それ以外では、ホットキーの衝突、削除後に残った参照、 解決できない Router のメニュー対象などの警告を示します。

exception_type

捕捉した例外の項目

例外のクラス名。traceback は Blender のコンソールに出力します。

phase

update_tags()、delete_pms()、set_enabled()

preflight や readback など、その項目を生成した段階。

expected, actual

stale_version

渡したバージョンと現在のバージョン。

line, column

invalid_syntax (スロット操作)

渡したテキスト内の構文エラーの位置。 検査の前に、テキストの空白除去や字下げの変更は行いません。

  • 診断があること自体は失敗を意味しません。判定は status で行います。 committed の結果にも診断が付く場合があります。

  • 関数固有のコードは、その関数の説明に記載します。

例外

例外

送出する条件

保存状態

RuntimeError

Blender のメインスレッド以外からの呼び出し、PME の読み込み完了前の呼び出し、 または PME の Preferences がない状態での呼び出し(基本事項)。

触れません。

TypeError

引数の型が誤っている。マッピングでない changes や、 bool でない dry_run など。

書き込みません。最初の書き込みの前に送出します。

ValueError

未知のフィールド、不正な値、矛盾する引数、 または存在しない・不正・曖昧なメニュー 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 で説明します。