Once you have a data block, such as a material, object, groups etc., its attributes can be accessed much like you would change a setting using the graphical interface. In fact, the tooltip for each button also displays the Python attribute which can help in finding what settings to change in a script.

This is an intentional part of the API design.
The blender/python api can’t create blender data that exists outside the main blender database (accessed through bpy.data), because this data is managed by blender (save/load/undo/append... etc).

Data is added and removed via methods on the collections in bpy.data, eg:

Python can access properties on any datablock that has an ID (data that can be linked in and accessed from bpy.data. When assigning a property, you can make up your own names, these will be created when needed or overwritten if they exist.

This data is saved with the blend file and copied with objects.

Example:

bpy.context.object["MyOwnProperty"]=42if"SomeProp"inbpy.context.object:print("Property found")# Use the get function like a python dictionary# which can have a fallback value.value=bpy.data.scenes["Scene"].get("test_prop","fallback value")# dictionaries can be assigned as long as they only use basic types.group=bpy.data.groups.new("MyTestGroup")group["GameSettings"]={"foo":10,"bar":"spam","baz":{}}delgroup["GameSettings"]

While it’s useful to be able to access data directly by name or as a list, it’s more common to operate on the user’s selection. The context is always available from ‘’‘bpy.context’‘’ and can be used to get the active object, scene, tool settings along with many other attributes.

Note that the context is read-only. These values cannot be modified directly, though they may be changed by running API functions or by using the data API.

So bpy.context.object=obj will raise an error.

But bpy.context.scene.objects.active=obj will work as expected.

The context attributes change depending on where they are accessed. The 3D view has different context members than the console, so take care when accessing context attributes that the user state is known.

Operators are tools generally accessed by the user from buttons, menu items or key shortcuts. From the user perspective they are a tool but Python can run these with its own settings through the bpy.ops module.

The menu item: Help -> Operator Cheat Sheet” gives a list of all operators and their default values in Python syntax, along with the generated docs. This is a good way to get an overview of all blender’s operators.

Many operators have a “poll” function which may check that the mouse is a valid area or that the object is in the correct mode (Edit Mode, Weight Paint etc). When an operator’s poll function fails within python, an exception is raised.

For example, calling bpy.ops.view3d.render_border() from the console raises the following error:

mathutils types keep a reference to Blender’s internal data so changes can
be applied back.

Example:

# modifies the Z axis in place.bpy.context.object.location.z+=2.0# location variable holds a reference to the object too.location=bpy.context.object.locationlocation*=2.0# Copying the value drops the reference so the value can be passed to# functions and modified without unwanted side effects.location=bpy.context.object.location.copy()

The first is through key properties directly, which is similar to inserting a keyframe from the button as a user. You can also manually create the curves and keyframe data, then set the path to the property. Here are examples of both methods.