Utilities (bpy.utils)¶
This module contains utility functions specific to blender but not associated with blenders internal data.
-
bpy.utils.
blend_paths
(absolute=False, packed=False, local=False)¶ Returns a list of paths to external files referenced by the loaded .blend file.
- Parameters
absolute (boolean) – When true the paths returned are made absolute.
packed (boolean) – When true skip file paths for packed data.
local (boolean) – When true skip linked library paths.
- Returns
path list.
- Return type
list of strings
-
bpy.utils.
escape_identifier
(string)¶ Simple string escaping function used for animation paths.
- Parameters
string (string) – text
- Returns
The escaped string.
- Return type
string
-
bpy.utils.
unescape_identifier
(string)¶ Simple string un-escape function used for animation paths. This performs the reverse of escape_identifier.
- Parameters
string (string) – text
- Returns
The un-escaped string.
- Return type
string
-
bpy.utils.
register_class
(cls)¶ Register a subclass of a Blender type class.
- Parameters
cls (class) – Blender type class in:
bpy.types.Panel
,bpy.types.UIList
,bpy.types.Menu
,bpy.types.Header
,bpy.types.Operator
,bpy.types.KeyingSetInfo
,bpy.types.RenderEngine
- Raises
ValueError – if the class is not a subclass of a registerable blender class.
Note
If the class has a register class method it will be called before registration.
-
bpy.utils.
resource_path
(type, major=bpy.app.version[0], minor=bpy.app.version[1])¶ Return the base path for storing system files.
- Parameters
type (string) – string in [‘USER’, ‘LOCAL’, ‘SYSTEM’].
major (int) – major version, defaults to current.
minor (string) – minor version, defaults to current.
- Returns
the resource path (not necessarily existing).
- Return type
string
-
bpy.utils.
unregister_class
(cls)¶ Unload the Python class from blender.
If the class has an unregister class method it will be called before unregistering.
-
bpy.utils.
keyconfig_init
()¶
-
bpy.utils.
keyconfig_set
(filepath, report=None)¶
-
bpy.utils.
load_scripts
(reload_scripts=False, refresh_scripts=False)¶ Load scripts and run each modules register function.
- Parameters
reload_scripts (bool) – Causes all scripts to have their unregister method called before loading.
refresh_scripts (bool) – only load scripts which are not already loaded as modules.
-
bpy.utils.
modules_from_path
(path, loaded_modules)¶ Load all modules in a path and return them as a list.
- Parameters
path (string) – this path is scanned for scripts and packages.
loaded_modules (set) – already loaded module names, files matching these names will be ignored.
- Returns
all loaded modules.
- Return type
list
-
bpy.utils.
preset_find
(name, preset_path, display_name=False, ext='.py')¶
-
bpy.utils.
preset_paths
(subdir)¶ Returns a list of paths for a specific preset.
- Parameters
subdir (string) – preset subdirectory (must not be an absolute path).
- Returns
script paths.
- Return type
list
-
bpy.utils.
refresh_script_paths
()¶ Run this after creating new script paths to update sys.path
-
bpy.utils.
app_template_paths
(subdir=None)¶ Returns valid application template paths.
- Parameters
subdir (string) – Optional subdir.
- Returns
app template paths.
- Return type
generator
-
bpy.utils.
register_manual_map
(manual_hook)¶
-
bpy.utils.
unregister_manual_map
(manual_hook)¶
-
bpy.utils.
register_classes_factory
(classes)¶ Utility function to create register and unregister functions which simply registers and unregisters a sequence of classes.
-
bpy.utils.
register_submodule_factory
(module_name, submodule_names)¶ Utility function to create register and unregister functions which simply load submodules, calling their register & unregister functions.
Note
Modules are registered in the order given, unregistered in reverse order.
- Parameters
module_name (string) – The module name, typically
__name__
.submodule_names (list of strings) – List of submodule names to load and unload.
- Returns
register and unregister functions.
- Return type
tuple pair of functions
-
bpy.utils.
register_tool
(tool_cls, *, after=None, separator=False, group=False)¶ Register a tool in the toolbar.
- Parameters
tool (
bpy.types.WorkSpaceTool
subclass.) – A tool subclass.space_type (string) – Space type identifier.
after (collection of strings or None.) – Optional identifiers this tool will be added after.
separator (bool) – When true, add a separator before this tool.
group (bool) – When true, add a new nested group of tools.
-
bpy.utils.
make_rna_paths
(struct_name, prop_name, enum_name)¶ Create RNA “paths” from given names.
- Parameters
struct_name (string) – Name of a RNA struct (like e.g. “Scene”).
prop_name (string) – Name of a RNA struct’s property.
enum_name (string) – Name of a RNA enum identifier.
- Returns
A triple of three “RNA paths” (most_complete_path, “struct.prop”, “struct.prop:’enum’”). If no enum_name is given, the third element will always be void.
- Return type
tuple of strings
-
bpy.utils.
manual_map
()¶
-
bpy.utils.
script_path_user
()¶ returns the env var and falls back to home dir or None
-
bpy.utils.
script_path_pref
()¶ returns the user preference or None
-
bpy.utils.
script_paths
(subdir=None, user_pref=True, check_all=False, use_user=True)¶ Returns a list of valid script paths.
- Parameters
subdir (string) – Optional subdir.
user_pref (bool) – Include the user preference script path.
check_all (bool) – Include local, user and system paths rather just the paths blender uses.
- Returns
script paths.
- Return type
list
-
bpy.utils.
smpte_from_frame
(frame, fps=None, fps_base=None)¶ Returns an SMPTE formatted string from the frame:
HH:MM:SS:FF
.If fps and fps_base are not given the current scene is used.
- Parameters
frame (int or float.) – frame number.
- Returns
the frame string.
- Return type
string
-
bpy.utils.
smpte_from_seconds
(time, fps=None, fps_base=None)¶ Returns an SMPTE formatted string from the time:
HH:MM:SS:FF
.If fps and fps_base are not given the current scene is used.
- Parameters
time (int, float or
datetime.timedelta
.) – time in seconds.- Returns
the frame string.
- Return type
string
-
bpy.utils.
unregister_tool
(tool_cls)¶
-
bpy.utils.
user_resource
(resource_type, path='', create=False)¶ Return a user resource path (normally from the users home directory).
- Parameters
type (string) – Resource type in [‘DATAFILES’, ‘CONFIG’, ‘SCRIPTS’, ‘AUTOSAVE’].
subdir (string) – Optional subdirectory.
create (boolean) – Treat the path as a directory and create it if its not existing.
- Returns
a path.
- Return type
string
-
bpy.utils.
execfile
(filepath, mod=None)¶