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