Property Definitions (bpy.props)

This module defines properties to extend Blender’s internal data. The result of these functions is used to assign properties to classes registered with Blender and can’t be used directly.

Note

All parameters to these functions must be passed as keywords.

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 Blender’s 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 individual 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 2 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", "Green", "", 2),
    ("BLUE", "Blue", "", 3),
    ("YELLOW", "Yellow", "", 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’, ‘PROPORTIONAL’,’TEXTEDIT_UPDATE’].
  • subtype (string) – Enumerator in [‘PIXEL’, ‘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.
  • get (function) – Function to be called when this value is ‘read’, This function must take 1 value (self) and return the value of the property.
  • set (function) – Function to be called when this value is ‘written’, This function must take 2 values (self, value) and return None.
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’, ‘PROPORTIONAL’,’TEXTEDIT_UPDATE’].
  • subtype (string) – Enumerator in [‘COLOR’, ‘TRANSLATION’, ‘DIRECTION’, ‘VELOCITY’, ‘ACCELERATION’, ‘MATRIX’, ‘EULER’, ‘QUATERNION’, ‘AXISANGLE’, ‘XYZ’, ‘COLOR_GAMMA’, ‘LAYER’, ‘NONE’].
  • size (int) – Vector dimensions in [1, 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.
  • get (function) – Function to be called when this value is ‘read’, This function must take 1 value (self) and return the value of the property.
  • set (function) – Function to be called when this value is ‘written’, This function must take 2 values (self, value) and return None.
bpy.props.CollectionProperty(type=None, name="", 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’, ‘PROPORTIONAL’,’TEXTEDIT_UPDATE’].
bpy.props.EnumProperty(items, name="", description="", default=None, options={'ANIMATABLE'}, update=None, get=None, set=None)

Returns a new enumerator property definition.

Parameters:
  • items (sequence of string tuples or a function) –

    sequence of enum items formatted: [(identifier, name, description, icon, number), ...].

    The first three elements of the tuples are mandatory.

    identifier:The identifier is used for Python access.
    name:Name for the interace.
    description:Used for documentation and tooltips.
    icon:An icon string identifier or integer icon value (e.g. returned by bpy.types.UILayout.icon)
    number:Unique value used as the identifier for this item (stored in file data). Use when the identifier may need to change.

    When an item only contains 4 items they define (identifier, name, description, number).

    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), context may be None.

    Warning

    There is a known bug with using a callback, Python must keep a reference to the strings returned or Blender will misbehave or even crash.

  • 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. WARNING: It shall not be specified (or specified to its default None value) for dynamic enums (i.e. if a callback function is given as items parameter).
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘ENUM_FLAG’, ‘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.
  • get (function) – Function to be called when this value is ‘read’, This function must take 1 value (self) and return the value of the property.
  • set (function) – Function to be called when this value is ‘written’, This function must take 2 values (self, value) and return None.
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.
  • min (float) – Hard minimum, trying to assign a value below will silently assign this minimum instead.
  • max (float) – Hard maximum, trying to assign a value above will silently assign this maximum instead.
  • soft_min (float) – Soft minimum (>= min), user won’t be able to drag the widget below this value in the UI.
  • soft_max (float) – Soft maximum (<= max), user won’t be able to drag the widget above this value in the UI.
  • step (int) – Step of increment/decrement in UI, in [1, 100], defaults to 3 (WARNING: actual value is /100).
  • precision (int) – Maximum number of decimal digits to display, in [0, 6].
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’, ‘PROPORTIONAL’,’TEXTEDIT_UPDATE’].
  • subtype (string) – Enumerator in [‘PIXEL’, ‘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.
  • get (function) – Function to be called when this value is ‘read’, This function must take 1 value (self) and return the value of the property.
  • set (function) – Function to be called when this value is ‘written’, This function must take 2 values (self, value) and return None.
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', unit='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.
  • min (float) – Hard minimum, trying to assign a value below will silently assign this minimum instead.
  • max (float) – Hard maximum, trying to assign a value above will silently assign this maximum instead.
  • soft_min (float) – Soft minimum (>= min), user won’t be able to drag the widget below this value in the UI.
  • soft_max (float) – Soft maximum (<= max), user won’t be able to drag the widget above this value in the UI.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’, ‘PROPORTIONAL’,’TEXTEDIT_UPDATE’].
  • step (int) – Step of increment/decrement in UI, in [1, 100], defaults to 3 (WARNING: actual value is /100).
  • precision (int) – Maximum number of decimal digits to display, in [0, 6].
  • 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, 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.
  • get (function) – Function to be called when this value is ‘read’, This function must take 1 value (self) and return the value of the property.
  • set (function) – Function to be called when this value is ‘written’, This function must take 2 values (self, value) and return None.
