Property Definitions (bpy.props)

This module defines properties to extend blenders internal data, the result of these functions is used to assign properties to classes registered with blender and can’t be used directly.

Assigning to Existing Classes

Custom properties can be added to any subclass of an ID, Bone and PoseBone.

These properties can be animated, accessed by the user interface and python like blenders existing properties.

import bpy

# Assign a custom property to an existing type.
bpy.types.Material.custom_float = bpy.props.FloatProperty(name="Test Prob")

# Test the property is there.
bpy.data.materials[0].custom_float = 5.0

Operator Example

A common use of custom properties is for python based Operator classes.

import bpy


class DialogOperator(bpy.types.Operator):
    bl_idname = "object.dialog_operator"
    bl_label = "Property Example"

    my_float = bpy.props.FloatProperty(name="Some Floating Point")
    my_bool = bpy.props.BoolProperty(name="Toggle Option")
    my_string = bpy.props.StringProperty(name="String Value")

    def execute(self, context):
        print("Dialog Runs")
        return {'FINISHED'}

    def invoke(self, context, event):
        wm = context.window_manager
        return wm.invoke_props_dialog(self)


bpy.utils.register_class(DialogOperator)

# test call
bpy.ops.object.dialog_operator('INVOKE_DEFAULT')

PropertyGroup Example

PropertyGroups can be used for collecting custom settings into one value to avoid many indervidual settings mixed in together.

import bpy


class MaterialSettings(bpy.types.PropertyGroup):
    my_int = bpy.props.IntProperty()
    my_float = bpy.props.FloatProperty()
    my_string = bpy.props.StringProperty()

bpy.utils.register_class(MaterialSettings)

bpy.types.Material.my_settings = \
    bpy.props.PointerProperty(type=MaterialSettings)

# test the new settings work
material = bpy.data.materials[0]

material.my_settings.my_int = 5
material.my_settings.my_float = 3.0
material.my_settings.my_string = "Foo"

Collection Example

Custom properties can be added to any subclass of an ID, Bone and PoseBone.

import bpy


# Assign a collection
class SceneSettingItem(bpy.types.PropertyGroup):
    name = bpy.props.StringProperty(name="Test Prop", default="Unknown")
    value = bpy.props.IntProperty(name="Test Prop", default=22)

bpy.utils.register_class(SceneSettingItem)

bpy.types.Scene.my_settings = \
    bpy.props.CollectionProperty(type=SceneSettingItem)

# Assume an armature object selected
print("Adding 3 values!")

my_item = bpy.context.scene.my_settings.add()
my_item.name = "Spam"
my_item.value = 1000

my_item = bpy.context.scene.my_settings.add()
my_item.name = "Eggs"
my_item.value = 30

for my_item in bpy.context.scene.my_settings:
    print(my_item.name, my_item.value)

Update Example

It can be useful to perform an action when a property is changed and can be used to update other properties or synchronize with external data.

All properties define update functions except for CollectionProperty.

import bpy


def update_func(self, context):
    print("my test function", self)

bpy.types.Scene.testprop = bpy.props.FloatProperty(update=update_func)

bpy.context.scene.testprop = 11.0

# >>> my test function <bpy_struct, Scene("Scene")>

Get/Set Example

Get/Set functions can be used for boolean, int, float, string and enum properties. If these callbacks are defined the property will not be stored in the ID properties automatically, instead the get/set functions will be called when the property is read or written from the API.

import bpy


# Simple property reading/writing from ID properties.
# This is what the RNA would do internally.
def get_float(self):
    return self["testprop"]


def set_float(self, value):
    self["testprop"] = value

bpy.types.Scene.test_float = bpy.props.FloatProperty(get=get_float, set=set_float)


# Read-only string property, returns the current date
def get_date(self):
    import datetime
    return str(datetime.datetime.now())

bpy.types.Scene.test_date = bpy.props.StringProperty(get=get_date)


# Boolean array. Set function stores a single boolean value, returned as the second component.
# Array getters must return a list or tuple
# Array size must match the property vector size exactly
def get_array(self):
    return (True, self["somebool"])


