Property¶
A Property (menu type PROPERTY) defines one user property: its type,
arguments, Enum items, callbacks, storage and Property ID. The definition is
read and changed by field name. A Property Stack is described on
Property Stack.
Function |
Purpose |
|---|---|
Returns the definition under |
|
Changes the definition, storage and Property ID. |
See also: Turn a setting into a Property switch.
Reading a Property¶
read_pm(pm_uid)["property"] is the definition under the field names that
update_property() accepts, plus registered_property_id, digest
and diagnostics. Only the fields that apply to the Property’s type and
storage are present; see Property definition. Values are what
the editor shows. Reading does not evaluate the 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': []}
A new Property is a stored Boolean without callbacks.
diagnostics lists problems in the saved definition:
|
Cause, and extra keys |
|---|---|
|
A saved callback has a syntax error. |
|
A saved argument is not a Python literal. |
Where the value lives¶
storage decides who owns the value. registered_property_id is the name
the Property is registered under.
|
Value owner |
Read |
|---|---|---|
|
Addon Preferences. PME holds one value. |
|
An ID type name, such as |
Each data-block of that type holds its own value, as an attribute named
|
|
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})"
registered_property_id is empty while the Property is disabled. Property ID
rules are listed under Property ID and migration.
Property definition¶
The fields of read_pm()["property"]. All except the last three are accepted
by update_property(). Default is the value the editor shows when the
field was never set. The arguments default, min, max, step,
precision, subtype and unit are passed to Blender’s bpy.props
function under the same names; None in update_property() returns
an argument to its default.
Field |
Type |
Applies to |
Default |
Meaning |
|---|---|---|---|---|
|
str |
all |
|
|
|
int |
BOOL, INT, FLOAT |
|
Property Size. 1 is a single value; 2 to 32 is a vector with that many components. |
|
bool, int, float, str or list |
all |
BOOL |
Default Value. A vector default is a list of exactly |
|
int or float |
INT, FLOAT |
|
Min Value. A 32-bit integer for INT, a finite number for FLOAT. |
|
int or float |
INT, FLOAT |
|
Max Value. Same rules as |
|
int or float |
INT, FLOAT |
|
Step. Same rules as |
|
int |
FLOAT |
|
Precision, 0 to 6. |
|
str |
INT, FLOAT, STRING |
|
Subtype. See Subtype values. |
|
str |
FLOAT |
|
Unit. See Unit values. |
|
bool |
ENUM |
|
Multi-Select. The value is a set of identifiers. |
|
bool |
all |
|
Expand. |
|
bool |
BOOL, INT, FLOAT, ENUM |
|
Horizontal Layout. |
|
bool |
|
|
Restore Default Value. PME initialization discards the saved value and
starts from |
|
list[dict] |
ENUM |
|
Enum items in order. See Enum items. |
|
str or None |
all |
|
Getter text. Its |
|
str or None |
all |
|
Setter text. Requires a Getter. |
|
str or None |
all |
|
On Update text. |
|
str or None |
all |
|
On Init text. |
|
str or None |
all |
|
|
|
str |
all |
Generated from the menu name |
Saved Property ID. |
|
bool |
all |
|
Lock. When |
|
str |
read only |
Name the Property is registered under. Empty while the Property is disabled or not registered. |
|
|
str |
read only |
Hex digest of the saved definition. Pass it as |
|
|
list[dict] |
read only |
Problems in the saved definition. See Reading a Property. |
Callback variables are listed under Getter / Setter / On Update / On Init.
Enum items¶
Each entry of items:
Key |
Type |
Value |
|---|---|---|
|
str |
UID of an existing item. On input, an existing UID keeps that item’s
identity; omit it, or pass |
|
str |
Required. The value used in scripts. Non-empty, without spaces or
|
|
str |
Display label. Without |
|
str |
Blender icon name. Omitted: |
items replaces the Enum items in the given order. Enum values follow item
order, as in the editor. An identifier cannot be GET, SET, UPDATE,
INIT, CLASS, default, min, max, step, precision,
subtype or unit. A Multi-Select Enum holds at most 31 items.
Subtype values¶
Property |
Accepted |
|---|---|
INT or FLOAT, |
|
INT or FLOAT, |
|
STRING |
|
Unit values¶
unit accepts the identifiers of Blender’s FloatProperty.unit. Blender
5.2 has NONE, LENGTH, AREA, VOLUME, ROTATION, TIME,
TIME_ABSOLUTE, VELOCITY, ACCELERATION, MASS, CAMERA,
POWER, TEMPERATURE, WAVELENGTH, COLOR_TEMPERATURE and
FREQUENCY. The list is read from the running Blender.
Reset rules¶
The editor’s own rules apply, in this order. Values supplied in the same call are applied after these resets.
Change |
Effect |
|---|---|
|
|
|
A |
|
|
|
|
Functions¶
- pme.editing.update_property(pm_uid, changes, *, expected_digest=None, dry_run=False)¶
Change a Property’s definition, storage and Property ID as its editor does.
All changes are checked before the first write. If any is rejected, nothing is written. The changes are then saved in three groups, in a fixed order.
- Parameters:
pm_uid (str) – UID of the Property.
changes (dict) – Field name mapped to its new value. Field names are those of Property definition, except the read-only ones. Partial: fields that are not named keep their values, apart from the Reset rules.
Nonereturns an argument to the editor default and removes a callback.expected_digest (str or None) –
read_pm()["property"]["digest"]. The update is rejected withstale_propertywhen the saved Property has changed.dry_run (bool) – Check the changes and return without writing.
- Returns:
The result described below.
- Return type:
- Raises:
TypeError –
changesis not a mapping;multiselect,expand,horizontal,restore_defaultorproperty_id_lockedis not a bool; a callback is not a string orNone;property_idis not a string;storageis notNoneor a non-empty string;itemsis not a sequence of mappings, an item’sidentifieris not a string, or itsuid,nameoriconis not a string orNone;expected_digestis not a string orNone;dry_runis not a bool.ValueError – A field name is unknown;
typeis not one of the five types;sizeis not an integer from 1 to 32; an item has a key other thanuid,identifier,nameandicon; the UID is missing, invalid or ambiguous; the menu is not a Property.RuntimeError – The call is not on Blender’s main thread, PME has not finished loading, or PME preferences are unavailable.
Groups
groupRuns when
Saved through
storagestoragediffers from the saved value.The editor’s storage setting. It can choose a new Property ID for the destination storage.
property_idThe saved Property ID or lock differs from the requested one, including an ID the storage group chose.
The editor’s Edit Property ID.
definitionAny other field differs from the saved value.
The editor’s fields, then one registration with Blender.
Each group leaves a complete Property.
groupslists the groups that ran andpendingthe groups that did not.Result
Key
Type
Value
statusstr
See Status below.
committedbool
Trueonly whenstatusis"committed".dry_runbool
The
dry_runargument.pm_uidstr
The
pm_uidargument.beforedict
read_pm()["property"]before the call.afterdict
read_pm()["property"]after the call. Equal tobeforeunless something was written.candidatedict or None
The definition to save, with
storage,property_idandproperty_id_locked.Nonewhen the changes are rejected.changed_fieldslist[str]
Field names whose value differs between
beforeandafter. Empty after a dry run.groupslist[dict]
One entry per group that ran:
groupandstatus("committed","rejected","restored_failure"or"unknown"). Empty after a dry run.pendinglist[str]
Groups that need to run and did not. After a dry run, the groups that would run.
registrationdict or None
Set when the
definitiongroup ran. See Registration below. Thestorageandproperty_idgroups register the Property too; after any group,after["storage"]andafter["registered_property_id"]give where and under which name it is registered.recoverydict or None
Set after a failed group:
scope(the group) andsaved_definition_matches.diagnosticslist[dict]
One entry per problem:
code,field(orfields) andmessage, plus the details listed under Diagnostics. Warnings also haveseverity: "warning".Registration
Key
Type
Value
statusstr
"committed","failed", or"not_applicable"while the Property is disabled.registered_property_idstr
Name the Property is registered under. Empty when not registered.
reason_codestr
Empty on success.
property_disabledfor a disabled Property. Otherwise the code of the failed step, such ashost_registration_failed.failed_stagestr
Empty on success. Otherwise the failed step:
validate,claim,resolve_owner,prepare_metadata,inspect_native,migrate,migrate_native,prepare_cleanup,register_new,commit_ownership,publishorcommit_metadata.blocked_ownerstr
The data-block that blocked moving a stored value, such as
Object 'Cube'. Empty otherwise.Status
The shared vocabulary is under Status values.
statusMeaning
committedEvery group that needed to run is saved.
validateddry_run=Trueand the changes are acceptable. Nothing was written.unchangedThe changes match the saved Property. Nothing was written. Also returned by a dry run.
rejectedThe saved Property is unchanged.
diagnosticsnames the cause: a check, or the failure of the first group that ran.partialA group failed after an earlier group committed. The earlier group stays saved;
pendinglists the groups that did not run.restored_failureBlender refused to register the saved definition, and the saved definition was restored.
unknownA failed group left the saved Property changed, or the restore could not be confirmed.
recovery["scope"]names the group. Callread_pm()before retrying.Diagnostics
Rejects: checked before the first write; the status is
rejected. Warning: the status is unaffected. Group: a group failed during the write.codeEffect
Cause, and extra keys
stale_propertyRejects
expected_digestdiffers from the saved digest.fieldis"digest".field_not_applicableRejects
The field does not apply to the resulting type, or
restore_defaultis given for ID storage.default_type_mismatchRejects
defaulthas the wrong type or, for a vector, the wrong length.default_not_in_itemsRejects
default, given or kept, names an identifier the items do not have.missinglists them.argument_type_mismatchRejects
min,maxorstepis not an integer (INT) or a finite number (FLOAT), orprecisionis not an integer.argument_out_of_rangeRejects
precisionis an integer outside 0 to 6; an INTdefault,min,maxorstepis an integer outside the 32-bit range (-2147483648 to 2147483647); or a FLOATdefault,min,maxorstepis a finite number outside the 32-bit float range (about ±3.4028235e38), which Blender would register as infinity.fieldnames the field.argument_not_a_choiceRejects
subtypeorunitis not accepted for the type and size.choiceslists the accepted values.min_greater_than_maxRejects
The resulting
minis greater thanmax.minandmaxgive both values. Not checked when the other bound is unreadable.multiselect_item_limitRejects
A Multi-Select Enum would have more than 31 items.
limitandcountgive the numbers.item_identifier_invalidRejects
An identifier is empty or contains a space or
|.indexnames the item.item_identifier_duplicateRejects
An identifier repeats an earlier one.
indexnames the item.item_identifier_reservedRejects
An identifier is a reserved entry name, listed under Enum items.
indexnames the item.item_name_invalidRejects
A name contains
|.indexnames the item.item_uid_duplicateRejects
Two items give the same
uid.item_uid_unknownRejects
A
uidis not an item of this Property.uidslists them.set_requires_getRejects
The result would have a Setter without a Getter.
argument_unreadable_would_be_replacedRejects
A saved argument that is not a literal would be replaced by a value the call did not name.
textholds the saved text. Passing the argument explicitly replaces it.storage_type_unknownRejects
storageis not a Blender ID type name.empty,too_long,invalid_identifier,non_ascii,python_keyword,reserved_access_nameRejects
The Property ID is empty, longer than 63 bytes, not an ASCII letter followed by letters, digits or
_, non-ASCII, a Python keyword, or one ofkeys,values,items,get. Checked whenproperty_idorstoragechanges.owner_reservedRejects
The destination storage already has an attribute of that name, such as a Blender property or a property another Property registered.
manual_prop_id_collisionRejects
Another Property in the same storage saves that Property ID.
reservedRejects
The Property ID is reserved for another reason.
callback_compile_errorWarning
A given callback has a syntax error. It is saved, as in the editor.
argument_unreadableWarning
A saved argument that is not a literal is kept.
textholds the saved text.property_readback_differsWarning
After a commit, the saved Property differs from
candidate.fieldslists the names.storage_registration_failedGroup
The storage group was not accepted.
messagejoins the editor’s reports.Code of the Property ID step
Group
The
property_idgroup was not accepted.codeis a Property ID code above,runtime_prop_id_register_failed, or the registration’sreason_code.effect_codeslists the steps run.definition_registration_failedGroup
Blender refused to register the saved definition.
registrationholds the details.Example
Turn a new Property into a Float from 0 to 1 with a length unit:
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"]
Notes
When
storagechanges, the Property ID that is requested or kept is checked against the storage it moves to.No callback is executed by validation, saving or reading. On Init does not run.
Stored values follow the normal registration rules: changing
typeorsizediscards the stored value, as in the editor. Stored values are not restored after a failure.A committed group, or a group that ends
unknown, incrementsread_pm()["version"].The selected menu and an open draft are not changed.
An exception raised while the definition group is saved is re-raised after the saved definition is restored. Its note states whether the restore was confirmed. Call
read_pm()before retrying.The call does not save Preferences to disk, add an Undo step, or display the Property.