# Utilities (bpy.utils)

This module contains utility functions specific to blender but not associated with blenders internal data.

- bpy.utils submodule (bpy.utils.previews)
- bpy.utils submodule (bpy.utils.units)

`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_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)