fix for doc building after pepper merge, also WIP tips/tricks.
[blender.git] / doc / python_api / rst / info_tips_and_tricks.rst
1 ***************
2 Tips and Tricks
3 ***************
4
5 Some of these are just python features that scripters may not have thaught to use with blender.
6
7
8 Use The Terminal
9 ================
10
11 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.
12
13 There are 3 main uses for the terminal, these are:
14
15 * You can see the output of `print()` as you're script runs, which is useful to view debug info.
16
17 * The error tracebacks are printed in full to the terminal which wont always generate an error popup in blenders user interface (depending on how the script is executed).
18
19 * If the script runs for too long or you accidentally enter an infinate loop, Ctrl+C in the terminal (Ctrl+Break on Windows) will quit the script early.
20
21 .. note::
22    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.
23
24
25 Run External Scripts
26 ====================
27
28 Blenders text editor is fine for edits and writing small tests but it is not a full featured editor so for larger projects you'll probably want to use an external editor.
29
30 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.
31
32
33 Executing External Scripts
34 ^^^^^^^^^^^^^^^^^^^^^^^^^^
35
36 This is the equivilent to running the script directly, referencing a scripts path from a 2 line textblock.
37
38 .. code-block::
39
40    filename = "/full/path/to/myscript.py"
41    exec(compile(open(filename).read(), filename, 'exec'))
42
43
44 You might also want to reference the file relative to the blend file.
45
46 .. code-block::
47
48    filename = "/full/path/to/script.py"
49    exec(compile(open(filename).read(), filename, 'exec'))
50
51
52 You might want to reference a script thats at the same location as the blend file.
53
54 .. code-block::
55
56    import bpy
57    import os
58
59    filename = os.path.join(os.path.basename(bpy.data.filepath), "myscript.py")
60    exec(compile(open(filename).read(), filename, 'exec'))
61
62
63 Executing Modules
64 ^^^^^^^^^^^^^^^^^
65
66 This example shows loading a script in as a module and executing a module function.
67
68 .. code-block::
69
70    import myscript
71    import imp
72
73    imp.reload(myscript)
74    myscript.main()
75
76
77 Notice that the script is reloaded every time, this forces an update, normally the module stays cached in `sys.modules`.
78
79 The main 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 argumnents to the function from this small script which is often useful for testing differnt settings quickly.
80
81 The other issue with this is the script has to be in pythons module search path.
82 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.
83
84 .. code-block::
85
86    import sys
87    import os
88    impory bpy
89
90    blend_dir = os.path.basename(bpy.data.filepath)
91    if blend_dir not in sys.path:
92       sys.path.append(blend_dir)
93
94    import myscript
95    import imp
96    imp.reload(myscript)
97    myscript.main()
98
99
100 Don't Use Blender!
101 ==================
102
103
104 Use External Tools
105 ==================
106
107
108 Bundled Python
109 ==============
110
111 Blender from blender.org includes a compleate 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.
112
113 There are 2 ways around this:
114
115 * remove blender python subdirectory, blender will then look for the systems python and use that instead **python version must match the one that blender comes with**.
116
117 * copy the extensions into blender's python subdirectry so blender can access them, you could also copy the entire python installation into blenders subdirectory, replacing the one blender comes with. This works as long as the python versions match and the paths are created in the same location 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.
118
119
120 Advanced
121 ========
122
123
124 Blender as a module
125 -------------------
126
127
128 Python Safety (Build Option)
129 ----------------------------
130
131
132 CTypes in Blender
133 -----------------