Merge branch 'blender2.7'
[blender.git] / doc / python_api / rst / info_tips_and_tricks.rst
1
2 ***************
3 Tips and Tricks
4 ***************
5
6 Here are various suggestions that you might find useful when writing scripts.
7
8 Some of these are just Python features that scripters may not have thought to use with Blender,
9 others are Blender specific.
10
11
12 .. _use_the_terminal:
13
14 Use The Terminal
15 ================
16
17 When writing Python scripts, it's useful to have a terminal open,
18 this is not the built-in Python console but a terminal application which is used to start Blender.
19
20 There are 3 main uses for the terminal, these are:
21
22 - You can see the output of ``print()`` as your script runs, which is useful to view debug info.
23 - The error trace-back is printed in full to the terminal which won't always generate an error popup in
24   Blender's user interface (depending on how the script is executed).
25 - If the script runs for too long or you accidentally enter an infinite loop,
26   :kbd:`Ctrl-C` in the terminal (:kbd:`Ctrl-Break` on Windows) will quit the script early.
27
28 .. note::
29
30    For Linux and macOS users this means starting the terminal first, then running Blender from within it.
31    On Windows the terminal can be enabled from the help menu.
32
33
34 Interface Tricks
35 ================
36
37
38 Access Operator Commands
39 ------------------------
40
41 You may have noticed that the tooltip for menu items and buttons includes the ``bpy.ops.[...])`` command
42 to run that button, a handy (hidden) feature is that you can press :kbd:`Ctrl-C` over
43 any menu item/button to copy this command into the clipboard.
44
45
46 Access Data Path
47 ----------------
48
49 To find the path from an :class:`ID` datablock to its setting isn't always so simple since it may be nested away.
50 To get this quickly you can right click on the setting and select select **Copy Data Path**,
51 if this can't be generated, only the property name is copied.
52
53 .. note::
54
55    This uses the same method for creating the animation path used by
56    :class:`bpy.types.FCurve.data_path` and
57    :class:`bpy.types.DriverTarget.data_path` drivers.
58
59
60 .. _info_show_all_operators:
61
62 Show All Operators
63 ==================
64
65 While Blender logs operators in the Info space,
66 this only reports operators with the ``REGISTER`` option enabeld so as not to flood the *Info* view
67 with calls to ``bpy.ops.view3d.smoothview`` and ``bpy.ops.view3d.zoom``.
68
69 However, for testing it can be useful to see **every** operator called in a terminal,
70 do this by enabling the debug option either by passing the ``--debug-wm`` argument when starting Blender
71 or by setting :mod:`bpy.app.debug_wm` to ``True`` while Blender is running.
72
73
74 Use an External Editor
75 ======================
76
77 Blenders text editor is fine for small changes and writing tests but its not full featured,
78 for larger projects you'll probably want to use a standalone editor or Python IDE.
79
80 Editing a text file externally and having the same text open in Blender does work but isn't that optimal
81 so here are 2 ways you can easily use an external file from Blender.
82
83 Using the following examples you'll still need textblock in Blender to execute,
84 but reference an external file rather than including it directly.
85
86
87 Executing External Scripts
88 --------------------------
89
90 This is the equivalent to running the script directly, referencing a scripts path from a 2 line text-block.
91
92 .. code-block:: python
93
94    filename = "/full/path/to/myscript.py"
95    exec(compile(open(filename).read(), filename, 'exec'))
96
97
98 You might want to reference a script relative to the blend file.
99
100 .. code-block:: python
101
102    import bpy
103    import os
104
105    filename = os.path.join(os.path.dirname(bpy.data.filepath), "myscript.py")
106    exec(compile(open(filename).read(), filename, 'exec'))
107
108
109 Executing Modules
110 -----------------
111
112 This example shows loading a script in as a module and executing a module function.
113
114 .. code-block:: python
115
116    import myscript
117    import importlib
118
119    importlib.reload(myscript)
120    myscript.main()
121
122
123 Notice that the script is reloaded every time, this forces use of the modified version,
124 otherwise the cached one in ``sys.modules`` would be used until Blender was restarted.
125
126 The important difference between this and executing the script directly is it
127 has to call a function in the module, in this case ``main()`` but it can be any function,
128 an advantage with this is you can pass arguments to the function from this
129 small script which is often useful for testing different settings quickly.
130
131 The other issue with this is the script has to be in Pythons module search path.
132 While this is not best practice - for testing you can extend the search path,
133 this example adds the current blend files directory to the search path, then loads the script as a module.
134
135 .. code-block:: python
136
137    import sys
138    import os
139    import bpy
140
141    blend_dir = os.path.dirname(bpy.data.filepath)
142    if blend_dir not in sys.path:
143       sys.path.append(blend_dir)
144
145    import myscript
146    import importlib
147    importlib.reload(myscript)
148    myscript.main()
149
150
151 Don't Use Blender!
152 ==================
153
154 While developing your own scripts Blenders interface can get in the way,
155 manually reloading, running the scripts, opening file import etc. adds overhead.
156
157 For scripts that are not interactive it can end up being more efficient not to use
158 Blenders interface at all and instead execute the script on the command line.
159
160 .. code-block:: sh
161
162    blender --background --python myscript.py
163
164
165 You might want to run this with a blend file so the script has some data to operate on.
166
167 .. code-block:: sh
168
169    blender myscene.blend --background --python myscript.py
170
171
172 .. note::
173
174    Depending on your setup you might have to enter the full path to the Blender executable.
175
176
177 Once the script is running properly in background mode, you'll want to check the output of the script,
178 this depends completely on the task at hand however here are some suggestions.
179
180 - render the output to an image, use an image viewer and keep writing over the same image each time.
181 - save a new blend file, or export the file using one of Blenders exporters.
182 - if the results can be displayed as text - print them or write them to a file.
183
184
185 While this can take a little time to setup, it can be well worth the effort
186 to reduce the time it takes to test changes - you can even have
187 Blender running the script every few seconds with a viewer updating the results,
188 so no need to leave your text editor to see changes.
189
190
191 Use External Tools
192 ==================
193
194 When there are no readily available Python modules to perform specific tasks it's
195 worth keeping in mind you may be able to have Python execute an external command
196 on your data and read the result back in.
197
198 Using external programs adds an extra dependency and may limit who can use the script
199 but to quickly setup your own custom pipeline or writing one-off scripts this can be handy.
200
201 Examples include:
202
203 - Run The Gimp in batch mode to execute custom scripts for advanced image processing.
204 - Write out 3D models to use external mesh manipulation tools and read back in the results.
205 - Convert files into recognizable formats before reading.
206
207
208 Bundled Python & Extensions
209 ===========================
210
211 The Blender releases distributed from blender.org include a complete Python installation on all platforms,
212 this has the disadvantage that any extensions you have installed in your systems Python won't be found by Blender.
213
214 There are 2 ways around this:
215
216 - Remove Blender Python sub-directory, Blender will then fallback on the systems Python and use that instead.
217
218   Depending on your platform,
219   you may need to explicitly reference the location of your Python installation using the
220   ``PYTHONPATH`` environment variable, eg:
221
222   .. code-block:: sh
223
224      PYTHONPATH=/usr/lib/python3.5 ./blender
225
226   .. warning::
227
228      The Python version must match the one that Blender comes with.
229
230 - Copy or link the extensions into Blender's Python sub-directory so Blender can access them,
231   you could also copy the entire Python installation into Blenders sub-directory,
232   replacing the one Blender comes with.
233   This works as long as the Python versions match and the paths are created in the same relative locations.
234   Doing this has the advantage that you can redistribute this bundle to others with Blender
235   including any extensions you rely on.
236
237
238 Drop Into a Python Interpreter in Your Script
239 =============================================
240
241 In the middle of a script you may want to inspect some variables,
242 run some function and generally dig about to see whats going on.
243
244 .. code-block:: python
245
246    import code
247    code.interact(local=locals())
248
249
250 If you want to access both global and local variables do this...
251
252 .. code-block:: python
253
254    import code
255    namespace = globals().copy()
256    namespace.update(locals())
257    code.interact(local=namespace)
258
259
260 The next example is an equivalent single line version of the script above which is easier to paste into your code:
261
262 .. code-block:: python
263
264    __import__('code').interact(local=dict(globals(), **locals()))
265
266
267 ``code.interact`` can be added at any line in the script
268 and will pause the script an launch an interactive interpreter in the terminal,
269 when you're done you can quit the interpreter and the script will continue execution.
270
271
272 If you have **IPython** installed you can use its ``embed()`` function which uses the current namespace.
273 The IPython prompt has auto-complete and some useful features that the standard Python eval-loop doesn't have.
274
275 .. code-block:: python
276
277    import IPython
278    IPython.embed()
279
280
281 Admittedly this highlights the lack of any Python debugging support built into Blender, but its still handy to know.
282
283 Advanced
284 ========
285
286
287 Blender as a module
288 -------------------
289
290 From a Python perspective it's nicer to have everything as an extension
291 which lets the Python script combine many components.
292
293 Advantages include:
294
295 - you can use external editors/IDE's with Blenders Python API and execute scripts within the IDE
296   (step over code, inspect variables as the script runs).
297 - editors/IDE's can auto complete Blender modules & variables.
298 - existing scripts can import Blender API's without having to run inside Blender.
299
300
301 This is marked advanced because to run Blender as a Python module requires a special build option.
302
303 For instructions on building see
304 `Building Blender as a Python module <https://wiki.blender.org/index.php/User:Ideasman42/BlenderAsPyModule>`_
305
306
307 Python Safety (Build Option)
308 ----------------------------
309
310 Since it's possible to access data which has been removed (see Gotcha's),
311 this can be hard to track down the cause of crashes.
312
313 To raise Python exceptions on accessing freed data (rather than crashing),
314 enable the CMake build option ``WITH_PYTHON_SAFETY``.
315
316 This enables data tracking which makes data access about 2x slower
317 which is why the option isn't enabled in release builds.