Property

Property(メニューの種類 PROPERTY)は、ユーザープロパティを 1 つ定義します。 定義には型、引数、Enum 項目、コールバック、保存先、Property ID が含まれます。 定義は項目名で読み取り、変更します。 Property Stack は Property Stack で説明します。

関数

用途

read_pm()

定義を property に入れて返します。

update_property()

定義、保存先、Property ID を変更します。

関連項目: 設定を Property のスイッチにする。

Property を読み取る

read_pm(pm_uid)["property"] は、update_property() が受け付ける項目名で表した定義に、 registered_property_id、digest、diagnostics を加えたものです。 Property の型と保存先に該当する項目だけが入ります。Property の定義 を参照してください。 値はエディターに表示される値です。読み取りでは Getter を評価しません。

>>> pme.editing.read_pm(pm_uid)["property"]
{'type': 'BOOL', 'size': 1, 'default': False, 'expand': True,
 'horizontal': True, 'restore_default': False, 'get': None, 'set': None,
 'update': None, 'init': None, 'storage': None, 'property_id': 'my_toggle',
 'property_id_locked': False, 'registered_property_id': 'my_toggle',
 'digest': '42aaaef6...', 'diagnostics': []}

新しい Property は、コールバックを持たず、値を保存する Boolean です。

diagnostics には、保存されている定義の問題が入ります。

code

原因と追加のキー

callback_compile_error

保存されたコールバックに構文エラーがあります。field がそのコールバックを示し、 severity は "warning" です。

argument_unreadable

保存された引数が Python のリテラルではありません。field が引数を示し、 text に保存されたテキストが入ります。項目にはエディターの既定値が表示されます。

値の置き場所

storage が値の所有者を決めます。registered_property_id は Property が登録された名前です。

storage

値の所有者

読み方

None

Addon Preferences。PME が値を 1 つ持ちます。

pme.props(registered_property_id)。

"Object" などの ID 型名

その型の各データブロックが、registered_property_id という名前の属性として自分の値を持ちます。

getattr(data_block, registered_property_id)。pme.props() はこの値を持ちません。pme.props(registered_property_id) は None を返すか、 Addon Preferences で同じ ID を使う別の Property の値を返します。

prop = pme.editing.read_pm(property_uid)["property"]
name = prop["registered_property_id"]
if prop["storage"] is None:  # Addon Preferences: one value
    value = pme.props(name)
    widget = f"L.prop(props(), {name!r})"
else:  # "Object": a value on each object
    value = getattr(bpy.context.object, name)
    widget = f"L.prop(C.object, {name!r})"

Property が無効の間、registered_property_id は空です。 Property ID の規則は Property ID と移行 にあります。

Property の定義

read_pm()["property"] の項目です。最後の 3 つ以外は update_property() が受け付けます。 既定値 は、一度も設定されていない項目にエディターが表示する値です。 引数 default、min、max、step、precision、subtype、unit は、 同じ名前で Blender の bpy.props の関数に渡されます。 update_property() で None を渡すと、その引数は既定値に戻ります。

項目

型

適用対象

既定値

意味

type

str

すべて

"BOOL"

"BOOL"、"INT"、"FLOAT"、"STRING"、"ENUM" のいずれか。

size

int

BOOL, INT, FLOAT

1

Property Size。1 は単一の値、2〜32 はその個数の成分を持つベクトルです。

default

bool, int, float, str or list

すべて

BOOL は False、INT と FLOAT は 0、STRING は ""。ベクトルは size 個のそれらの値のリスト。ENUM は最初の項目の識別子で、項目がなければ None。 Multi-Select は []

Default Value。ベクトルの既定値は、ちょうど size 個の値のリストです。 Enum の既定値は識別子 1 つです。Multi-Select の既定値は識別子の list、tuple、set のいずれかで、ソートした list として読み戻されます。

min

int or float

INT, FLOAT

-2147483648

Min Value。INT では 32 bit 整数、FLOAT では有限の数です。

max

int or float

INT, FLOAT

2147483647

Max Value。規則は min と同じです。

step

int or float

INT, FLOAT

1 (INT)、3 (FLOAT)

Step。規則は min と同じです。

precision

int

FLOAT

2

Precision。0〜6。

subtype

str

INT, FLOAT, STRING

"NONE"

Subtype。Subtype の値 を参照してください。

unit

str

FLOAT

"NONE"

Unit。Unit の値 を参照してください。

multiselect

bool

ENUM

False

Multi-Select。値は識別子の集合です。

expand

bool

すべて

True

Expand。

horizontal

bool

BOOL, INT, FLOAT, ENUM

True

Horizontal Layout。

restore_default

bool

storage が None

False

Restore Default Value。PME の初期化時に保存値を破棄し、default から始めます。

items

list[dict]

ENUM

[]