def set_array(self, values):
    self["somebool"] = values[0] and values[1]

bpy.types.Scene.test_array = bpy.props.BoolVectorProperty(size=2, get=get_array, set=set_array)


# Enum property.
# Note: the getter/setter callback must use integer identifiers!
test_items = [
    ("RED", "Red", "", 1),
    ("GREEN", "Red", "", 2),
    ("BLUE", "Red", "", 3),
    ("YELLOW", "Red", "", 4),
    ]


def get_enum(self):
    import random
    return random.randint(1, 4)


def set_enum(self, value):
    print("setting value", value)

bpy.types.Scene.test_enum = bpy.props.EnumProperty(items=test_items, get=get_enum, set=set_enum)


# Testing

scene = bpy.context.scene

scene.test_float = 12.34
print(scene.test_float)

scene.test_array = (True, False)
print([x for x in scene.test_array])

#scene.test_date = "blah"   # this would fail, property is read-only
print(scene.test_date)

scene.test_enum = 'BLUE'
print(scene.test_enum)


# >>> 12.34000015258789
# >>> [True, False]
# >>> 2013-01-05 16:33:52.135340
# >>> setting value 3
# >>> GREEN
bpy.props.BoolProperty(name="", description="", default=False, options={'ANIMATABLE'}, subtype='NONE', update=None, get=None, set=None)

Returns a new boolean property definition.

Parameters:
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’].
  • subtype (string) – Enumerator in [‘UNSIGNED’, ‘PERCENTAGE’, ‘FACTOR’, ‘ANGLE’, ‘TIME’, ‘DISTANCE’, ‘NONE’].
  • update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion.
bpy.props.BoolVectorProperty(name="", description="", default=(False, False, False), options={'ANIMATABLE'}, subtype='NONE', size=3, update=None, get=None, set=None)

Returns a new vector boolean property definition.

Parameters:
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • default (sequence) – sequence of booleans the length of size.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’].
  • subtype (string) – Enumerator in [‘COLOR’, ‘TRANSLATION’, ‘DIRECTION’, ‘VELOCITY’, ‘ACCELERATION’, ‘MATRIX’, ‘EULER’, ‘QUATERNION’, ‘AXISANGLE’, ‘XYZ’, ‘COLOR_GAMMA’, ‘LAYER’, ‘NONE’].
  • size (int) – Vector dimensions in [1, and 32].
  • update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion.
bpy.props.CollectionProperty(items, type="", description="", options={'ANIMATABLE'})

Returns a new collection property definition.

Parameters:
  • type (class) – A subclass of bpy.types.PropertyGroup.
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’].
bpy.props.EnumProperty(items, name="", description="", default="", options={'ANIMATABLE'}, update=None, get=None, set=None)

Returns a new enumerator property definition.

Parameters:
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • default (string or set) – The default value for this enum, a string from the identifiers used in items. If the ENUM_FLAG option is used this must be a set of such string identifiers instead.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘ENUM_FLAG’, ‘LIBRARY_EDITABLE’].
  • items (sequence of string tuples or a function) – sequence of enum items formatted: [(identifier, name, description, icon, number), ...] where the identifier is used for python access and other values are used for the interface. The three first elements of the tuples are mandatory. The forth one is either the (unique!) number id of the item or, if followed by a fith element (which must be the numid), an icon string identifier. Note the item is optional. For dynamic values a callback can be passed which returns a list in the same format as the static list. This function must take 2 arguments (self, context) WARNING: Do not use generators here (they will work the first time, but will lead to empty values in some unload/reload scenarii)!
  • update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion.
bpy.props.FloatProperty(name="", description="", default=0.0, min=sys.float_info.min, max=sys.float_info.max, soft_min=sys.float_info.min, soft_max=sys.float_info.max, step=3, precision=2, options={'ANIMATABLE'}, subtype='NONE', unit='NONE', update=None, get=None, set=None)

Returns a new float property definition.

