Python Entities and API

Blender expands Python by making the modules of its Application Programming Interface (API) available inside the app.

These modules provide wrappers that translate Blender’s internal data into Python objects. Comprehensive documentation and an API reference are available online and can be reached from inside the application. Plus, there are some extra features to help programmers in their journey.

Much like the syntax highlight that we have met in Chapter 1, some features for developers are common-place in the programming world. Others, such as property tooltips and variables display, are specific to Blender.

In this chapter, we are going to look at some snippets, that is, chunks of code, that will help you become confident with the architecture of Blender’s API.

Generally, the API is designed to be very friendly to programmers that are already experienced with Python, only deviating a few times from the standards.

By the end of...

Technical requirements

Only Blender is needed to follow along with this chapter.

Useful features of Python

We already met the Python elements of the Scripting workspace in Chapter 1. Now we are going to look at some useful features that can help us get the most out of them. When it comes to programming, automation can speed up the search for attributes and terms. That can happen both in the console, through conventional methods such as autocompletion, or in the interface, via shortcuts that display the Python address of a graphic element. Some of these features are already available when Blender starts, while others are left for the users to enable.

Options for developers

Developer features are disabled by default. They can be enabled in the Preferences dialog from the Edit menu in the top bar of Blender. We need to select the Interface tab on the left and look at the first panel: Display. Programmers usually enable the Developer Extras and Python Tooltips options.

Developer Extras

Developer Extras adds a right-click menu entry that can display the...

Accessing Blender modules

Blender’s additional modules are available throughout the application and can be used via the standard import statement. They are available in the Python console, the Text Editor, and generally in the scripts that are installed in the Blender system and user paths.

Some modules are very specific; for instance, the freestyle module handles the settings of the freestyle stylized rendering and cannot be used for any other purpose. Others, such as mathutils, come into play whenever numbers are concerned.

Finally, the bpy module and its submodules play a bigger role in Blender scripts, as they grant access to objects and data.

In this section, we will have a closer look at bpy, how it is already present in the console, and how we can use it in our scripts. We will also learn where to find more information about the API and its elements.

The bpy module

In Chapter 1, we copied the lines from the console using Console->Copy from the Python...

Accessing Blender data

All the entities created in the current session are available as part of bpy.data. They are grouped in categories that follow the object types available in Blender, so we have bpy.data.armatures, bpy.data.curves, and so on. Each category is a bpy_collection, a Blender type that contains more elements. Their content can be accessed with indices, like in a Python list, or with keywords, like in dictionaries.

Objects access

We can use Python to access the objects of a scene. For example, we can query the content of Blender’s default scene, which contains a Cube, a Camera and a Light:

1. Open or restart Blender and select Scripting Workspace in the workspace tabs at the top of the screen.

Figure 2.10: The workspace tabs

2. Type len(bpy.data.objects) and press Enter:

   >>> len(bpy.data.objects)

   3

3. In the Python console, type bpy.data.objects, then press Tab.

Figure 2.11: Blender...

Understanding the user context

The current state of interaction, the current scene, and the selection are available via bpy.context. Since it depends on the user actions, bpy.context is read-only; that is, it cannot be changed directly. Anyway, we can affect the state of the current activity via Python. Rather than changing the attributes of bpy.context, we must look for the selection and activity properties of Blender’s objects, layers, and scenes.

Active scene

A .blend file, or an unsaved session for that matter, can contain more than one scene. That differs from the standard in 3D packages, where a saved file is equivalent to one scene. If more scenes are available, they can be selected from the list menu at the top right of Blender’s header.

Each scene can contain any of the objects from bpy.data.objects, and one object can belong to more than one scene. Changes made to an object in one scene retained in the others.

We have seen how to create new objects...

Summary

In this chapter, we saw how Python can access the content of Blender via bpy.data and introduced space entities such as vectors. We also saw how to interact with the user activity through bpy.context, and how read-only attributes of context are changed by affecting the status of objects and layers.

In Chapter 3, we will see how to insert our routines in our own add-ons and make them ready to install and use in Blender.

Questions

1. Which helper utilities are typical of Blender?
2. How can we store and display space coordinates?
3. Which attribute of bpy gives access to all Blender entities?
4. Do Python classes of Blender objects have a constructor?
5. How do we create new Blender objects?
6. What does it mean that an object is active?
7. Is the active object a property of the Blender scene?
8. Can we affect the selection using bpy.context?
9. Can we affect the selection using bpy.context.view_layer?