順序どおりの Enum 項目。Enum 項目 を参照してください。

get

str or None

すべて

None

Getter の本文。その return が値になります。None: Getter なし。

set

str or None

すべて

None

Setter の本文。Getter が必要です。None: Setter なし。

update

str or None

すべて

None

On Update の本文。None: On Update なし。

init

str or None

すべて

None

On Init の本文。None: On Init なし。

storage

str or None

すべて

None

Addon Preferences なら None、または "Object" や "Scene" などの Blender の ID 型名。値の置き場所 を参照してください。

property_id

str

すべて

メニュー名から生成

保存された Property ID。

property_id_locked

bool

すべて

False

Lock。True のとき、Property ID はメニュー名の変更に追従しません。

registered_property_id

str

読み取り専用

Property が登録された名前。Property が無効、または登録されていない間は空です。

digest

str

読み取り専用

保存された定義の 16 進 digest。expected_digest として渡します。

diagnostics

list[dict]

読み取り専用

保存された定義の問題。Property を読み取る を参照してください。

コールバックで使える変数は Getter / Setter / On Update / On Init にあります。

Enum 項目

items の各要素:

キー

型

値

uid

str

既存の項目の UID。入力では、既存の UID を渡すとその項目の identity を保ちます。 新しい項目では省略するか、"" または None を渡します。

identifier

str

必須。スクリプトで使う値です。空ではなく、空白や | を含まず、 Property 内で一意です。

name

str

表示ラベル。| を含みません。省略または空のときは識別子を使います。

icon

str

Blender のアイコン名。省略時は ""。

items は Enum 項目を渡した順序で置き換えます。Enum の値は、エディターと同じく項目の順序に従います。 識別子に GET、SET、UPDATE、INIT、CLASS、default、min、max、step、 precision、subtype、unit は使えません。Multi-Select の Enum は最大 31 項目です。

Subtype の値

Property

受け付ける subtype

INT または FLOAT、size 1

PIXEL、UNSIGNED、PERCENTAGE、FACTOR、ANGLE、 TIME、TIME_ABSOLUTE、DISTANCE、DISTANCE_CAMERA、 POWER、TEMPERATURE、NONE

INT または FLOAT、size 2〜32

COLOR、TRANSLATION、DIRECTION、VELOCITY、 ACCELERATION、MATRIX、EULER、QUATERNION、AXISANGLE、 XYZ、XYZ_LENGTH、COLOR_GAMMA、COORDINATES、LAYER、 LAYER_MEMBER、NONE

STRING

FILE_PATH、DIR_PATH、FILE_NAME、BYTE_STRING、 PASSWORD、NONE

Unit の値

unit は Blender の FloatProperty.unit の識別子を受け付けます。 Blender 5.2 では NONE、LENGTH、AREA、VOLUME、ROTATION、TIME、 TIME_ABSOLUTE、VELOCITY、ACCELERATION、MASS、CAMERA、 POWER、TEMPERATURE、WAVELENGTH、COLOR_TEMPERATURE、FREQUENCY です。 一覧は実行中の Blender から読み取ります。

初期化の規則

エディター自身の規則が、この順に適用されます。 同じ呼び出しで渡した値は、これらの初期化のあとに適用されます。

変更

影響

type

size は 1、multiselect は False、horizontal は True、 items は [] になります。default、min、max、step、 precision、subtype、unit は、新しい型のエディター既定値に戻ります。 コールバック、expand、restore_default、storage、Property ID は保持されます。

items

一度も設定されていない default、または以前の最初の項目を指す default は、 新しい最初の項目に追従します。削除された識別子を指す default は、 default も渡さない限り default_not_in_items で拒否されます。

multiselect

default はエディター既定値に戻ります。オンなら []、オフなら最初の項目です。

size

subtype と unit は "NONE" になります。default は新しいサイズに合わせて切り詰められるか補われます。サイズ 1 では最初の成分が残ります。

関数

pme.editing.update_property(pm_uid, changes, *, expected_digest=None, dry_run=False)

Property の定義、保存先、Property ID を、エディターと同じ処理で変更します。

すべての変更を、最初の書き込みの前に検査します。1 つでも拒否されれば、何も書き込みません。 そのあと、変更を 3 つのグループに分け、決まった順序で保存します。

パラメータ:
  • pm_uid (str) -- Property の UID。

  • changes (dict) -- 項目名と新しい値の対応。項目名は Property の定義 の項目のうち、読み取り専用のもの以外です。 部分指定です。指定しない項目は、初期化の規則 による変化を除き、 値を保持します。None は引数をエディター既定値に戻し、コールバックを削除します。

  • expected_digest (str or None) -- read_pm()["property"]["digest"]。保存されている Property が変わっている場合、更新は stale_property で拒否されます。

  • dry_run (bool) -- 変更を検査し、書き込まずに返ります。