bpy.props.IntProperty(name="", description="", default=0, min=-2**31, max=2**31-1, soft_min=-2**31, soft_max=2**31-1, 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.
  • min (int) – Hard minimum, trying to assign a value below will silently assign this minimum instead.
  • max (int) – Hard maximum, trying to assign a value above will silently assign this maximum instead.
  • soft_max (int) – Soft maximum (<= max), user won’t be able to drag the widget above this value in the UI.
  • soft_min (int) – Soft minimum (>= min), user won’t be able to drag the widget below this value in the UI.
  • step (int) – Step of increment/decrement in UI, in [1, 100], defaults to 1 (WARNING: unused currently!).
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’, ‘PROPORTIONAL’,’TEXTEDIT_UPDATE’].
  • subtype (string) – Enumerator in [‘PIXEL’, ‘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.
  • get (function) – Function to be called when this value is ‘read’, This function must take 1 value (self) and return the value of the property.
  • set (function) – Function to be called when this value is ‘written’, This function must take 2 values (self, value) and return None.
bpy.props.IntVectorProperty(name="", description="", default=(0, 0, 0), min=-2**31, max=2**31-1, soft_min=-2**31, soft_max=2**31-1, step=1, 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.
  • min (int) – Hard minimum, trying to assign a value below will silently assign this minimum instead.
  • max (int) – Hard maximum, trying to assign a value above will silently assign this maximum instead.
  • soft_min (int) – Soft minimum (>= min), user won’t be able to drag the widget below this value in the UI.
  • soft_max (int) – Soft maximum (<= max), user won’t be able to drag the widget above this value in the UI.
  • step (int) – Step of increment/decrement in UI, in [1, 100], defaults to 1 (WARNING: unused currently!).
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’, ‘PROPORTIONAL’,’TEXTEDIT_UPDATE’].
  • subtype (string) – Enumerator in [‘COLOR’, ‘TRANSLATION’, ‘DIRECTION’, ‘VELOCITY’, ‘ACCELERATION’, ‘MATRIX’, ‘EULER’, ‘QUATERNION’, ‘AXISANGLE’, ‘XYZ’, ‘COLOR_GAMMA’, ‘LAYER’, ‘NONE’].
  • size (int) – Vector dimensions in [1, 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.
  • get (function) – Function to be called when this value is ‘read’, This function must take 1 value (self) and return the value of the property.
  • set (function) – Function to be called when this value is ‘written’, This function must take 2 values (self, value) and return None.
bpy.props.PointerProperty(type=None, name="", 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’, ‘PROPORTIONAL’,’TEXTEDIT_UPDATE’].
  • 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.
  • default (string) – initializer string.
  • maxlen (int) – maximum length of the string.
  • options (set) – Enumerator in [‘HIDDEN’, ‘SKIP_SAVE’, ‘ANIMATABLE’, ‘LIBRARY_EDITABLE’, ‘PROPORTIONAL’,’TEXTEDIT_UPDATE’].
  • subtype (string) – Enumerator in [‘FILE_PATH’, ‘DIR_PATH’, ‘FILE_NAME’, ‘BYTE_STRING’, ‘PASSWORD’, ‘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.
  • get (function) – Function to be called when this value is ‘read’, This function must take 1 value (self) and return the value of the property.
  • set (function) – Function to be called when this value is ‘written’, This function must take 2 values (self, value) and return None.