3
3
# The module files in this folder are used to create the API documentation.
4
4
# Doc system used: epydoc - http://epydoc.sf.net
7
# epydoc -o BPY_API_230 --url "http://www.blender.org" -t Blender.py \
5
# pseudo command line (check the epy_docgen.sh file):
6
# epydoc -o BPY_API_23x --url "http://www.blender.org" -t Blender.py \
8
7
# -n "Blender" --no-private --no-frames Blender.py \
9
# Types.py Scene.py Object.py NMesh.py Material.py Camera.py Lamp.py \
10
# Armature.py Metaball.py Effect.py Curve.py Ipo.py World.py BGL.py Window.py \
11
# Draw.py Image.py Text.py Lattice.py Texture.py Registry.py Sys.py Mathutils.py
8
# Types.py Scene.py Object.py [ ... etc]
14
11
The main Blender module.
16
The Blender Python API Reference
17
================================
49
- L{sys<Sys>} (added time function)
54
This Reference documents the Blender Python API, a growing collection of
55
Python modules (libs) that give access to part of the program's internal data
58
Through scripting, Blender can be extended in realtime. Possibilities range
59
from simple functionality to importers / exporters and even more complex
60
"applications". Blender scripts are written in
61
U{Python <www.python.org>}, an impressive high level, multi-paradigm,
64
@author: The Blender Python Team
65
@requires: Blender 2.33 or newer.
67
@see: U{www.blender.org<http://www.blender.org>}
68
@see: U{projects.blender.org<http://projects.blender.org>}
69
@see: U{www.python.org<http://www.python.org>}
70
@see: U{www.python.org/doc<http://www.python.org/doc>}
13
B{New}: L{Run}, L{UpdateMenus}, new options to L{Get}, L{ShowHelp},
14
L{SpaceHandlers} dictionary.
20
@var bylink: True if the current script is being executed as a script link.
21
@type link: Blender Object or None; integer (space handlers)
22
@var link: for normal script links, 'link' points to the linked Object (can be
23
a scene, object (mesh, camera, lamp), material or
24
world). For space handler script links, 'link' is an integer from the
25
Blender.L{SpaceHandlers} dictionary. For script not running as script
26
links, 'link' is None.
27
@type event: string or int
28
@var event: this has three possible uses: script link type or events callback
30
- for normal script links it is a string representing the link type
31
(OnLoad, FrameChanged, Redraw, etc.).
32
- for EVENT space handler script links it is the passed event.
33
- for normal L{GUI<Draw.Register>} scripts I{during the events callback},
34
it holds the ascii value of the current event, if it is a valid one.
35
Users interested in this should also check the builtin 'ord' and 'chr'
38
@var mode: Blender's current mode:
39
- 'interactive': normal mode, with an open window answering to user input;
40
- 'background': Blender was started as 'C{blender -b <blender file>}' and
41
will exit as soon as it finishes rendering or executing a script
42
(ex: 'C{blender -b <blender file> -P <script>}'). Try 'C{blender -h}'
43
for more detailed informations.
44
@type SpaceHandlers: constant dictionary
45
@var SpaceHandlers: dictionary with space handler types.
73
50
def Set (request, data):
85
62
Retrieve settings from Blender.
86
63
@type request: string
87
64
@param request: The setting data to be returned:
88
- 'curframe': the current animation frame
89
- 'curtime' : the current animation time
90
- 'staframe': the start frame of the animation
91
- 'endframe': the end frame of the animation
92
- 'filename': the name of the last file read or written
93
- 'version' : the Blender version number
94
@return: The requested data.
65
- 'curframe': the current animation frame.
66
- 'curtime' : the current animation time.
67
- 'staframe': the start frame of the animation.
68
- 'endframe': the end frame of the animation.
69
- 'filename': the name of the last file read or written.
70
- 'homedir': Blender's home dir.
71
- 'datadir' : the path to the dir where scripts should store and
72
retrieve their data files, including saved configuration (can
73
be None, if not found).
74
- 'udatadir': the path to the user defined data dir. This may not be
75
available (is None if not found), but users that define uscriptsdir
76
have a place for their own scripts and script data that won't be
77
erased when a new version of Blender is installed. For this reason
78
we recommend scripts check this dir first and use it, if available.
79
- 'scriptsdir': the path to the main dir where scripts are stored.
80
- 'uscriptsdir': the path to the user defined dir for scripts. (*)
81
- 'yfexportdir': the path to the user defined dir for yafray export. (*)
82
- 'fontsdir': the path to the user defined dir for fonts. (*)
83
- 'texturesdir': the path to the user defined dir for textures. (*)
84
- 'texpluginsdir': the path to the user defined dir for texture plugins. (*)
85
- 'seqpluginsdir': the path to the user defined dir for sequence plugins. (*)
86
- 'renderdir': the path to the user defined dir for render output. (*)
87
- 'soundsdir': the path to the user defined dir for sound files. (*)
88
- 'tempdir': the path to the user defined dir for storage of Blender
90
- 'version' : the Blender version number.
91
@note: (*) these can be set in Blender at the User Preferences window -> File
93
@warn: this function returns None for requested dir paths that have not been
94
set or do not exist in the user's file system.
95
@return: The requested data or None if not found.
99
100
Redraw all 3D windows.
102
def ReleaseGlobalDict (bool = None):
104
@depreciated: this function doesn't work anymore and will be removed.
105
Look at the L{Registry} submodule for a better alternative.
103
def Load (filename = None):
105
Load a Blender .blend file or any of the other supported file formats.
110
- Open Inventor 1.0 ASCII;
116
@type filename: string
117
@param filename: the pathname to the desired file. If 'filename'
118
isn't given or if it contains the substring '.B.blend', the default
119
.B.blend file is loaded.
121
@warn: loading a new .blend file removes the current data in Blender. For
122
safety, this function saves the current data as an autosave file in
123
the temporary dir used by Blender before loading a new Blender file.
124
@warn: after a call to Load(blendfile), current data in Blender is lost,
125
including the Python dictionaries. Any posterior references in the
126
script to previously defined data will generate a NameError. So it's
127
better to put Blender.Load as the last executed command in the script,
128
when this function is used to open .blend files.
129
@warn: if in edit mode, this function leaves it, since Blender itself
133
def Save (filename, overwrite = 0):
135
Save a Blender .blend file with the current program data or export to
136
one of the builtin file formats.
145
@type filename: string
146
@param filename: the filename for the file to be written. It must have one
147
of the supported extensions or an error will be returned.
148
@type overwrite: int (bool)
149
@param overwrite: if non-zero, file 'filename' will be overwritten if it
150
already exists (can be checked with L{Blender.sys.exists<Sys.exists>}.
151
By default existing files are not overwritten (an error is returned).
153
@note: The substring ".B.blend" is not accepted inside 'filename'.
154
@note: DXF, STL and Videoscape export only B{selected} meshes.
159
Execute the given script.
161
@param script: the name of an available Blender Text (use L{Text.Get}() to
162
get a complete list) or the full pathname to a Python script file in the
164
@note: the script is executed in its own context -- with its own global
165
dictionary -- as if it had been executed from the Text Editor or chosen
169
def ShowHelp (script):
171
Show help for the given script. This is a time-saver ("code-saver") for
172
scripts that need to feature a 'help' button in their GUI's or a 'help'
173
submenu option. With proper documentation strings, calling this function is
174
enough to present a screen with help information plus link and email buttons.
176
@param script: the filename of a registered Python script.
177
@note: this function uses L{Run} and the "Scripts Help Browser" script. This
178
means that it expects proper doc strings in the script to be able to show
179
help for it (otherwise it offers to load the script source code as text).
180
The necessary information about doc strings is in the
181
L{Intro page<API_intro>} of this API Reference documentation you're
183
@note: 'script' doesn't need to be a full path name: "filename.py" is enough.
184
Note, though, that this function only works for properly registered
185
scripts (those that appear in menus).
190
Update the menus that list registered scripts. This will scan the default
191
and user defined (if available) folder(s) for scripts that have registration
192
data and will make them accessible via menus.
193
@note: only scripts that save other new scripts in the default or user
194
defined folders need to call this function.
199
Exit from Blender immediately.
200
@warn: the use of this function should obviously be avoided, it is available
201
because there are some cases where it can be useful, like in automated
202
tests. For safety, a "quit.blend" file is saved (normal Blender behavior
203
upon exiting) when this function is called, so the data in Blender isn't
added
removed
source/blender/python/api2_2x/doc/Blender.py
