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.register_class(cls)

Register a subclass of a blender type in (bpy.types.Panel, bpy.types.UIList, bpy.types.Menu, bpy.types.Header, bpy.types.Operator, bpy.types.KeyingSetInfo, bpy.types.RenderEngine).

If the class has a register class method it will be called before registration.

Note

ValueError exception is raised if the class is not a subclass of a registerable blender class.

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_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_module(module, verbose=False)
bpy.utils.register_manual_map(manual_hook)
bpy.utils.unregister_manual_map(manual_hook)
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.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)

Returns an SMPTE formatted string from the time: HH:MM:SS:FF.

If the fps is 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_module(module, verbose=False)
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