Property Stack¶
A Property Stack (menu type CONDITION) combines condition rows into one
Boolean switch and writes settings when the switch is set. Its logic is
replaced as a whole or edited one condition row at a time. The While True HUD
has its own function; the logic functions leave it and the Property ID
unchanged. A single Property is described on Property.
Function |
Purpose |
|---|---|
Returns the logic and registration under |
|
Replaces the complete logic. |
|
Appends an empty condition row. |
|
Changes one condition row. |
|
Removes one condition row and its derived write entry. |
|
Changes the While True HUD. |
See also: Author a Property Stack and show its state, and the Property Stack Editor for the meaning of evaluation-only rows and write modes.
Reading a Property Stack¶
read_pm(pm_uid)["property_stack"] holds:
Key |
Type |
Value |
|---|---|---|
|
dict or None |
The saved logic as the storage decoder reads it. See
Logic. |
|
str |
Hex digest of the saved logic text. Pass it as |
|
str |
Saved Property ID. |
|
str |
ID the Property Stack is currently registered under. Empty when it is not registered. |
|
dict |
While True HUD settings. Changed with
|
|
list[dict] |
Problems found while reading the saved logic, with |
>>> pme.editing.read_pm(stack_uid)["property_stack"]
{'logic': {'version': 1, 'combine_mode': 'all', 'predicate_rows': [],
'write_plan': {'false_policy': 'no_op', 'entries': []}},
'digest': 'e3b0c442...', 'property_id': 'surface',
'registered_property_id': 'surface',
'while_true_hud': {'enabled': False, 'message': '', 'is_expr': False,
'area_type': 'VIEW_3D', 'alignment': 'TOP',
'display': 'LABEL', 'icon': '', 'use_color': False,
'color': [1.0, 1.0, 1.0]},
'diagnostics': []}
Reading does not evaluate the Getter or run the Setter.
registered_property_id is the ID a widget uses, for example
L.prop(props(), registered_property_id). It is not derived from the menu
name.
while_true_hud has the keys of Schema v2 PropertyStackWhileTrueHud.
The values of a new Property Stack are shown above. The fields are listed
under While True HUD fields; the editor is described under
While True HUD — notify while conditions match.
logic is the storage decoder’s normalized view, not the raw stored JSON.
The view can omit unsupported or stale write entries, or turn writes off.
property_stack_storage_normalized reports each difference. When logic
is None, the row operations reject the stack and
update_property_stack() replaces it.
Codes in diagnostics:
|
Cause, and extra keys |
|---|---|
|
The saved text is not JSON, or an integer value of a |
|
The saved value is not text. |
|
The saved JSON is not an object. |
|
|
|
Two write entries share an |
|
|
|
A write entry has |
|
A write entry’s PME Property or Property Stack source is not read-only.
|
|
A write to a PME Property has no matching condition row. The view omits it. |
|
A write entry has an unknown |
|
The view differs from the saved JSON. |
Each entry has code, path, severity and scope. The decoder codes
also have address (a position such as entry_index) and blocking
(True when logic is None). severity is "error" for a
blocking code and "warning" otherwise.
Common result¶
The four editing functions return the same keys. The row operations add
condition_uid.
Key |
Type |
Value |
|---|---|---|
|
str |
See Status below. |
|
bool |
|
|
str |
The |
|
bool |
The |
|
dict or None |
|
|
dict or None |
|
|
dict or None |
The logic to save, in the form of |
|
list[dict] |
One entry per problem. See Diagnostic entries below. |
|
str or None |
Row operations only. The row the call acted on. |
Status
The shared vocabulary is under Status values.
|
Meaning |
|---|---|
|
The logic is saved in memory and read back exactly. |
|
|
|
|
|
The saved logic is unchanged. |
|
The write could not be verified. Call |
Diagnostic entries
Key |
Type |
Value |
|---|---|---|
|
str |
See the tables on this page. |
|
str |
|
|
str |
|
|
str |
|
|
str |
|
|
Normalization codes: the submitted and the normalized value, and whether each is present. |
|
|
Current-storage codes. See Reading a Property Stack. |
|
|
str |
Write codes: the exception class name, when one was raised. |
Request and write diagnostics
|
Cause |
|---|---|
|
|
|
|
|
PME preferences are unavailable. |
|
No menu has the UID. |
|
Several menus have the UID. |
|
The UID is empty, malformed, or not a string. |
|
The menu is not a Property Stack. |
Other |
The menu collection changed during the call, or the menu’s saved identity is inconsistent. |
|
|
|
The saved logic could not be read before the write. Status
|
|
The saved logic changed just before the write. Status |
|
The write failed and the saved logic is unchanged. Status
|
|
The read-back differs from both the old and the new logic. Status
|
|
Warning. The logic is saved and read back, but the write raised.
Status |
Functions¶
- pme.editing.update_property_stack(pm_uid, *, logic, expected_digest=None, dry_run=False)¶
Replace the complete logic of a Property Stack.
Rows and write entries that
logicomits are removed. UIDs are not allocated or repaired: eachcondition_uidandentry_uidmust be present and unique.- Parameters:
pm_uid (str) – UID of the Property Stack.
logic (dict) – The complete logic, in the form described under Logic. Without
while_true_hud; change the HUD withupdate_property_stack_hud().expected_digest (str or None) –
read_pm()["property_stack"]["digest"]. The update is rejected withstale_property_stack_digestwhen the saved logic has changed.dry_run (bool) – Check the logic and return without writing.
- Returns:
The result described under Common result.
condition_uidis absent.- Return type:
- Raises:
RuntimeError – The call is not on Blender’s main thread, or PME has not finished loading.
Status
committed,validated,unchanged,rejectedorunknown. Logic equal to the readlogicreturnsunchangedwithout writing, on a new Property Stack too. When the readdiagnosticshave a"repair"normalization, the same logic is written instead: the write removes from the saved data what the read view leaves out.Diagnostics
In addition to Common result. All have
scope"input".codeCause, and extra keys
property_stack_logic_must_be_a_mappinglogicis not a dict.property_stack_hud_not_editablelogichaswhile_true_hud.property_stack_input_must_be_json_valueslogicholds a value JSON cannot represent, such as a set or NaN.property_stack_schema_invalidlogicdoes not match Schema v2PropertyStackLogic.pathnames the field andmessagethe rule.schema_v2_logic_condition_uid_repairedA
condition_uidrepeats an earlier one.schema_v2_logic_entry_uid_repairedAn
entry_uidis empty or repeats an earlier one.schema_v2_logic_derived_condition_uid_repaired,schema_v2_logic_derived_condition_uid_unmatchedA
derived_from_condition_uidnames a repaired row, or more entries derive from acondition_uidthan rows have it.schema_v2_logic_write_entry_pm_property_ref_stale_droppedA write to a PME Property has no matching condition row.
schema_v2_logic_predicate_row_malformedAn integer value of a
floatrow cannot become a float.Other
schema_v2_logic_*codesThe Schema v2 decoder rejected or repaired the logic.
pathis"logic".property_stack_normalization_rejectedThe decoder changed a value with a different meaning, such as a repaired UID, a dropped entry or a write status turned
off.path,inputandnormalizedgive the change.property_stack_canonicalizedseverity"info"; does not reject. The decoder changed the form of a value with the same meaning, such as1.0to1.Example
Make the stack TRUE when any condition matches:
import copy stack = pme.editing.read_pm(stack_uid)["property_stack"] logic = copy.deepcopy(stack["logic"]) logic["combine_mode"] = "any" result = pme.editing.update_property_stack( stack_uid, logic=logic, expected_digest=stack["digest"], ) assert result["status"] == "committed", result["diagnostics"]
Notes
To change part of an existing stack, submit the read
logicwith that part changed and the readdigest. Keep every other value, eachcondition_uid,entry_uidandderived_from_condition_uid.Review
scope="current_storage"diagnostics before submitting a readlogic: the view can already omit entries or turn writes off. Input validation does not undo normalization applied while reading.Current-storage diagnostics are carried into the result as warnings. They do not reject the call. A stack whose
logicisNonecan be replaced.A dry run does not evaluate sources, check runtime writability, execute a Setter, or test a widget.
The While True HUD and the saved and registered Property ID are not changed.
The call does not save Preferences to disk, add an Undo step, or run the Getter or Setter.
An exception raised during the write keeps its traceback and gains a note with the last status. Call
read_pm()before retrying.
- pme.editing.add_property_stack_row(pm_uid, *, expected_digest=None, dry_run=False)¶
Append an empty condition row, as the editor does.
The new row is enabled and
incomplete, withsource,op,valueandvalue_typeset toNoneand the label"Condition N", N being its position. No write entry is added until the row has a definition.- Parameters:
- Returns:
The result described under Common result.
condition_uidis the new row’s UID, or the UID it would get after a dry run;Nonewhen rejected before a candidate exists.- Return type:
- Raises:
RuntimeError – The call is not on Blender’s main thread, or PME has not finished loading.
Diagnostics
In addition to Common result:
codeCause
property_stack_current_storage_requires_explicit_repairThe saved logic cannot be decoded, or reading it repaired meaning or identity (a blocking code or a
"repair"normalization).update_property_stack()replaces it.predicate_row_limit_reachedThe stack already has 128 rows.
Example
before = pme.editing.read_pm(stack_uid)["property_stack"] added = pme.editing.add_property_stack_row( stack_uid, expected_digest=before["digest"], ) assert added["status"] == "committed", added["diagnostics"] row_uid = added["condition_uid"]
Notes
A dry run’s
condition_uidis only a candidate until a later call commits.Other rows, write entries, HUD settings and Property IDs are kept.
- pme.editing.update_property_stack_row(pm_uid, condition_uid, fields, *, expected_digest=None, dry_run=False)¶
Change one condition row’s source, operator, value, value type, label or enabled state, as the editor does.
Omitted fields are kept. The row’s
authoring_stateand its derived write entry follow the editor’s rules.- Parameters:
pm_uid (str) – UID of the Property Stack.
condition_uid (str) –
condition_uidof the row. It cannot be changed.fields (dict) – Any of
source,op,value,value_type,labelandenabled, with the types of a condition row.expected_digest (str or None) –
read_pm()["property_stack"]["digest"].dry_run (bool) – Check and return without writing.
- Returns:
The result described under Common result.
condition_uidis the argument.- Return type:
- Raises:
RuntimeError – The call is not on Blender’s main thread, or PME has not finished loading.
Change
Effect
A changed
source,op,valueorvalue_typeThe row gets the definition.
authoring_statebecomescompletewhen the operator accepts the value type and the value fits the operator, otherwiseincomplete. The derived write entry is created or updated; a new one hasentry_uid"write_<condition_uid>".Resulting
op,valueandvalue_typeallNoneSource only. The row stays
incompleteand its derived write entry is removed.labelonlyThe write plan is unchanged.
enabledThe derived write entry follows the editor’s rules. Disabling the row turns it
off.A value equal to the saved one is not a change. When nothing changes, the status is
unchanged.Diagnostics
In addition to Common result. All have
scope"input".codeCause
property_stack_current_storage_requires_explicit_repairAs for
add_property_stack_row().condition_uid_invalidcondition_uidis not a non-empty string.predicate_row_not_foundNo row has
condition_uid.condition_identity_ambiguousSeveral rows have
condition_uid.property_stack_row_fields_must_be_a_mappingfieldsis not a dict.property_stack_row_field_unsupportedfieldshas a key other than the six above.property_stack_schema_invalidand the other codes ofupdate_property_stack()The row with
fieldsapplied does not match Schema v2PmeLogicConditionRow. The check runs on the input, and again on a row that becamecomplete.pathrefers to a one-row logic, such as"logic.predicate_rows[0].value".predicate_row_source_requiredA definition field is given and the row has no source.
predicate_row_operator_unsupportedThe resulting
opisNonewhilevalue_typeorvalueis set.predicate_row_value_type_unsupportedThe resulting
value_typeisNonewhileopis set.predicate_row_operator_type_mismatchopdoes not acceptvalue_type.predicate_row_value_type_mismatchvaluedoes not fitopandvalue_type.write_entry_limit_reachedThe definition would add a write entry beyond 128.
Example
Add a row that is true on frame 1:
before = pme.editing.read_pm(stack_uid)["property_stack"] added = pme.editing.add_property_stack_row(stack_uid, expected_digest=before["digest"]) if added["status"] != "committed": raise RuntimeError(added) row_uid = added["condition_uid"] updated = pme.editing.update_property_stack_row(stack_uid, row_uid, { "source": {"kind": "rna_path", "root": "context", "detected_type": "int", "readonly": False, "segments": [ {"kind": "attr", "name": "scene"}, {"kind": "attr", "name": "frame_current"}]}, "op": "equals", "value": 1, "value_type": "int", "label": "First frame", }, expected_digest=added["after"]["digest"]) print(updated["status"], updated["diagnostics"])
Notes
An empty row accepts
labelandenabled. A definition requires a non-null source.An operator that needs a value, given without one, leaves the row
incompleteand its derived write entrymanual_required.Independent write entries, other rows,
combine_mode,false_policy, HUD settings and Property IDs are kept.The call does not save Preferences to disk, add an Undo step, or run the Getter or Setter. After
unknownor an exception, callread_pm()before retrying.
- pme.editing.remove_property_stack_row(pm_uid, condition_uid, *, expected_digest=None, dry_run=False)¶
Remove one condition row and its derived write entry.
The last row can be removed. Independent write entries are kept.
- Parameters:
- Returns:
The result described under Common result.
condition_uidis the argument.- Return type:
- Raises:
RuntimeError – The call is not on Blender’s main thread, or PME has not finished loading.
Diagnostics
In addition to Common result:
property_stack_current_storage_requires_explicit_repair,condition_uid_invalid,predicate_row_not_foundandcondition_identity_ambiguous, as forupdate_property_stack_row().Example
current = pme.editing.read_pm(stack_uid)["property_stack"] removed = pme.editing.remove_property_stack_row(stack_uid, row_uid, expected_digest=current["digest"])
- pme.editing.update_property_stack_hud(pm_uid, changes, *, expected=None, dry_run=False)¶
Change the While True HUD of a Property Stack, as its Advanced settings do.
Every value is checked before the first write. The HUD is written through the same owner as JSON import and Duplicate, with
enabledset last, and read back.- Parameters:
pm_uid (str) – UID of the Property Stack.
changes (dict) – Field names from While True HUD fields mapped to new values. Fields not given keep their saved values.
expected (dict or None) – Any subset of the saved
while_true_hud. The call is rejected withstale_property_stack_hudwhen a value differs.dry_run (bool) – Check and return the candidate without writing.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
changesorexpectedis not a mapping with string keys, ordry_runis not a bool.ValueError – A field name is unknown, or the UID is missing, invalid, ambiguous or not a Property Stack.
RuntimeError – Called off Blender’s main thread, or before PME has finished loading.
Result
Key
Type
Value
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".dry_runbool
The
dry_runargument.pm_uidstr
The
pm_uidargument.beforedict
while_true_hudat the start of the call.afterdict
while_true_hudat the end of the call. Equal tobeforewhen nothing was written.candidatedict or None
The complete HUD that is saved, or would be saved with
dry_run=True.Nonewhen the request was rejected before it was built.changed_fieldslist[str]
Fields whose saved value differs between
beforeandafter.recoverydict or None
After a failed write:
scope("while_true_hud") andsaved_hud_matches.diagnosticslist[dict]
See Diagnostics below.
Status
statusMeaning
committedThe HUD is saved in memory and read back as requested.
validateddry_run=Trueand the request is acceptable. Nothing was written.unchangedThe candidate equals the saved HUD. Nothing was written.
rejectedNothing was written.
diagnosticsnames the cause.restored_failureA write raised or a value was not kept. The previous HUD was written back and read back equal.
unknownWriting the previous HUD back did not confirm. Read the menu before retrying.
Diagnostics
codeCause, and extra keys
stale_property_stack_hudA value in
expecteddiffers.fields.property_stack_hud_value_invalidA value the HUD cannot keep: a wrong type, an editor the HUD cannot show in, a
displayother thanLABELorFRAME, analignmentthe display does not offer, acolorcomponent outside 0.0 to 1.0,messageoriconlonger than 256 UTF-8 bytes, a name that is not a Blender icon or@customicon, or a Blender icon the HUD cannot draw.field,valueandmessage;choicesforarea_type,displayandalignment;sizeandlimitfor text length.invalid_syntaxis_exprisTrueandmessagedoes not compile.field,message,lineandcolumn(withinmessage).icon_not_foundWarning: no custom icon has the
@name. The HUD is saved and shows no icon until the icon exists.fieldandvalue.property_stack_hud_write_failedThe write raised.
exception_typeandmessage.property_stack_hud_value_not_retainedA field read back differently.
fields,requestedandactual.Example
stack_uid = pme.create_pm(pme.PmCreationSpec("CONDITION", name="X Mirror")).pm_uid result = pme.editing.update_property_stack_hud(stack_uid, { "enabled": True, "message": "X-Axis Mirror", "display": "FRAME", "alignment": "LEFT", "icon": "MOD_MIRROR", "use_color": True, "color": [0.2, 0.6, 1.0], }) assert result["status"] == "committed", result["diagnostics"]
Notes
The editor moves an alignment the new display does not offer to
TOP. This function rejects it instead; givedisplayandalignmenttogether.Changing only
is_exprconvertsmessageas the editor’s Expression toggle does:Mirrorbecomesreturn 'Mirror'. Whenmessageis given too, it is saved as given.Text is limited by UTF-8 bytes, not characters: 256 bytes is 85 Japanese characters.
An empty Property Stack can have an enabled HUD, as in the editor.
logic, itsdigestand the menu version do not change. The logic functions leave the HUD unchanged.The HUD of a duplicate is copied with
enabledoff. Export and import carry the HUD inlogic.while_true_hud.The call does not save Preferences to disk or add an Undo step.
While True HUD fields¶
changes, expected and read_pm()["property_stack"]["while_true_hud"]
use these fields.
Field |
Type |
Value |
|---|---|---|
|
bool |
Show the HUD while the Property Stack is True. Default |
|
str |
Text, or an expression when |
|
bool |
|
|
str |
The editor that shows the HUD, such as |
|
str |
|
|
str |
|
|
str |
A Blender icon name the HUD can draw, an |
|
bool |
Use |
|
list[float] |
Three components from 0.0 to 1.0. Default |
Logic¶
logic follows Schema v2 PropertyStackLogic without while_true_hud.
Key |
Type |
Value |
|---|---|---|
|
int |
|
|
str |
|
|
list[dict] |
Condition rows in order. |
|
dict |
|
Condition row¶
Schema v2 PmeLogicConditionRow. Every key is required.
Key |
Type |
Value |
|---|---|---|
|
str |
Local UID, non-empty and unique in the stack. Write entries refer to it. |
|
bool |
A disabled row does not take part in evaluation. |
|
str |
|
|
str |
Display name, at most 256 characters. |
|
dict or None |
The value read. See Value source. |
|
str or None |
Operator. See Vocabularies. |
|
bool, int, float, str, list[str] or None |
Comparison value. Its shape depends on |
|
str or None |
|
A complete row needs a source whose detected_type equals
value_type, an op that accepts value_type, and a value of the
shape that op requires.
Value source¶
Schema v2 PmeLogicValueSource. Used by condition rows and write entries.
Key |
Type |
Value |
|---|---|---|
|
str |
|
|
str |
For |
|
list[dict] |
|
|
str |
|
|
str or None |
|
|
bool |
|
|
str or None |
Optional. RNA type of a polymorphic owner, such as the Space type under
|
|
int |
Optional, |
Each entry of segments:
|
Other key |
Meaning |
|---|---|---|
|
|
Attribute |
|
|
Item by key, |
|
|
Item by index, |
|
|
Item by the value of an integer PME Property: a |
One element of an array is addressed by ending the path with an index
segment. C.scene.tool_settings.mesh_select_mode[0] is root "context"
with the segments
[{"kind": "attr", "name": "scene"}, {"kind": "attr", "name": "tool_settings"}, {"kind": "attr", "name": "mesh_select_mode"}, {"kind": "index", "index": 0}].
Write plan¶
Schema v2 PropertyStackWritePlan.
Key |
Type |
Value |
|---|---|---|
|
str |
|
|
list[dict] |
Write entries in order. See below. |
Each write entry is a Schema v2 PropertyStackWriteEntry. Every key is
required.
Key |
Type |
Value |
|---|---|---|
|
str |
Local UID, non-empty and unique in the plan. |
|
str |
|
|
str |
|
|
str or None |
|
|
dict or None |
The write target, a value source. |
|
bool, int, float, str or None |
The value written. |
|
str or None |
As for a condition row. |
|
str |
Custom Set code, at most 32768 characters. |
|
str or None |
|
|
list[str] |
Identifiers that the mode applies. Non-empty strings. |
An entry whose source is a condition_ref has kind derived or
manual_write, value_type "bool" and no Enum-set write.
Vocabularies¶
Value |
Meaning |
|---|---|
|
TRUE when every participating row is true. |
|
TRUE when at least one participating row is true. |
Only enabled, complete rows participate. With no participating row, the
result is FALSE.
|
|
|
|---|---|---|
|
|
|
|
|
One value of that type. An |
|
|
One value of that type. |
|
|
A number. |
|
|
A string. |
|
|
A non-empty list of identifiers. |
Comparison meanings are listed under F. Comparison operator and value.
Value |
Meaning |
|---|---|
|
Belongs to a condition row through |
|
A write with an explicit value. |
|
Runs |
Value |
Editor |
Meaning |
|---|---|---|
|
Auto |
The write value is derived from the condition row. |
|
Set |
A write value or method is set explicitly. |
|
Need |
A write value must be specified before the entry can write. |
|
Off |
The entry does not write. |
Value |
FALSE request, for |
|---|---|
|
Only entries that follow the switch write: a |
|
The entries that follow the switch write as under |
Value |
TRUE request |
FALSE request |
|---|---|---|
|
Adds |
Removes them, when the entry writes on FALSE. |
|
Removes |
Adds them, when the entry writes on FALSE. |
|
Replaces the set with |
No write. |
TRUE and FALSE¶
FALSE behaviour is chosen per setting. With false_policy="no_op", a
Boolean auto_resolved entry still writes its inverse on FALSE.
Intended operation |
TRUE |
FALSE / write-entry choice |
|---|---|---|
Surface or Volume preset |
Set both Boolean values |
No writes: fixed Boolean entries use |
3D Step Snap |
Global Snap on, selected transform on, INCREMENT |
Turn only the transform off: its Boolean entry is |
UV Step Snap |
UV Snap on, selected transform on, INCREMENT |
Turn UV Snap off: its Boolean entry is |
For Enum sets, a manual_resolved entry with
enum_set_write_mode="replace" and enum_set_write_values=["INCREMENT"]
replaces the set on TRUE and makes no FALSE write. Test the Getter against
extra set members as well as the desired set. FALSE does not restore a
previous state. The editor’s view of the same rules is under
What TRUE and FALSE write.