move wiki api intro and overview docs into the api reference docs.
[blender.git] / doc / python_api / rst / info_overview.rst
1 ###################
2 Python API Overview
3 ###################
4
5 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.
6
7 *****************
8 Python in Blender
9 *****************
10
11 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.
12
13 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. 
14
15 Here is a simple example of moving a vertex of the object named **Cube**:
16
17 .. code-block:: python
18
19    import bpy
20    bpy.data.objects["Cube"].data.vertices[0].co.x += 1.0
21
22 This modifies Blender's internal data directly. When you run this in the interactive console you will see the 3D viewport update.
23
24
25 ***********************
26 The Default Environment
27 ***********************
28
29 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.
30
31 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.5/Manual/Introduction/Installing_Blender/DirectoryLayout>`_
32
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 ======
68 Addons
69 ======
70
71 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.
72
73 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.
74
75 The user preferences addon listing uses **bl_info** to display information about each addon.
76
77 `See Addons <http://wiki.blender.org/index.php/Dev:2.5/Py/Scripts/Guidelines/Addons>`_ for details on the **bl_info** dictionary.
78
79
80 ***************************
81 Integration through Classes
82 ***************************
83
84 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.
85
86 The blender python api allows integration for:
87
88 * :class:`bpy.types.Panel`
89
90 * :class:`bpy.types.Menu`
91
92 * :class:`bpy.types.Operator`
93
94 * :class:`bpy.types.PropertyGroup`
95
96 * :class:`bpy.types.KeyingSet`
97
98 * :class:`bpy.types.RenderEngine`
99
100
101 This is intentionally limited. Currently, for more advanced features such as mesh modifiers, object types, or shader nodes, C/C++ must be used.
102
103 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.
104
105 For example:
106
107 .. code-block:: python
108
109    import bpy
110    class SimpleOperator(bpy.types.Operator):
111        bl_idname = "object.simple_operator"
112        bl_label = "Tool Name"
113
114        def execute(self, context):
115            print("Hello World")
116            return {'FINISHED'}
117
118    bpy.utils.register_class(SimpleOperator)
119
120 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.
121
122 Both class properties start with a **bl_** prefix. This is a convention used to distinguish blender properties from those you add yourself.
123
124 Next see the execute function, which takes an instance of the operator and the current context. A common prefix is not used for functions.
125
126 Lastly the register function is called, this takes the class and loads it into blender. See `Class Registration`_.
127
128 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.
129
130 class mix-in example:
131
132 .. code-block:: python
133
134    import bpy
135    class BaseOperator:
136        def execute(self, context):
137            print("Hello World BaseClass")
138            return {'FINISHED'}
139
140    class SimpleOperator(bpy.types.Operator, BaseOperator):
141        bl_idname = "object.simple_operator"
142        bl_label = "Tool Name"
143
144    bpy.utils.register_class(SimpleOperator)
145
146 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.
147
148 .. note:: Modal operators are an exception, keeping their instance variable as blender runs, see modal operator template.
149
150 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.
151
152 To run operators you can call them through the operator api, eg:
153
154 .. code-block:: python
155
156    import bpy
157    bpy.ops.object.simple_operator()
158
159 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.
160
161
162 ************
163 Registration
164 ************
165
166
167 ===================
168 Module Registration
169 ===================
170
171 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.
172
173 A simple blender/python module can look like this:
174
175 .. code-block:: python
176
177    import bpy
178
179    class SimpleOperator(bpy.types.Operator):
180        """ See example above """
181
182    def register():
183        bpy.utils.register_class(SimpleOperator)
184
185    def unregister():
186        bpy.utils.unregister_class(SimpleOperator)    
187
188    if __name__ == "__main__":
189        register()
190
191 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.
192
193 The register/unregister calls are used so it's possible to toggle addons and reload scripts while blender runs.
194 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.
195
196 This becomes problematic when a script imports classes from another module making it difficult to manage which classes are being loaded and when.
197
198 The last 2 lines are only for testing:
199
200 .. code-block:: python
201
202    if __name__ == "__main__":
203        register()
204
205 This allows the script to be run directly in the text editor to test changes.
206 This ``register()`` call won't run when the script is imported as a module since ``__main__`` is reserved for direct execution.
207
208
209 ==================
210 Class Registration
211 ==================
212
213 Registering a class with blender results in the class definition being loaded into blender, where it becomes available alongside existing functionality.
214
215 Once this class is loaded you can access it from :mod:`bpy.types`, using the bl_idname rather than the classes original name.
216
217 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.
218
219 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:
220
221 Using the function arguments ``def execute(self, context, spam)``, will raise an exception:
222
223 ``ValueError: expected Operator, SimpleOperator class "execute" function to have 2 args, found 3``
224
225 Using ``bl_idname = 1`` will raise.
226
227 ``TypeError: validating class error: Operator.bl_idname expected a string type, not int``
228
229
230 ----------------
231 Multiple-Classes
232 ----------------
233
234 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.
235
236 For more convenient loading/unloading :mod:`bpy.utils.register_module` (module) and :mod:`bpy.utils.unregister_module` (module) functions exist.
237
238 A script which defines many of its own operators, panels menus etc. you only need to write:
239
240 .. code-block:: python
241
242    def register():
243        bpy.utils.register_module(__name__)
244
245    def unregister():
246        bpy.utils.unregister_module(__name__)
247
248 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.
249
250
251 --------------------------
252 Inter Classes Dependencies
253 --------------------------
254
255 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.
256
257 Custom properties groups are themselves classes which need to be registered.
258
259 Say you want to store material settings for a custom engine.
260
261 .. code-block:: python
262
263    # Create new property
264    # bpy.data.materials[0].my_custom_props.my_float
265    import bpy
266
267    class MyMaterialProps(bpy.types.PropertyGroup):
268        my_float = bpy.props.FloatProperty()
269
270    def register():
271        bpy.utils.register_class(MyMaterialProps)
272        bpy.types.Material.my_custom_props = bpy.props.PointerProperty(type=MyMaterialProps)
273
274    def unregister():
275        del bpy.types.Material.my_custom_props
276        bpy.utils.unregister_class(MyMaterialProps)
277
278    if __name__ == "__main__":
279        register()
280
281 .. note::
282
283    *The class must be registered before being used in a property, failing to do so will raise an error:*
284    
285    ``ValueError: bpy_struct "Material" registration error: my_custom_props could not register``
286
287
288 .. code-block:: python
289
290    # Create new property group with a sub property
291    # bpy.data.materials[0].my_custom_props.sub_group.my_float
292    import bpy
293
294    class MyMaterialSubProps(bpy.types.PropertyGroup):
295        my_float = bpy.props.FloatProperty()
296
297    class MyMaterialGroupProps(bpy.types.PropertyGroup):
298        sub_group = bpy.props.PointerProperty(type=MyMaterialSubProps)
299
300    def register():
301        bpy.utils.register_class(MyMaterialSubProps)
302        bpy.utils.register_class(MyMaterialGroupProps)
303        bpy.types.Material.my_custom_props = bpy.props.PointerProperty(type=MyMaterialGroupProps)
304
305    def unregister():
306        del bpy.types.Material.my_custom_props
307        bpy.utils.unregister_class(MyMaterialGroupProps)
308        bpy.utils.unregister_class(MyMaterialSubProps)
309
310    if __name__ == "__main__":
311        register()
312
313 .. note::
314
315    *The lower most class needs to be registered first and that unregister() is a mirror of register()*
316
317
318 --------------------
319 Manipulating Classes
320 --------------------
321
322 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.
323
324 For example:
325
326 .. code-block:: python
327
328    # add a new property to an existing type
329    bpy.types.Object.my_float = bpy.props.FloatProperty()
330    # remove
331    del bpy.types.Object.my_float
332
333 This works just as well for PropertyGroup subclasses you define yourself.
334
335 .. code-block:: python
336
337    class MyPropGroup(bpy.types.PropertyGroup):
338        pass
339    MyPropGroup.my_float = bpy.props.FloatProperty()
340
341 ...this is equivalent to:
342
343 .. code-block:: python
344
345    class MyPropGroup(bpy.types.PropertyGroup):
346        my_float = bpy.props.FloatProperty()
347
348
349 ----------------------------------
350 Dynamic Defined-Classes (Advanced)
351 ----------------------------------
352
353 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.
354
355 .. code-block:: python
356
357    for i in range(10):
358        idname = "object.operator_%d" % i
359
360        def func(self, context):
361            print("Hello World", self.bl_idname)
362            return {'FINISHED'}
363
364        opclass = type("DynOp%d" % i,
365                       (bpy.types.Operator, ),
366                       {"bl_idname": idname, "bl_label": "Test", "execute": func},
367                       )
368        bpy.utils.register_class(opclass)
369
370 .. note::
371
372    Notice ``type()`` is called to define the class. This is an alternative syntax for class creation in python, better suited to constructing classes dynamically.
373
374
375 Calling these operators:
376
377 .. code-block:: python
378
379    >>> bpy.ops.object.operator_1()
380    Hello World OBJECT_OT_operator_1
381    {'FINISHED'}
382
383    >>> bpy.ops.object.operator_2()
384    Hello World OBJECT_OT_operator_2
385    {'FINISHED'}
386