remove mesh and object arguments from bmesh operators, these are stored within the...
[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
13 When writing python scripts, its useful to have a terminal open, this is not the built-in python console but a terminal application which is used to start blender.
14
15 There are 3 main uses for the terminal, these are:
16
17 * You can see the output of `print()` as you're script runs, which is useful to view debug info.
18
19 * The error trace-back is printed in full to the terminal which wont always generate an error popup in blenders user interface (depending on how the script is executed).
20
21 * 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.
22
23 .. note::
24    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.
25
26
27 Use an External Editor
28 ======================
29
30 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.
31
32 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.
33
34
35 Executing External Scripts
36 --------------------------
37
38 This is the equivalent to running the script directly, referencing a scripts path from a 2 line textblock.
39
40 .. code-block:: python
41
42    filename = "/full/path/to/myscript.py"
43    exec(compile(open(filename).read(), filename, 'exec'))
44
45
46 You might want to reference a script relative to the blend file.
47
48 .. code-block:: python
49
50    import bpy
51    import os
52
53    filename = os.path.join(os.path.basename(bpy.data.filepath), "myscript.py")
54    exec(compile(open(filename).read(), filename, 'exec'))
55
56
57 Executing Modules
58 -----------------
59
60 This example shows loading a script in as a module and executing a module function.
61
62 .. code-block:: python
63
64    import myscript
65    import imp
66
67    imp.reload(myscript)
68    myscript.main()
69
70
71 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.
72
73 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.
74
75 The other issue with this is the script has to be in pythons module search path.
76 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.
77
78 .. code-block:: python
79
80    import sys
81    import os
82    import bpy
83
84    blend_dir = os.path.basename(bpy.data.filepath)
85    if blend_dir not in sys.path:
86       sys.path.append(blend_dir)
87
88    import myscript
89    import imp
90    imp.reload(myscript)
91    myscript.main()
92
93
94 Don't Use Blender!
95 ==================
96
97 While developing your own scripts blenders interface can get in the way, manually reloading, running the scripts, opening file import etc. adds overhead.
98
99 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.
100
101 .. code-block:: python
102
103    blender --background --python myscript.py
104
105
106 You might want to run this with a blend file so the script has some data to operate on.
107
108 .. code-block:: python
109
110    blender myscene.blend --background --python myscript.py
111
112
113 .. note::
114
115    Depending on you're setup you might have to enter the full path to the blender executable.
116
117
118 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.
119
120 * render the output to an image, use an image viewer and keep writing over the same image each time.
121
122 * save a new blend file, or export the file using one of blenders exporters.
123
124 * if the results can be displayed as text - print them or write them to a file.
125
126
127 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 you're text editor to see changes.
128
129
130 Use External Tools
131 ==================
132
133 When there are no readily available python modules to perform specific tasks its worth keeping in mind you may be able to have python execute an external command on you're data and read the result back in.
134
135 Using external programs adds an extra dependency and may limit who can use the script but to quickly setup you're own custom pipeline or writing one-off scripts this can be handy.
136
137 Examples include:
138
139 * Run The Gimp in batch mode to execute custom scripts for advanced image processing.
140
141 * Write out 3D models to use external mesh manipulation tools and read back in the results.
142
143 * Convert files into recognizable formats before reading.
144
145
146 Bundled Python & Extensions
147 ===========================
148
149 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 you're systems python wont be found by blender.
150
151 There are 2 ways around this:
152
153 * 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**.
154
155 * 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.
156
157
158 Drop Into a Python Interpreter in You're Script
159 ===============================================
160
161 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.
162
163 .. code-block:: python
164
165    import code
166    code.interact(locals=locals())
167
168
169 If you want to access both global and local variables do this...
170
171 .. code-block:: python
172
173    import code
174    namespace = globals().copy()
175    namespace.update(locals())
176    code.interact(locals=namespace)
177
178
179 The next example is an equivalent single line version of the script above which is easier to paste into you're code:
180
181 .. code-block:: python
182
183    __import__('code').interact(locals={k: v for ns in (globals(), locals()) for k, v in ns.items()})
184
185
186 `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.
187
188
189 Admittedly this highlights the lack of any python debugging support built into blender, but its still handy to know.
190
191 .. note::
192
193    This works in the game engine as well, it can be handy to inspect the state of a running game.
194
195
196 Advanced
197 ========
198
199
200 Blender as a module
201 -------------------
202
203 From a python perspective its nicer to have everything as an extension which lets the python script combine many components.
204
205 Advantages include:
206
207 * 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).
208
209 * editors/IDE's can auto complete blender modules & variables.
210
211 * existing scripts can import blender API's without having to run inside blender.
212
213
214 This is marked advanced because to run blender as a python module requires a special build option.
215
216 For instructions on building see `Building blender as a python module <http://wiki.blender.org/index.php/User:Ideasman42/BlenderAsPyModule>`_
217
218
219 Python Safety (Build Option)
220 ----------------------------
221
222 Since its possible to accessed data which has been removed (see Gotcha's), this can be a hard to track down the cause of crashes.
223
224 To raise python exceptions on accessing freed data (rather then crashing), enable the CMake build option WITH_PYTHON_SAFETY.
225
226 This enables data tracking which makes data access about 2x slower which is why the option is not enabled in release builds.
227