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