Parameters:
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’].
  • subtype (string) – Enumerator in [‘UNSIGNED’, ‘PERCENTAGE’, ‘FACTOR’, ‘ANGLE’, ‘TIME’, ‘DISTANCE’, ‘NONE’].
  • unit (string) – Enumerator in [‘NONE’, ‘LENGTH’, ‘AREA’, ‘VOLUME’, ‘ROTATION’, ‘TIME’, ‘VELOCITY’, ‘ACCELERATION’].
  • update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion.
  • precision (int) – Number of digits of precision to display.
bpy.props.FloatVectorProperty(name="", description="", default=(0.0, 0.0, 0.0), min=sys.float_info.min, max=sys.float_info.max, soft_min=sys.float_info.min, soft_max=sys.float_info.max, step=3, precision=2, options={'ANIMATABLE'}, subtype='NONE', size=3, update=None, get=None, set=None)

Returns a new vector float property definition.

Parameters:
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • default (sequence) – sequence of floats the length of size.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’].
  • subtype (string) – Enumerator in [‘COLOR’, ‘TRANSLATION’, ‘DIRECTION’, ‘VELOCITY’, ‘ACCELERATION’, ‘MATRIX’, ‘EULER’, ‘QUATERNION’, ‘AXISANGLE’, ‘XYZ’, ‘COLOR_GAMMA’, ‘LAYER’, ‘NONE’].
  • unit (string) – Enumerator in [‘NONE’, ‘LENGTH’, ‘AREA’, ‘VOLUME’, ‘ROTATION’, ‘TIME’, ‘VELOCITY’, ‘ACCELERATION’].
  • size (int) – Vector dimensions in [1, and 32].
  • precision (int) – Number of digits of precision to display.
  • update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion.
bpy.props.IntProperty(name="", description="", default=0, min=-sys.maxint, max=sys.maxint, soft_min=-sys.maxint, soft_max=sys.maxint, step=1, options={'ANIMATABLE'}, subtype='NONE', update=None, get=None, set=None)

Returns a new int property definition.

Parameters:
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’].
  • subtype (string) – Enumerator in [‘UNSIGNED’, ‘PERCENTAGE’, ‘FACTOR’, ‘ANGLE’, ‘TIME’, ‘DISTANCE’, ‘NONE’].
  • update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion.
bpy.props.IntVectorProperty(name="", description="", default=(0, 0, 0), min=-sys.maxint, max=sys.maxint, soft_min=-sys.maxint, soft_max=sys.maxint, options={'ANIMATABLE'}, subtype='NONE', size=3, update=None, get=None, set=None)

Returns a new vector int property definition.

Parameters:
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • default (sequence) – sequence of ints the length of size.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’].
  • subtype (string) – Enumerator in [‘COLOR’, ‘TRANSLATION’, ‘DIRECTION’, ‘VELOCITY’, ‘ACCELERATION’, ‘MATRIX’, ‘EULER’, ‘QUATERNION’, ‘AXISANGLE’, ‘XYZ’, ‘COLOR_GAMMA’, ‘LAYER’, ‘NONE’].
  • size (int) – Vector dimensions in [1, and 32].
  • update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion.
bpy.props.PointerProperty(type="", description="", options={'ANIMATABLE'}, update=None)

Returns a new pointer property definition.

Parameters:
  • type (class) – A subclass of bpy.types.PropertyGroup.
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’].
  • update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion.
bpy.props.RemoveProperty(cls, attr=)

Removes a dynamically defined property.

Parameters:
  • cls (type) – The class containing the property (must be a positional argument).
  • attr (string) – Property name (must be passed as a keyword).

Note

Typically this function doesn’t need to be accessed directly. Instead use del cls.attr

bpy.props.StringProperty(name="", description="", default="", maxlen=0, options={'ANIMATABLE'}, subtype='NONE', update=None, get=None, set=None)

Returns a new string property definition.

Parameters:
  • name (string) – Name used in the user interface.
  • description (string) – Text used for the tooltip and api documentation.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’].
  • subtype (string) – Enumerator in [‘FILE_PATH’, ‘DIR_PATH’, ‘FILE_NAME’, ‘NONE’].
  • update (function) – function to be called when this value is modified, This function must take 2 values (self, context) and return None. Warning there are no safety checks to avoid infinite recursion.