Merge branch 'blender2.7'
[blender.git] / doc / python_api / rst / info_api_reference.rst
1
2 *******************
3 Reference API Usage
4 *******************
5
6 Blender has many interlinking data types which have an auto-generated reference api which often has the information
7 you need to write a script, but can be difficult to use.
8
9 This document is designed to help you understand how to use the reference api.
10
11
12 Reference API Scope
13 ===================
14
15 The reference API covers :mod:`bpy.types`, which stores types accessed via :mod:`bpy.context` - *The user context*
16 or :mod:`bpy.data` - *Blend file data*.
17
18 Other modules such as :mod:`bmesh` and :mod:`aud` are not using Blenders data API
19 so this document doesn't apply to those modules.
20
21
22 Data Access
23 ===========
24
25 The most common case for using the reference API is to find out how to access data in the blend file.
26
27 Before going any further its best to be aware of ID Data-Blocks in Blender since you will often find properties
28 relative to them.
29
30
31 ID Data
32 -------
33
34 ID Data-Blocks are used in Blender as top-level data containers.
35
36 From the user interface this isn't so obvious, but when developing you need to know about ID Data-Blocks.
37
38 ID data types include Scene, Group, Object, Mesh, Screen, World, Armature, Image and Texture.
39 for a full list see the sub-classes of :class:`bpy.types.ID`
40
41 Here are some characteristics ID Data-Blocks share.
42
43 - ID's are blend file data, so loading a new blend file reloads an entire new set of Data-Blocks.
44 - ID's can be accessed in Python from ``bpy.data.*``
45 - Each data-block has a unique ``.name`` attribute, displayed in the interface.
46 - Animation data is stored in ID's ``.animation_data``.
47 - ID's are the only data types that can be linked between blend files.
48 - ID's can be added/copied and removed via Python.
49 - ID's have their own garbage-collection system which frees unused ID's when saving.
50 - When a data-block has a reference to some external data, this is typically an ID Data-Block.
51
52
53 Simple Data Access
54 ------------------
55
56 Lets start with a simple case, say you want a python script to adjust the object's location.
57
58 Start by finding this setting in the interface ``Properties Window -> Object -> Transform -> Location``
59
60 From the button you can right click and select **Online Python Reference**, this will link you to:
61 :class:`bpy.types.Object.location`
62
63 Being an API reference, this link often gives little more information then the tool-tip, though some of the pages
64 include examples (normally at the top of the page).
65
66 At this point you may say *Now what?* - you know that you have to use ``.location`` and that its an array of 3 floats
67 but you're still left wondering how to access this in a script.
68
69 So the next step is to find out where to access objects, go down to the bottom of the page to the **References**
70 section, for objects there are many references, but one of the most common places to access objects is via the context.
71
72 It's easy to be overwhelmed at this point since there ``Object`` get referenced in so many places - modifiers,
73 functions, textures and constraints.
74
75 But if you want to access any data the user has selected
76 you typically only need to check the :mod:`bpy.context` references.
77
78 Even then, in this case there are quite a few though if you read over these - most are mode specific.
79 If you happen to be writing a tool that only runs in weight paint mode, then using ``weight_paint_object``
80 would be appropriate.
81 However to access an item the user last selected, look for the ``active`` members,
82 Having access to a single active member the user selects is a convention in Blender: eg. ``active_bone``,
83 ``active_pose_bone``, ``active_node`` ... and in this case we can use - ``active_object``.
84
85
86 So now we have enough information to find the location of the active object.
87
88 .. code-block:: python
89
90    bpy.context.active_object.location
91
92 You can type this into the python console to see the result.
93
94 The other common place to access objects in the reference is :class:`bpy.types.BlendData.objects`.
95
96 .. note::
97
98    This is **not** listed as :mod:`bpy.data.objects`,
99    this is because :mod:`bpy.data` is an instance of the :class:`bpy.types.BlendData` class,
100    so the documentation points there.
101
102
103 With :mod:`bpy.data.objects`, this is a collection of objects so you need to access one of its members.
104
105 .. code-block:: python
106
107    bpy.data.objects["Cube"].location
108
109
110 Nested Properties
111 -----------------
112
113 The previous example is quite straightforward because ``location`` is a property of ``Object`` which can be accessed
114 from the context directly.
115
116 Here are some more complex examples:
117
118 .. code-block:: python
119
120    # access a render layers samples
121    bpy.context.scene.render.layers["RenderLayer"].samples
122
123    # access to the current weight paint brush size
124    bpy.context.tool_settings.weight_paint.brush.size
125
126    # check if the window is fullscreen
127    bpy.context.window.screen.show_fullscreen
128
129
130 As you can see there are times when you want to access data which is nested
131 in a way that causes you to go through a few indirections.
132
133 The properties are arranged to match how data is stored internally (in blenders C code) which is often logical but
134 not always quite what you would expect from using Blender.
135
136 So this takes some time to learn, it helps you understand how data fits together in Blender which is important
137 to know when writing scripts.
138
139
140 When starting out scripting you will often run into the problem where you're not sure how to access the data you want.
141
142 There are a few ways to do this.
143
144 - Use the Python console's auto-complete to inspect properties.
145   *This can be hit-and-miss but has the advantage
146   that you can easily see the values of properties and assign them to interactively see the results.*
147 - Copy the Data-Path from the user interface.
148   *Explained further in :ref:`Copy Data Path <info_data_path_copy>`*
149 - Using the documentation to follow references.
150   *Explained further in :ref:`Indirect Data Access <info_data_path_indirect>`*
151
152
153 .. _info_data_path_copy:
154
155 Copy Data Path
156 --------------
157
158 Blender can compute the Python string to a property which is shown in the tool-tip, on the line below ``Python: ...``,
159 This saves having to use the API reference to click back up the references to find where data is accessed from.
160
161 There is a user-interface feature to copy the data-path which gives the path from an :class:`bpy.types.ID` data-block,
162 to its property.
163
164 To see how this works we'll get the path to the Subdivision-Surface modifiers subdivision setting.
165
166 Start with the default scene and select the **Modifiers** tab, then add a **Subdivision-Surface** modifier to the cube.
167
168 Now hover your mouse over the button labeled **View**, The tool-tip includes :class:`bpy.types.SubsurfModifier.levels`
169 but we want the path from the object to this property.
170
171 Note that the text copied won't include the ``bpy.data.collection["name"].`` component since its assumed that
172 you won't be doing collection look-ups on every access and typically you'll want to use the context rather
173 then access each :class:`bpy.types.ID` instance by name.
174
175
176 Type in the ID path into a Python console :mod:`bpy.context.active_object`.
177 Include the trailing dot and don't hit "enter", yet.
178
179 Now right-click on the button and select **Copy Data Path**, then paste the result into the console.
180
181 So now you should have the answer:
182
183 .. code-block:: python
184
185    bpy.context.active_object.modifiers["Subsurf"].levels
186
187 Hit "enter" and you'll get the current value of 1. Now try changing the value to 2:
188
189 .. code-block:: python
190
191   bpy.context.active_object.modifiers["Subsurf"].levels = 2
192
193 You can see the value update in the Subdivision-Surface modifier's UI as well as the cube.
194
195
196 .. _info_data_path_indirect:
197
198 Indirect Data Access
199 --------------------
200
201 For this example we'll go over something more involved, showing the steps to access the active sculpt brushes texture.
202
203 Lets say we want to access the texture of a brush via Python, to adjust its ``contrast`` for example.
204
205 - Start in the default scene and enable 'Sculpt' mode from the 3D-View header.
206 - From the toolbar expand the **Texture** panel and add a new texture.
207   *Notice the texture button its self doesn't have very useful links (you can check the tooltips).*
208 - The contrast setting isn't exposed in the sculpt toolbar, so view the texture in the properties panel...
209
210   - In the properties button select the Texture context.
211   - Select the Brush icon to show the brush texture.
212   - Expand the *Colors* panel to locate the *Contrast* button.
213 - Right click on the contrast button and select **Online Python Reference**
214   This takes you to ``bpy.types.Texture.contrast``
215 - Now we can see that ``contrast`` is a property of texture,
216   so next we'll check on how to access the texture from the brush.
217 - Check on the **References** at the bottom of the page, sometimes there are many references, and it may take
218   some guess work to find the right one, but in this case its obviously ``Brush.texture``.
219
220   *Now we know that the texture can be accessed from* ``bpy.data.brushes["BrushName"].texture``
221   *but normally you won't want to access the brush by name, so we'll see now to access the active brush instead.*
222 - So the next step is to check on where brushes are accessed from via the **References**.
223   In this case there is simply ``bpy.context.brush`` which is all we need.
224
225 Now you can use the Python console to form the nested properties needed to access brush textures contrast,
226 logically we now know.
227
228 *Context -> Brush -> Texture -> Contrast*
229
230 Since the attribute for each is given along the way we can compose the data path in the python console:
231
232 .. code-block:: python
233
234    bpy.context.brush.texture.contrast
235
236
237 There can be multiple ways to access the same data, which you choose often depends on the task.
238
239 An alternate path to access the same setting is...
240
241 .. code-block:: python
242
243    bpy.context.sculpt.brush.texture.contrast
244
245 Or access the brush directly...
246
247 .. code-block:: python
248
249    bpy.data.brushes["BrushName"].texture.contrast
250
251
252 If you are writing a user tool normally you want to use the :mod:`bpy.context` since the user normally expects
253 the tool to operate on what they have selected.
254
255 For automation you are more likely to use :mod:`bpy.data` since you want to be able to access specific data and manipulate
256 it, no matter what the user currently has the view set at.
257
258
259 Operators
260 =========
261
262 Most key-strokes and buttons in Blender call an operator which is also exposed to python via :mod:`bpy.ops`,
263
264 To see the Python equivalent hover your mouse over the button and see the tool-tip,
265 eg ``Python: bpy.ops.render.render()``,
266 If there is no tool-tip or the ``Python:`` line is missing then this button is not using an operator and
267 can't be accessed from Python.
268
269
270 If you want to use this in a script you can press :kbd:`Control-C` while your mouse is over the button to copy it to the
271 clipboard.
272
273 You can also right click on the button and view the **Online Python Reference**, this mainly shows arguments and
274 their defaults however operators written in Python show their file and line number which may be useful if you
275 are interested to check on the source code.
276
277 .. note::
278
279    Not all operators can be called usefully from Python,
280    for more on this see :ref:`using operators <using_operators>`.
281
282
283 Info View
284 ---------
285
286 Blender records operators you run and displays them in the **Info** space.
287 This is located above the file-menu which can be dragged down to display its contents.
288
289 Select the **Script** screen that comes default with Blender to see its output.
290 You can perform some actions and see them show up - delete a vertex for example.
291
292 Each entry can be selected (Right-Mouse-Button),
293 then copied :kbd:`Control-C`, usually to paste in the text editor or python console.
294
295 .. note::
296
297    Not all operators get registered for display,
298    zooming the view for example isn't so useful to repeat so its excluded from the output.
299
300    To display *every* operator that runs see :ref:`Show All Operators <info_show_all_operators>`