戻り値:

下で説明する結果。

戻り値の型:

dict

例外:
  • TypeError -- changes がマッピングではない。multiselect、 expand、horizontal、restore_default、 property_id_locked が bool ではない。コールバックが文字列でも None でもない。property_id が文字列ではない。storage が None でも空でない文字列でもない。items がマッピングのシーケンスではない、項目の identifier が文字列ではない、または uid、name、icon が文字列でも None でもない。expected_digest が文字列でも None でもない。dry_run が bool ではない。

  • ValueError -- 項目名が不明。type が 5 つの型のいずれでもない。 size が 1〜32 の整数ではない。項目に uid、identifier、name、icon 以外のキーがある。UID がない、不正、または曖昧。メニューが Property ではない。

  • RuntimeError -- Blender のメインスレッド以外から呼ばれた、PME の読み込みが完了していない、または PME の Preferences を利用できない。

グループ

group

実行される条件

保存処理

storage

storage が保存値と異なる。

エディターの保存先の設定。移動先の保存先に合わせて、新しい Property ID を選ぶことがあります。

property_id

保存されている Property ID または Lock が、要求されたものと異なる。 保存先グループが選んだ ID も含みます。

エディターの Edit Property ID。

definition

その他の項目が保存値と異なる。

エディターの各項目のあと、Blender への 1 回の登録。

各グループの終了時点で、Property は完成した形です。 groups は実行したグループ、pending は実行しなかったグループを示します。

結果

キー

型

値

status

str

下の ステータス を参照してください。

committed

bool

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

dry_run

bool

dry_run 引数。

pm_uid

str

pm_uid 引数。

before

dict

呼び出し前の read_pm()["property"]。

after

dict

呼び出し後の read_pm()["property"]。何も書き込まなければ before と同じです。

candidate

dict or None

保存する定義。storage、property_id、property_id_locked を含みます。 変更が拒否されたときは None。

changed_fields

list[str]

before と after で値が異なる項目名。dry run のあとは空です。

groups

list[dict]

実行したグループごとに 1 要素: group と status ("committed"、"rejected"、"restored_failure"、 "unknown" のいずれか)。dry run のあとは空です。

pending

list[str]

実行が必要で、実行されなかったグループ。dry run のあとは、実行されるはずのグループ。

registration

dict or None

definition グループが実行されたときに設定されます。下の 登録 を参照してください。storage と property_id のグループも Property を登録します。どのグループのあとでも、after["storage"] と after["registered_property_id"] が、登録先と登録名を示します。

recovery

dict or None

グループが失敗したあとに設定されます: scope (そのグループ) と saved_definition_matches。

diagnostics

list[dict]

問題ごとに 1 要素: code、field (または fields)、 message と、診断 に挙げる詳細。警告には severity: "warning" も付きます。

登録

キー

型

値

status

str

"committed"、"failed"、または Property が無効の間は "not_applicable"。

registered_property_id

str

Property が登録された名前。登録されていないときは空です。

reason_code

str

成功時は空。無効な Property では property_disabled。 それ以外では失敗した段階のコード (host_registration_failed など)。

failed_stage

str

成功時は空。それ以外では失敗した段階: validate、 claim、resolve_owner、prepare_metadata、 inspect_native、migrate、migrate_native、 prepare_cleanup、register_new、commit_ownership、 publish、commit_metadata のいずれか。

blocked_owner

str

保存値の移動を妨げたデータブロック (Object 'Cube' など)。 それ以外では空です。

ステータス

共通の語彙は ステータスの値 にあります。

status

意味

committed

実行が必要なすべてのグループが保存されました。

validated

dry_run=True で、変更を受け付けられます。何も書き込んでいません。

unchanged

変更が保存されている Property と一致します。何も書き込んでいません。 dry run でも返ります。

rejected

保存されている Property は変わっていません。diagnostics が原因を示します。 原因は検査、または最初に実行したグループの失敗です。

partial

先のグループが確定したあとで、グループが失敗しました。先のグループは保存されたままです。pending が実行されなかったグループを示します。

restored_failure

Blender が保存した定義の登録を拒否し、保存した定義を元に戻しました。

unknown

失敗したグループが保存されている Property を変えたまま残したか、 復元を確認できませんでした。recovery["scope"] がそのグループを示します。 再試行の前に read_pm() を呼んでください。

診断

拒否: 最初の書き込みの前に検査します。ステータスは rejected です。 警告: ステータスに影響しません。グループ: 書き込み中にグループが失敗しました。

code

影響

原因と追加のキー

stale_property

拒否

expected_digest が保存されている digest と異なります。field は "digest" です。

field_not_applicable

拒否

項目が変更後の型に該当しない、または ID の保存先に restore_default が指定されています。

default_type_mismatch

