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