From BlenderWiki

Jump to: navigation, search

API Changes

This page shall give addon developers advice on how to update their scripts to make them work again after major changes to the Blender Python API.

If your specific problem isn't covered here, feel free to inform the community about it in the forum.

You may also have a look at the auto-generated API change log for minor things that changed - but keep in mind that it may be incomplete!


Template List (r53355)

UI's template_list() was refactored to be much more flexible and give real control over items' drawing. A new RNA type was introduced for this, bpy.types.UIList, making lists independent from Panels. This UIList has a draw_item() callback which allows to customize items' drawing from python, that all addons can now use.

If your addon uses the old API for a simple list, it's easy to update:

template_list(bpy.context.scene, "your_collection", bpy.context.scene, "your_collection_idx")
template_list('UI_UL_list', 'your_collection_id', bpy.context.scene, "your_collection", bpy.context.scene, "your_collection_idx")

For simple lists, it isn't necessary to derive a custom class from UIList type. Instead, simply put 'UI_UL_list' (for a default drawing method for the list items) as first argument and a list ID string as second. Chose something unique for the ID, preferably a brief description of what your list contains. If another script used the default 'UI_UL_list' and the same ID (maybe a blank string), Blender would not be able to distinguish between both lists!

For in-depth explanation, e.g. how to create custom draw_item callbacks, see the API docs: UIList, UILayout.template_list.

Region Draw Callbacks (r53207)

Region drawing callbacks were changed to work much closer to how blender manages them internally. The change was necessary to fix bug T30740.

To update old code, you need to replace the Region.callback_add() and Region.callback_remove() calls. The new way of adding/removing a draw callback is to call a Space type's draw_handler_add() and draw_handler_remove() functions. A common Space type is the 3D View, bpy.types.SpaceView3D. For a list of Space types, see subclasses in API docs - bpy.types.Space.

The deprecated callback_add() expected 3 arguments, whereas draw_handler_add() requires 4. You now need to specify the Space's region type (string) as 3rd parameter. It is also required on callback removal:

self._handle = context.region.callback_add(draw_callback_px, (self, context), 'POST_PIXEL')
CLASSNAME._handle = bpy.types.SpaceView3D.draw_handler_add(draw_callback_px, (self, context), 'WINDOW', 'POST_PIXEL')
bpy.types.SpaceView3D.draw_handler_remove(CLASSNAME._handle, 'WINDOW')
# To store the handle, the class should be used rather than the class instance (you may use self.__class__),
# so we can access the variable from outside, e.g. to remove the drawback on unregister()

Below you find a comparison of the old and the new API usage:

