Extensions:2.6/Py/API Changes

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!

2.66

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:

# OLD
template_list(bpy.context.scene, "your_collection", bpy.context.scene, "your_collection_idx")

# NEW
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:

# OLD
self._handle = context.region.callback_add(draw_callback_px, (self, context), 'POST_PIXEL')
context.region.callback_remove(self._handle)

# NEW
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
            context.window_manager.event_timer_remove(self._timer)
            context.region.callback_remove(self._handle)
            return {'CANCELLED'}

        return {'PASS_THROUGH'}

    def cancel(self, context):
        if context.window_manager.screencast_keys_keys:
            context.window_manager.event_timer_remove(self._timer)
            context.region.callback_remove(self._handle)
            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,
                    context.window)

# ...
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

    @staticmethod
    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)

    @staticmethod
    def handle_remove(context):
        if ScreencastKeysStatus._handle is not None:
            context.window_manager.event_timer_remove(ScreencastKeysStatus._timer)
            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

            ScreencastKeysStatus.handle_remove(context)
            return {'CANCELLED'}

        return {'PASS_THROUGH'}

    def cancel(self, context):
        if context.window_manager.screencast_keys_keys:

            ScreencastKeysStatus.handle_remove(context)
            context.window_manager.screencast_keys_keys = False
        return {'CANCELLED'}

    def invoke(self, context, event):
        # ...



                ScreencastKeysStatus.handle_add(self, context)

# ...
def unregister():
    ScreencastKeysStatus.handle_remove(bpy.context)
# ...

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 bpy.data.

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
        else:
            layout.label("my_prop = " + context.scene.my_prop)

        layout.operator(InitMyPropOperator.bl_idname, text=InitMyPropOperator.bl_label)

class InitMyPropOperator(bpy.types.Operator):
    """Tooltip"""
    bl_idname = "scene.init_my_prop"
    bl_label = "Init my_prop"

    @classmethod
    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"
        else:
            context.scene.my_prop = "foobar"
            self.__class__.bl_label = self.bl_label
        return {'FINISHED'}


def register():
    bpy.utils.register_module(__name__)
    bpy.types.Scene.my_prop = bpy.props.StringProperty(default="default value")

def unregister():
    bpy.utils.unregister_module(__name__)
    del bpy.types.Scene.my_prop

if __name__ == "__main__":
    register()

Also see: mailing list thread

2.67

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 nodetree.nodes.new 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

node.bl_idname

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
RGBTOBW	ShaderNodeRGBToBW
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
VALTORGB	ShaderNodeValToRGB
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
RGBTOBW	CompositorNodeRGBToBW
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
RGBTOBW	TextureNodeRGBToBW
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
VALTORGB	TextureNodeValToRGB
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:
        continue
    tree = bpy.data.node_groups.new("test", tree_idname)

    node_map = {}

    for c in nodetype.__subclasses__():
#        print(c)
        if hasattr(c, "bl_rna"):
            try:
                node = tree.nodes.new(c.bl_rna.identifier)
                node_map[node.type] = node.bl_idname
#                print("%s -> %s" % (node.type, c.bl_rna.identifier))
                shader_tree.nodes.remove(node)
            except:
                pass

    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)
    print(table)

2.70

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:

old:

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

new:

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:
             layout.label(text)
         else:
             # draw full property buttons here