Merge branch 'blender2.7' of git.blender.org:blender
[blender.git] / doc / python_api / rst / info_overview.rst
1
2 .. _info_overview:
3
4 *******************
5 Python API Overview
6 *******************
7
8 The purpose of this document is to explain how Python and Blender fit together,
9 covering some of the functionality that may not be obvious from reading the API
10 references and example scripts.
11
12
13 Python in Blender
14 =================
15
16 Blender has an embedded Python interpreter which is loaded when Blender is started and stays
17 active while Blender is running. This interpreter runs scripts to draw the user interface
18 and is used for some of Blender’s internal tools as well.
19
20 Blender's embedded interpreter provides a typical Python environment, so code from tutorials
21 on how to write Python scripts can also be run with Blender’s interpreter. Blender provides its
22 Python modules, such as :mod:`bpy` and :mod:`mathutils`, to the embedded interpreter so they can
23 be imported into a script and give access to Blender's data, classes, and functions. Scripts that
24 deal with Blender data will need to import the modules to work.
25
26 Here is a simple example which moves a vertex attached to an object named **Cube**:
27
28 .. code-block:: python
29
30    import bpy
31    bpy.data.objects["Cube"].data.vertices[0].co.x += 1.0
32
33 This modifies Blender's internal data directly.
34 When you run this in the interactive console you will see the 3D viewport update.
35
36
37 The Default Environment
38 =======================
39
40 When developing your own scripts it may help to understand how Blender sets up its Python environment.
41 Many Python scripts come bundled with Blender and can be used as a reference
42 because they use the same API that script authors write tools in.
43 Typical usage for scripts include: user interface, import/export,
44 scene manipulation, automation, defining your own toolset and customization.
45
46 On startup Blender scans the ``scripts/startup/`` directory for Python modules and imports them.
47 The exact location of this directory depends on your installation.
48 See the :ref:`directory layout docs <blender_manual:getting-started_installing-config-directories>`.
49
50
51 Script Loading
52 ==============
53
54 This may seem obvious, but it is important to note the difference between
55 executing a script directly and importing a script as a module.
56
57 Extending Blender by executing a script directly means the classes that the script
58 defines remain available inside Blender after the script finishes execution.
59 Using scripts this way makes future access to their classes
60 (to unregister them for example) more difficult compared to importing the scripts as modules.
61 When a script is imported as a module, its class instances will remain
62 inside the module and can be accessed later on by importing that module again.
63
64 For this reason it is preferable to avoid directly executing scripts that extend Blender by registering classes.
65
66
67 Here are some ways to run scripts directly in Blender.
68
69 - Loaded in the text editor and press **Run Script**.
70 - Typed or pasted into the interactive console.
71 - Execute a Python file from the command line with Blender, eg:
72
73   .. code-block:: sh
74
75      blender --python /home/me/my_script.py
76
77
78 To run as modules:
79
80 - The obvious way, ``import some_module`` command from the text window or interactive console.
81 - Open as a text block and tick "Register" option, this will load with the blend file.
82 - copy into one of the directories ``scripts/startup``, where they will be automatically imported on startup.
83 - define as an add-on, enabling the add-on will load it as a Python module.
84
85
86 Add-ons
87 -------
88
89 Some of Blenders functionality is best kept optional,
90 alongside scripts loaded at startup we have add-ons which are kept in their own directory ``scripts/addons``,
91 and only load on startup if selected from the user preferences.
92
93 The only difference between add-ons and built-in Python modules is that add-ons must contain a ``bl_info``
94 variable which Blender uses to read metadata such as name, author, category and URL.
95
96 The User Preferences add-on listing uses **bl_info** to display information about each add-on.
97
98 `See Add-ons <https://wiki.blender.org/index.php/Dev:Py/Scripts/Guidelines/Addons>`__
99 for details on the ``bl_info`` dictionary.
100
101
102 Integration through Classes
103 ===========================
104
105 Running Python scripts in the text editor is useful for testing but you'll
106 want to extend Blender to make tools accessible like other built-in functionality.
107
108 The Blender Python api allows integration for:
109
110 - :class:`bpy.types.Panel`
111 - :class:`bpy.types.Menu`
112 - :class:`bpy.types.Operator`
113 - :class:`bpy.types.PropertyGroup`
114 - :class:`bpy.types.KeyingSet`
115 - :class:`bpy.types.RenderEngine`
116
117
118 This is intentionally limited. Currently, for more advanced features such as mesh modifiers,
119 object types, or shader nodes, C/C++ must be used.
120
121 For Python integration Blender defines methods which are common to all types.
122 This works by creating a Python subclass of a Blender class which contains variables and functions
123 specified by the parent class which are pre-defined to interface with Blender.
124
125 For example:
126
127 .. code-block:: python
128
129    import bpy
130    class SimpleOperator(bpy.types.Operator):
131        bl_idname = "object.simple_operator"
132        bl_label = "Tool Name"
133
134        def execute(self, context):
135            print("Hello World")
136            return {'FINISHED'}
137
138    bpy.utils.register_class(SimpleOperator)
139
140 First note that we subclass a member of :mod:`bpy.types`,
141 this is common for all classes which can be integrated with Blender and
142 used so we know if this is an Operator and not a Panel when registering.
143
144 Both class properties start with a ``bl_`` prefix.
145 This is a convention used to distinguish Blender properties from those you add yourself.
146
147 Next see the execute function, which takes an instance of the operator and the current context.
148 A common prefix is not used for functions.
149
150 Lastly the register function is called, this takes the class and loads it into Blender. See `Class Registration`_.
151
152 Regarding inheritance, Blender doesn't impose restrictions on the kinds of class inheritance used,
153 the registration checks will use attributes and functions defined in parent classes.
154
155 class mix-in example:
156
157 .. code-block:: python
158
159    import bpy
160    class BaseOperator:
161        def execute(self, context):
162            print("Hello World BaseClass")
163            return {'FINISHED'}
164
165    class SimpleOperator(bpy.types.Operator, BaseOperator):
166        bl_idname = "object.simple_operator"
167        bl_label = "Tool Name"
168
169    bpy.utils.register_class(SimpleOperator)
170
171 Notice these classes don't define an ``__init__(self)`` function.
172 While ``__init__()`` and ``__del__()`` will be called if defined,
173 the class instances lifetime only spans the execution.
174 So a panel for example will have a new instance for every redraw,
175 for this reason there is rarely a cause to store variables in the panel instance.
176 Instead, persistent variables should be stored in Blenders
177 ata so that the state can be restored when Blender is restarted.
178
179 .. note::
180
181    Modal operators are an exception, keeping their instance variable as Blender runs, see modal operator template.
182
183 So once the class is registered with Blender, instancing the class and calling the functions is left up to Blender.
184 In fact you cannot instance these classes from the script as you would expect with most Python API's.
185
186 To run operators you can call them through the operator api, eg:
187
188 .. code-block:: python
189
190    import bpy
191    bpy.ops.object.simple_operator()
192
193 User interface classes are given a context in which to draw, buttons window, file header, toolbar etc,
194 then they are drawn when that area is displayed so they are never called by Python scripts directly.
195
196
197 .. _info_overview_registration:
198
199 Registration
200 ============
201
202 Module Registration
203 -------------------
204
205 Blender modules loaded at startup require ``register()`` and ``unregister()`` functions.
206 These are the *only* functions that Blender calls from your code, which is otherwise a regular Python module.
207
208 A simple Blender/Python module can look like this:
209
210 .. code-block:: python
211
212    import bpy
213
214    class SimpleOperator(bpy.types.Operator):
215        """ See example above """
216
217    def register():
218        bpy.utils.register_class(SimpleOperator)
219
220    def unregister():
221        bpy.utils.unregister_class(SimpleOperator)
222
223    if __name__ == "__main__":
224        register()
225
226 These functions usually appear at the bottom of the script containing class registration sometimes adding menu items.
227 You can also use them for internal purposes setting up data for your own tools but take care
228 since register won't re-run when a new blend file is loaded.
229
230 The register/unregister calls are used so it's possible to toggle add-ons and reload scripts while Blender runs.
231 If the register calls were placed in the body of the script, registration would be called on import,
232 meaning there would be no distinction between importing a module or loading its classes into Blender.
233
234 This becomes problematic when a script imports classes from another module
235 making it difficult to manage which classes are being loaded and when.
236
237 The last 2 lines are only for testing:
238
239 .. code-block:: python
240
241    if __name__ == "__main__":
242        register()
243
244 This allows the script to be run directly in the text editor to test changes.
245 This ``register()`` call won't run when the script is imported as a module
246 since ``__main__`` is reserved for direct execution.
247
248
249 Class Registration
250 ------------------
251
252 Registering a class with Blender results in the class definition being loaded into Blender,
253 where it becomes available alongside existing functionality.
254
255 Once this class is loaded you can access it from :mod:`bpy.types`,
256 using the bl_idname rather than the classes original name.
257
258 When loading a class, Blender performs sanity checks making sure all required properties and functions are found,
259 that properties have the correct type, and that functions have the right number of arguments.
260
261 Mostly you will not need concern yourself with this but if there is a problem
262 with the class definition it will be raised on registering:
263
264 Using the function arguments ``def execute(self, context, spam)``, will raise an exception:
265
266 ``ValueError: expected Operator, SimpleOperator class "execute" function to have 2 args, found 3``
267
268 Using ``bl_idname = 1`` will raise.
269
270 ``TypeError: validating class error: Operator.bl_idname expected a string type, not int``
271
272
273 Multiple-Classes
274 ^^^^^^^^^^^^^^^^
275
276 Loading classes into Blender is described above,
277 for simple cases calling :mod:`bpy.utils.register_class` (SomeClass) is sufficient,
278 but when there are many classes or a packages submodule has its own
279 classes it can be tedious to list them all for registration.
280
281 For more convenient loading/unloading :mod:`bpy.utils.register_module` (module)
282 and :mod:`bpy.utils.unregister_module` (module) functions exist.
283
284 A script which defines many of its own operators, panels menus etc. you only need to write:
285
286 .. code-block:: python
287
288    def register():
289        bpy.utils.register_module(__name__)
290
291    def unregister():
292        bpy.utils.unregister_module(__name__)
293
294 Internally Blender collects subclasses on registrable types, storing them by the module in which they are defined.
295 By passing the module name to :mod:`bpy.utils.register_module`
296 Blender can register all classes created by this module and its submodules.
297
298
299 Inter Classes Dependencies
300 ^^^^^^^^^^^^^^^^^^^^^^^^^^
301
302 When customizing Blender you may want to group your own settings together,
303 after all, they will likely have to co-exist with other scripts.
304 To group these properties classes need to be defined,
305 for groups within groups or collections within groups
306 you can find yourself having to deal with order of registration/unregistration.
307
308 Custom properties groups are themselves classes which need to be registered.
309
310 Say you want to store material settings for a custom engine.
311
312 .. code-block:: python
313
314    # Create new property
315    # bpy.data.materials[0].my_custom_props.my_float
316    import bpy
317
318    class MyMaterialProps(bpy.types.PropertyGroup):
319        my_float = bpy.props.FloatProperty()
320
321    def register():
322        bpy.utils.register_class(MyMaterialProps)
323        bpy.types.Material.my_custom_props = bpy.props.PointerProperty(type=MyMaterialProps)
324
325    def unregister():
326        del bpy.types.Material.my_custom_props
327        bpy.utils.unregister_class(MyMaterialProps)
328
329    if __name__ == "__main__":
330        register()
331
332 .. note::
333
334    *The class must be registered before being used in a property, failing to do so will raise an error:*
335
336    ``ValueError: bpy_struct "Material" registration error: my_custom_props could not register``
337
338
339 .. code-block:: python
340
341    # Create new property group with a sub property
342    # bpy.data.materials[0].my_custom_props.sub_group.my_float
343    import bpy
344
345    class MyMaterialSubProps(bpy.types.PropertyGroup):
346        my_float = bpy.props.FloatProperty()
347
348    class MyMaterialGroupProps(bpy.types.PropertyGroup):
349        sub_group = bpy.props.PointerProperty(type=MyMaterialSubProps)
350
351    def register():
352        bpy.utils.register_class(MyMaterialSubProps)
353        bpy.utils.register_class(MyMaterialGroupProps)
354        bpy.types.Material.my_custom_props = bpy.props.PointerProperty(type=MyMaterialGroupProps)
355
356    def unregister():
357        del bpy.types.Material.my_custom_props
358        bpy.utils.unregister_class(MyMaterialGroupProps)
359        bpy.utils.unregister_class(MyMaterialSubProps)
360
361    if __name__ == "__main__":
362        register()
363
364 .. note::
365
366    *The lower most class needs to be registered first and that unregister() is a mirror of register()*
367
368
369 Manipulating Classes
370 ^^^^^^^^^^^^^^^^^^^^
371
372 Properties can be added and removed as Blender runs,
373 normally happens on register or unregister but for some
374 special cases it may be useful to modify types as the script runs.
375
376 For example:
377
378 .. code-block:: python
379
380    # add a new property to an existing type
381    bpy.types.Object.my_float = bpy.props.FloatProperty()
382    # remove
383    del bpy.types.Object.my_float
384
385 This works just as well for PropertyGroup subclasses you define yourself.
386
387 .. code-block:: python
388
389    class MyPropGroup(bpy.types.PropertyGroup):
390        pass
391    MyPropGroup.my_float = bpy.props.FloatProperty()
392
393 ...this is equivalent to:
394
395 .. code-block:: python
396
397    class MyPropGroup(bpy.types.PropertyGroup):
398        my_float = bpy.props.FloatProperty()
399
400
401 Dynamic Defined-Classes (Advanced)
402 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
403
404 In some cases the specifier for data may not be in Blender, renderman shader definitions
405 for example, and it may be useful to define them as types and remove them on the fly.
406
407 .. code-block:: python
408
409    for i in range(10):
410        idname = "object.operator_%d" % i
411
412        def func(self, context):
413            print("Hello World", self.bl_idname)
414            return {'FINISHED'}
415
416        opclass = type("DynOp%d" % i,
417                       (bpy.types.Operator, ),
418                       {"bl_idname": idname, "bl_label": "Test", "execute": func},
419                       )
420        bpy.utils.register_class(opclass)
421
422 .. note::
423
424    ``type()`` is called to define the class.
425    This is an alternative syntax for class creation in Python, better suited to constructing classes dynamically.
426
427
428 To call the operators from the previous example:
429
430    >>> bpy.ops.object.operator_1()
431    Hello World OBJECT_OT_operator_1
432    {'FINISHED'}
433
434    >>> bpy.ops.object.operator_2()
435    Hello World OBJECT_OT_operator_2
436    {'FINISHED'}