拒否

default の型が違う、またはベクトルで長さが違います。

default_not_in_items

拒否

指定した、または保持した default が、項目にない識別子を指しています。 missing がそれらを列挙します。

argument_type_mismatch

拒否

min、max、step が整数 (INT) または有限の数 (FLOAT) ではない、 または precision が整数ではありません。

argument_out_of_range

拒否

precision が 0〜6 の範囲外の整数。INT の default、 min、max、step が 32 bit の範囲 (-2147483648〜2147483647) 外の整数。または FLOAT の default、min、 max、step が 32 bit float の範囲 (約 ±3.4028235e38) 外の有限の数で、 Blender が無限大として登録してしまう値。field がその項目を示します。

argument_not_a_choice

拒否

subtype または unit が、その型とサイズで受け付けられない値です。 choices が受け付ける値を列挙します。

min_greater_than_max

拒否

結果の min が max より大きくなります。min と max が両方の値を示します。もう一方の境界値を読めない場合は検査しません。

multiselect_item_limit

拒否

Multi-Select の Enum が 31 項目を超えます。limit と count が数を示します。

item_identifier_invalid

拒否

識別子が空、または空白や | を含みます。index が項目を示します。

item_identifier_duplicate

拒否

識別子が前の識別子と重複しています。index が項目を示します。

item_identifier_reserved

拒否

識別子が予約された名前です (Enum 項目 に記載)。 index が項目を示します。

item_name_invalid

拒否

名前が | を含みます。index が項目を示します。

item_uid_duplicate

拒否

2 つの項目が同じ uid を指定しています。

item_uid_unknown

拒否

uid がこの Property の項目ではありません。uids がそれらを列挙します。

set_requires_get

拒否

結果が Getter のない Setter になります。

argument_unreadable_would_be_replaced

拒否

リテラルではない保存済みの引数が、呼び出しで指定していない値に置き換わります。 text に保存されたテキストが入ります。その引数を明示的に渡すと置き換えます。

storage_type_unknown

拒否

storage が Blender の ID 型名ではありません。

empty、too_long、invalid_identifier、non_ascii、 python_keyword、reserved_access_name

拒否

Property ID が空、63 バイトより長い、ASCII 英字で始まり英数字と _ が続く形ではない、非 ASCII、Python のキーワード、または keys、values、items、 get のいずれかです。property_id または storage が変わるときに検査します。

owner_reserved

拒否

移動先の保存先に、その名前の属性がすでにあります (Blender のプロパティや、 別の Property が登録したプロパティなど)。

manual_prop_id_collision

拒否

同じ保存先の別の Property が、その Property ID を保存しています。

reserved

拒否

Property ID がほかの理由で予約されています。

callback_compile_error

警告

指定したコールバックに構文エラーがあります。エディターと同じく保存されます。

argument_unreadable

警告

リテラルではない保存済みの引数が保持されます。text に保存されたテキストが入ります。

property_readback_differs

警告

確定後、保存されている Property が candidate と異なります。 fields が項目名を列挙します。

storage_registration_failed

グループ

保存先グループが受け付けられませんでした。message はエディターの報告をつなげたものです。

Property ID 段階のコード

グループ

property_id グループが受け付けられませんでした。code は上の Property ID のコード、runtime_prop_id_register_failed、または登録の reason_code です。effect_codes が実行した段階を列挙します。

definition_registration_failed

グループ

Blender が保存した定義の登録を拒否しました。registration に詳細が入ります。

例

新しい Property を、長さの単位を持つ 0〜1 の Float にします。

created = pme.create_pm(pme.PmCreationSpec("PROPERTY", name="Bevel Width"))
before = pme.editing.read_pm(created.pm_uid)["property"]
result = pme.editing.update_property(
    created.pm_uid,
    {"type": "FLOAT", "default": 0.1, "min": 0.0, "max": 1.0, "unit": "LENGTH"},
    expected_digest=before["digest"],
)
assert result["status"] == "committed", result["diagnostics"]

補足

  • storage が変わるとき、要求された、または保持される Property ID を、 移動先の保存先で検査します。

  • 検証、保存、読み取りのいずれもコールバックを実行しません。On Init も実行されません。

  • 保存値は通常の登録の規則に従います。エディターと同じく、type や size を変えると保存値は破棄されます。失敗後に保存値は復元されません。

  • 確定したグループ、または unknown で終わったグループは、 read_pm()["version"] を 1 増やします。

  • 選択中のメニューと、編集中の下書きは変わりません。

  • 定義グループの保存中に発生した例外は、保存した定義を復元したあとで再送出されます。 その注記に、復元を確認できたかどうかが記されます。再試行の前に read_pm() を呼んでください。

  • この呼び出しは、Preferences のディスクへの保存、Undo ステップの追加、 Property の表示を行いません。