class ScreencastKeysStatus(bpy.types.Operator):
    bl_idname = "view3d.screencast_keys"
    bl_label = "Screencast Keys"
    bl_description = "Display keys pressed in the 3D View"
    _handle = None
    _timer = None
    def modal(self, context, event):
        # ...
        if not context.window_manager.screencast_keys_keys:
            # stop script
            return {'CANCELLED'}
        return {'PASS_THROUGH'}
    def cancel(self, context):
        if context.window_manager.screencast_keys_keys:
            context.window_manager.screencast_keys_keys = False
        return {'CANCELLED'}
    def invoke(self, context, event):
        # ...
                self._handle = context.region.callback_add(draw_callback_px,
                    (self, context), 'POST_PIXEL')
                self._timer = context.window_manager.event_timer_add(0.075,
# ...
def unregister():
# ...
class ScreencastKeysStatus(bpy.types.Operator):
    bl_idname = "view3d.screencast_keys"
    bl_label = "Screencast Keys"
    bl_description = "Display keys pressed in the 3D View"
    _handle = None
    _timer = None
    def handle_add(self, context):
        ScreencastKeysStatus._handle = bpy.types.SpaceView3D.draw_handler_add(draw_callback_px, (self, context), 'WINDOW', 'POST_PIXEL')
        ScreencastKeysStatus._timer = context.window_manager.event_timer_add(0.075, context.window)
    def handle_remove(context):
        if ScreencastKeysStatus._handle is not None:
            bpy.types.SpaceView3D.draw_handler_remove(ScreencastKeysStatus._handle, 'WINDOW')
        ScreencastKeysStatus._handle = None
        ScreencastKeysStatus._timer = None
    def modal(self, context, event):
        # ...
        if not context.window_manager.screencast_keys_keys:
            # stop script
            return {'CANCELLED'}
        return {'PASS_THROUGH'}
    def cancel(self, context):
        if context.window_manager.screencast_keys_keys:
            context.window_manager.screencast_keys_keys = False
        return {'CANCELLED'}
    def invoke(self, context, event):
        # ...
                ScreencastKeysStatus.handle_add(self, context)
# ...
def unregister():
# ...

Note: If you don't use an event timer, remove the argument "context" from handle_remove(), in staticmethod definition and in the call inside unregister(). Or omit the static methods and call the draw_handler_* functions directly, as seen in the Operator Modal Draw template.

Restricted Context

To avoid errors on accessing blend-file data while addons register() / unregister(), Blender now restricts access to bpy.context and

This is done because there is no assurance that the data loaded when the addon is registered will be active or even exist when the user accesses operators the addon defines.

If you see an exception like this, then the addon needs to be updated to access the context during execution rather then on registration:

AttributeError: '_RestrictContext' object has no attribute 'scene'

Bad code example:

def register():
    bpy.types.Scene.my_prop = bpy.props.StringProperty()
    bpy.context.scene.my_prop = "foobar" # can't access bpy.context here!

Such initialization needs to be done when an operator runs the first time. It's also possible to provide a special init operator, shown as button in a panel.

Init operator example:

import bpy
class HelloWorldPanel(bpy.types.Panel):
    """Creates a Panel in the Object properties window"""
    bl_label = "Hello World Panel"
    bl_idname = "OBJECT_PT_hello"
    bl_space_type = 'PROPERTIES'
    bl_region_type = 'WINDOW'
    bl_context = "scene"
    def draw(self, context):
        layout = self.layout
        # If Scene.my_prop wasn't created in register() or removed, draw a note
        if not hasattr(context.scene, "my_prop"):
            layout.label("Scene does not have a property 'my_prop'")
        # If it has no longer the default property value, draw a label with icon
        elif context.scene.my_prop != 'default value':
            layout.label("my_prop = " + context.scene.my_prop, icon="FILE_TICK")
        # It has the default property value, draw a label with no icon
            layout.label("my_prop = " + context.scene.my_prop)
        layout.operator(InitMyPropOperator.bl_idname, text=InitMyPropOperator.bl_label)
class InitMyPropOperator(bpy.types.Operator):
    bl_idname = "scene.init_my_prop"
    bl_label = "Init my_prop"
    def poll(cls, context):
        return context.active_object is not None
    def execute(self, context):
        if context.scene.my_prop != "initialized":
            context.scene.my_prop = "initialized"
            self.__class__.bl_label = "Change my_prop"
            context.scene.my_prop = "foobar"
            self.__class__.bl_label = self.bl_label
        return {'FINISHED'}
def register():
    bpy.types.Scene.my_prop = bpy.props.StringProperty(default="default value")
def unregister():
    del bpy.types.Scene.my_prop
if __name__ == "__main__":

Also see: mailing list thread


Node Identifiers

The type enum property of nodes is no longer the primary way of identifying node types. Instead nodes now have a bl_idname property (like other registerable types such as operators, menus, etc.). Also see: Python Nodes - API Changes

The bl_idname must be passed to the method in particular for identifying the node type. The old type property still exists, but should be avoided as much as possible. Scripters are encouraged to convert their use of explicit identifiers to the new system. The full list of which enum type maps to which bl_idname can be found below (most names are pretty obvious though). A quick way of getting the correct identifier is typing
in the Blender console.
Shader Nodes
type bl_idname
ADD_SHADER ShaderNodeAddShader
AMBIENT_OCCLUSION ShaderNodeAmbientOcclusion
ATTRIBUTE ShaderNodeAttribute
BACKGROUND ShaderNodeBackground
BRIGHTCONTRAST ShaderNodeBrightContrast
BSDF_ANISOTROPIC ShaderNodeBsdfAnisotropic
BSDF_DIFFUSE ShaderNodeBsdfDiffuse
BSDF_GLASS ShaderNodeBsdfGlass
BSDF_GLOSSY ShaderNodeBsdfGlossy
BSDF_REFRACTION ShaderNodeBsdfRefraction
BSDF_TRANSLUCENT ShaderNodeBsdfTranslucent
BSDF_TRANSPARENT ShaderNodeBsdfTransparent
BSDF_VELVET ShaderNodeBsdfVelvet
BUMP ShaderNodeBump
CAMERA ShaderNodeCameraData
COMBRGB ShaderNodeCombineRGB
CURVE_RGB ShaderNodeRGBCurve
CURVE_VEC ShaderNodeVectorCurve
EMISSION ShaderNodeEmission
FRESNEL ShaderNodeFresnel
GAMMA ShaderNodeGamma
GEOMETRY ShaderNodeGeometry
GROUP ShaderNodeGroup
HAIR_INFO ShaderNodeHairInfo
HOLDOUT ShaderNodeHoldout
HUE_SAT ShaderNodeHueSaturation
INVERT ShaderNodeInvert
LAYER_WEIGHT ShaderNodeLayerWeight
LIGHT_FALLOFF ShaderNodeLightFalloff
LIGHT_PATH ShaderNodeLightPath
MAPPING ShaderNodeMapping
MATERIAL ShaderNodeMaterial
MATERIAL_EXT ShaderNodeExtendedMaterial
MATH ShaderNodeMath
MIX_RGB ShaderNodeMixRGB
MIX_SHADER ShaderNodeMixShader
NEW_GEOMETRY ShaderNodeNewGeometry
NORMAL ShaderNodeNormal
NORMAL_MAP ShaderNodeNormalMap
OBJECT_INFO ShaderNodeObjectInfo
OUTPUT ShaderNodeOutput
OUTPUT_LAMP ShaderNodeOutputLamp
OUTPUT_MATERIAL ShaderNodeOutputMaterial
OUTPUT_WORLD ShaderNodeOutputWorld
PARTICLE_INFO ShaderNodeParticleInfo
RGB ShaderNodeRGB
SCRIPT ShaderNodeScript
SEPRGB ShaderNodeSeparateRGB
SQUEEZE ShaderNodeSqueeze
SUBSURFACE_SCATTERING ShaderNodeSubsurfaceScattering
TANGENT ShaderNodeTangent
TEXTURE ShaderNodeTexture
TEX_BRICK ShaderNodeTexBrick
TEX_CHECKER ShaderNodeTexChecker
TEX_COORD ShaderNodeTexCoord
TEX_ENVIRONMENT ShaderNodeTexEnvironment
TEX_GRADIENT ShaderNodeTexGradient
TEX_IMAGE ShaderNodeTexImage
TEX_MAGIC ShaderNodeTexMagic
TEX_MUSGRAVE ShaderNodeTexMusgrave
TEX_NOISE ShaderNodeTexNoise
TEX_SKY ShaderNodeTexSky
TEX_VORONOI ShaderNodeTexVoronoi
TEX_WAVE ShaderNodeTexWave
VALUE ShaderNodeValue
VECT_MATH ShaderNodeVectorMath

Compositor Nodes
type bl_idname
ALPHAOVER CompositorNodeAlphaOver
BILATERALBLUR CompositorNodeBilateralblur
BLUR CompositorNodeBlur
BOKEHBLUR CompositorNodeBokehBlur
BOKEHIMAGE CompositorNodeBokehImage
BOXMASK CompositorNodeBoxMask
BRIGHTCONTRAST CompositorNodeBrightContrast
CHANNEL_MATTE CompositorNodeChannelMatte
CHROMA_MATTE CompositorNodeChromaMatte
COLORBALANCE CompositorNodeColorBalance
COLORCORRECTION CompositorNodeColorCorrection
COLOR_MATTE CompositorNodeColorMatte
COLOR_SPILL CompositorNodeColorSpill
COMBHSVA CompositorNodeCombHSVA
COMBRGBA CompositorNodeCombRGBA
COMBYCCA CompositorNodeCombYCCA
COMBYUVA CompositorNodeCombYUVA
COMPOSITE CompositorNodeComposite
CROP CompositorNodeCrop
CURVE_RGB CompositorNodeCurveRGB
CURVE_VEC CompositorNodeCurveVec
DBLUR CompositorNodeDBlur
DEFOCUS CompositorNodeDefocus
DESPECKLE CompositorNodeDespeckle
DIFF_MATTE CompositorNodeDiffMatte
DILATEERODE CompositorNodeDilateErode
DISPLACE CompositorNodeDisplace
DISTANCE_MATTE CompositorNodeDistanceMatte
DOUBLEEDGEMASK CompositorNodeDoubleEdgeMask
ELLIPSEMASK CompositorNodeEllipseMask
FILTER CompositorNodeFilter
FLIP CompositorNodeFlip
GAMMA CompositorNodeGamma
GLARE CompositorNodeGlare
GROUP CompositorNodeGroup
HUECORRECT CompositorNodeHueCorrect
HUE_SAT CompositorNodeHueSat
ID_MASK CompositorNodeIDMask
IMAGE CompositorNodeImage
INPAINT CompositorNodeInpaint
INVERT CompositorNodeInvert
KEYING CompositorNodeKeying
KEYINGSCREEN CompositorNodeKeyingScreen
LENSDIST CompositorNodeLensdist
LEVELS CompositorNodeLevels
LUMA_MATTE CompositorNodeLumaMatte
MAP_RANGE CompositorNodeMapRange
MAP_UV CompositorNodeMapUV
MAP_VALUE CompositorNodeMapValue
MASK CompositorNodeMask
MATH CompositorNodeMath
MIX_RGB CompositorNodeMixRGB
MOVIECLIP CompositorNodeMovieClip
MOVIEDISTORTION CompositorNodeMovieDistortion
NORMAL CompositorNodeNormal
NORMALIZE CompositorNodeNormalize
OUTPUT_FILE CompositorNodeOutputFile
PIXELATE CompositorNodePixelate
PREMULKEY CompositorNodePremulKey
RGB CompositorNodeRGB
ROTATE CompositorNodeRotate
SCALE CompositorNodeScale
SEPHSVA CompositorNodeSepHSVA
SEPRGBA CompositorNodeSepRGBA
SEPYCCA CompositorNodeSepYCCA
SEPYUVA CompositorNodeSepYUVA
SETALPHA CompositorNodeSetAlpha
SPLITVIEWER CompositorNodeSplitViewer
STABILIZE2D CompositorNodeStabilize
SWITCH CompositorNodeSwitch
TEXTURE CompositorNodeTexture
TIME CompositorNodeTime
TONEMAP CompositorNodeTonemap
TRACKPOS CompositorNodeTrackPos
TRANSFORM CompositorNodeTransform
TRANSLATE CompositorNodeTranslate
VALTORGB CompositorNodeValToRGB
VALUE CompositorNodeValue
VECBLUR CompositorNodeVecBlur
VIEWER CompositorNodeViewer
ZCOMBINE CompositorNodeZcombine

Texture Nodes
type bl_idname
AT TextureNodeAt
BRICKS TextureNodeBricks
CHECKER TextureNodeChecker
COMPOSE TextureNodeCompose
COORD TextureNodeCoordinates
CURVE_RGB TextureNodeCurveRGB
CURVE_TIME TextureNodeCurveTime
DECOMPOSE TextureNodeDecompose
DISTANCE TextureNodeDistance
GROUP TextureNodeGroup
HUE_SAT TextureNodeHueSaturation
IMAGE TextureNodeImage
INVERT TextureNodeInvert
MATH TextureNodeMath
MIX_RGB TextureNodeMixRGB
OUTPUT TextureNodeOutput
ROTATE TextureNodeRotate
SCALE TextureNodeScale
TEXTURE TextureNodeTexture
TEX_BLEND TextureNodeTexBlend
TEX_CLOUDS TextureNodeTexClouds
TEX_DISTNOISE TextureNodeTexDistNoise
TEX_MAGIC TextureNodeTexMagic
TEX_MARBLE TextureNodeTexMarble
TEX_MUSGRAVE TextureNodeTexMusgrave
TEX_NOISE TextureNodeTexNoise
TEX_STUCCI TextureNodeTexStucci
TEX_VORONOI TextureNodeTexVoronoi
TEX_WOOD TextureNodeTexWood
TRANSLATE TextureNodeTranslate
VALTONOR TextureNodeValToNor
VIEWER TextureNodeViewer

The tables above were generated with a python script. This may need to be rerun in case nodes are added and missing in these lists:

import bpy
trees = [
    ('ShaderNodeTree', 'ShaderNode', 'Shader Nodes'),
    ('CompositorNodeTree', 'CompositorNode', 'Compositor Nodes'),
    ('TextureNodeTree', 'TextureNode', 'Texture Nodes'),
for tree_idname, node_idname, type_category in trees:
    treetype = getattr(bpy.types, tree_idname)
    nodetype = getattr(bpy.types, node_idname)
#    print(treetype, nodetype)
    if not treetype or not nodetype:
    tree ="test", tree_idname)
    node_map = {}
    for c in nodetype.__subclasses__():
#        print(c)
        if hasattr(c, "bl_rna"):
                node =
                node_map[node.type] = node.bl_idname
#                print("%s -> %s" % (node.type, c.bl_rna.identifier))
    sorted_node_map = sorted(node_map.items(), key=lambda item: item[0])
    table = "{| {{Css/prettytable|75%%|talign=left}}\n| '''type''' || '''bl_idname'''\n|-\n%s|}" \
            % "|-\n".join("| %s || %s\n" % (key, value) for key, value in sorted_node_map)
    print("\n\n=====%s=====\n" % type_category)


Node Socket in_out (r60660)

This was an enum property with 2 modes 'IN' and 'OUT'. Now there is a boolean property is_output instead that can be used in the same way:


socket.in_out == 'IN'  # is it an input socket?
socket.in_out == 'OUT' # is it an output socket?


not socket.is_output   # is it an input socket?
socket.is_output       # is it an output socket?

Python Node Output Drawing (r60661)

Node output sockets now use the same button drawing function as input sockets, instead of always displaying just the label. This means pynodes scripters have to make a small adjustment in order to draw sockets in the established way, i.e. only showing labels for outputs:

     def draw(self, context, layout, node, text):
-        if self.is_linked:
+        if self.is_output or self.is_linked:
             # draw full property buttons here