API Reference

Preference Manager

class PreferenceManager

Bases: ToolSet

Preference Manager is responsible for discovery of preference folders/files and the management of said folders/files.

See :ref:preinterface.PreferenceInterface: to know about how to handle interfacing to installed package preferences. These should be used when accessing preference files as a client of zootools prefs.

These can be listed via PreferenceManager.interfaces() or PreferenceManager.Interface() to return a new instance.

pref = PreferenceManager()
# query the current root directories
pref.roots  # OrderedDict

# add a custom directory for the preferences, by default the user_preferences root is 
# already created but you can create another. Note: the order of the preferences
# root directories specified in pref.roots matters for priority searching
pref.addRoot("/MyCustomPrefererenceDirectory", root="custom_dir") # custom_dir is the root name

# optional feature to copy all default preference to a root location
pref.copyOriginalToRoot("custom_dir")

# find a .pref and load it from disk
# specifying the root will search and load the .pref relative to the root.
# specifying root=None will search each root until the .pref is found
obj = pref.findSetting("prefs/global/stylesheet", "user_preference")
# a SettingsObject is always returned so do the following to validate
if not obj.isValid(): print("handle invalid settings here")

# get the fullpath to the file, though you shouldn't rename or move the file
# since the preferences internally rely on the relative path, for this 
# reason there is no argument in the settingObject interface to rename.
obj.path()

# return the root Path object that it belongs too, remember the root
# can change depending on which root its save to. see below
obj.rootPath()
# return the root name
obj.root

# make some change
obj["settings"]["someSettings"] = {"name": "test"}

# save the change to disk in place.
obj.save()

# save it to a different location.
pref.createSetting(obj.relativePath, "custom_dir", obj)
DEFAULT_USER_PREFERENCE_NAME = 'user_preferences'
hasInterface(name)

Returns whether an interface with the “name” exists.

Parameters

name (str) – id variable on the interface class

Returns

True if exists in the registry

Return type

bool

interface(name)

Returns the interface object.

use the id * silky change

An Interface is a class that contains method to communicate with the preferences data structures. Interfaces are the preferred use over direct access to the data.

Parameters

name (str) – The interface class id

Return type

zoo.preferences.prefinterface.PreferenceInterface

interfaces()

Returns all currently available interfaces names

Return type

list(idStr)

iterPackagePreferenceRoots()

Generator function which returns the preferences root folder directly under each package directory.

This function should only be used for admin purposes and any modification under this root will not be maintained between package versions.

..code-block: python

for root in preference.iterPackagePreferenceRoots:

print(root) # packagePath/preferences

Returns

Generator function

Return type

Generator(str)

iterPackagePrefPath()

Generator Function which iterates over each installed package and returns the sub directory of the preferences ie. packagePath/preferences/prefs

Return type

str

packagePreferenceRootLocation(packageName)

Returns the absolute path of the installed package preference root folder.

Parameters

packageName (str) – The install package path

Raises
  • ValueError – [description]

  • ValueError – Raised when either the package doesn’t exist or the preferences folder doesn’t exist.

Returns

[description]

Return type

[type]

packagePreferenceLocation(packageName)

Returns the installed package preference path by package name.

Parameters

packageName – The install package name

Type

str

Raise

ValueError

copyOriginalToRoot(root, force=False)

Method to copy the preference files and folders from each zoo repository into the default zoo_preference location

Parameters
  • root (str) – The root name location which should be part of the this instance

  • force (bool) – If True then if the file exists at the root location it will be overridden.

moveRootLocation(root, destination)

Physically moves the give root location to the destination directory.

If the destination doesn’t exist it will be created.

Note

Using this function to move preferences requires a restart

Parameters
  • root (str) – The root name location which should be part of the this instance

  • destination (str) – The absolute fullpath to the destination folder

Returns

first element is whether the root was copied, second element is the original root location

Return type

(bool, str)

Raise

RootDoesntExistsError

Raise

OSError

Raise

RootDestinationAlreadyExistsError

setRootLocation(root, destination)

Will only set the root location, without moving any of the files.

Parameters
  • root (str) – The root name location which should be part of the this instance

  • destination (str) – The absolute fullpath to the destination folder

Returns

classmethod assetPath()

Asset Path

eg. ~/zoo_preferences/assets

Returns

classmethod prefsPath()

Prefs Path

eg. ~/zoo_preferences/prefs

Returns

classmethod defaultPreferencePath()

Zoo Preferences Path (zoo_preferences)

Retrieves the path to the Zoo Tools User Preferences, if ‘~/zoo_preferences’ then displays full path

Returns

defaultPreferenceSettings(packageName, relativePath)

Returns the default preferences for the package.

Parameters
  • packageName (str) – The package name currently in the environment.

  • relativePath (str) – The relative path from the preferences folder under the package root.

Returns

The SettingsObject for the preferences file or None

Return type

:zoo.libs.tooldata.tooldata.SettingsObject or None

findSetting(relativePath, root, name=None, extension=None)

Searches the roots for the relativePath and returns the settingObject or if ‘name’ is provided then the value of the key(name) will be returned.

Parameters
  • relativePath (str) – eg. interface/stylesheet

  • root – The root name to search, if None then all roots will be searched until the relativePath is found.

  • name (str) – the name to

Returns

the settings value usually a standard python type. SettingObject or the value or ‘name’

Return type

zoo.libs.tooldata.tooldata.SettingObject

Interface

class PreferenceInterface(preference)

Bases: object

Preference interface class which is responsible for interfacing to .pref files within zoo.

PreferenceInterface shouldn’t be instanced directly but through zoo.preferences.core.PreferenceManager instance.

It’s the intention for interface subclasses to handle creating and manipulating one or more .pref belonging to the installed zoo package. As a general rule of thumb the interface shouldn’t manipulate a .pref outside it’s own package but can request it from the external interface via self.preference.interface() method however do this at your own risk.

The .pref internal data structure may change over the life of zootools so it is recommended that the interface provides the necessary methods to handle manipulating the data structure over the client directly making the changes.

See preference.interface.preference_interface.ZooToolsPreference for example usage.

id = ''
settings(relativePath=None, root=None, name=None, refresh=False)
Parameters
  • relativePath (str) – eg. interface/stylesheet

  • root – The root name to search, if None then all roots will be searched until the relativePath is found.

  • name (str or None) – The key within the nested “settings” dict within the file.

  • refresh (bool) – Whether or not to re-cache the queried settings back on this interface instance.

Returns

the settings value usually a standard python type

Return type

zoo.libs.tooldata.tooldata.SettingObject

refreshSettings()

Refreshes the settings

Returns

saveSettings(indent=True, sort=False)

Save the settings

Parameters
  • indent – Add indent to the json file that will be saved

  • sort – Sort the json file alphabetically

Returns

settingsValid()

Returns true if setting is valid. False otherwise

refresh()

Force a refresh

Returns

Return type

revertSettings()

Revert the settings back to the previous settings

Returns

Custom Interfaces

class GeneralPreferences(preference)

Bases: PreferenceInterface

id = 'general_interface'
primaryRenderer()

Primary Renderer

Returns

Return type

basestring

setPrimaryRenderer(renderer)
class UpdateThemeEvent(stylesheet, themeDict, preference)

Bases: object

class ZooToolsPreference(preference)

Bases: PreferenceInterface

class ThemeUpdater(*args: Any, **kwargs: Any)

Bases: QObject

Sends a signal when the theme is set. Allows widget-specific theme changes

update

alias of UpdateThemeEvent

id = 'core_interface'
property themeUpdated

Emits the theme and dictionary

Returns

(theme, themeDict)

Return type

emitUpdateSignal(styleSheet, themeDict)

Do a manual update for the widgets that require it

Parameters
  • styleSheet

  • themeDict (preferences.interface.themedict.ThemeDict) –

Returns

Return type

currentTheme()

Returns the current theme name for zootools.

Returns

The style sheet theme name

Return type

str

defaultPreferencesPath()
themes()

Returns the themes as a list

Returns

The style sheet theme name

Return type

str

forceRefresh()

Force a refresh

Returns

Return type

stylesheet(theme=None)

Loads and returns the stylesheet string

Parameters

theme (basestring) – Themes name

Returns

The final composed stylesheet

Return type

zoo.libs.pyqt.stylesheet.StyleSheet

stylesheetSetting(key, theme=None)

Get one specific setting from a theme in the stylesheet.

Parameters
  • key (str) – A key from the theme eg “$BTN_BACKGROUND_COLOR”

  • theme (str or None) – Leave none to use default

Returns

The key value

Return type

str or tuple

stylesheetSettingColour(key, theme=None)

Return colour setting from current theme

Parameters
  • key – Get key eg ‘$EMBED_WINDOW_BORDER_COL’

  • theme – from theme

Returns

Tuple(r,g,b)

Return type

tuple(float,float,float)

revertThemeToDefault(theme=None, save=True)

Reverts current theme to default

Returns

Return type

stylesheetForTheme(theme)

Return stylesheet from theme.

Parameters

theme (str) – theme eg “dark” or “maya-toolkit”

Return type

zoo.libs.pyqt.stylesheet.StyleSheet

themeDict(theme)

Retrieve the theme dict found in the stylesheet.pref for the corresponding theme

The return usually looks like the following:

themeDict = {
                '$BROWSER_BG_COLOR': '1A1A1A',
                '$BROWSER_BG_SELECTED_COLOR': '5E5E5E',
                ...
            }
Parameters

theme

Returns

Return type

dict

stylesheetFromData(data)

Generate stylesheet from data.

Data is the dict usually from stylesheet.pref under one of the themes:

{
    "$EMBED_WINDOW_BG": "2a2a2a",
    "$EMBED_WINDOW_BORDER_COL": "3c3c3c",
    "$DEBUG_1": "ff0000",
    "$DEBUG_2": "0012ff",
    "$TEAROFF_LINES": "AAAAAA"
}
Parameters

data (dict) – Data is the dict usually from stylesheet.pref under one of the themes

Returns

zoo.libs.pyqt.stylesheet.StyleSheet

bakePreferenceRoots()

Bake Preference Roots Bakes the Preferences root paths and names to zootoolspro/config/env/preferences_root.config

defaultPreferencePath()
prefsPath()
assetPath()
assetFolder(folder='')

Returns the default folder paths as created from the global user preferences directory

Example:

assetFolder("model_assets")
# Output: userPath/zoo_preferences/assets/model_assets
Parameters

folder (str) – The folder to get within the asset path

Returns

The full path of the userPreferences + assets directory + model assets directory

Return type

str

userPreferences()

Get user preferences

Retrieves the path to the Zoo Tools User Preferences, if ‘~/zoo_preferences’ then displays full path

Returns

class ToolsetPreference(preference)

Bases: PreferenceInterface

id = 'toolsets_interface'
class MayaPreference(preference)

Bases: PreferenceInterface

id = 'maya_interface'
settings()

Returns the data of the user preferences JSON for the zoo_light_suite

class HiveInterface(preference)

Bases: PreferenceInterface

Preference interface class for hive

id = 'Hive'
upgradePreferences()

Upgrades the local preferences from the default preferences.

upgradeAssets()
defaultUserTemplatePath()

Returns the default hive template path for saving.

We use the zootools assets/hive/templates path.

Returns

The absolute hive template path

Return type

str

defaultExportPluginPath()

Returns the default hive export plugin path.

We use the zootools assets/hive/exporters.

Returns

The absolute hive Exporters folder path.

Return type

str

defaultBuildScriptPath()
defaultNamingConfigPath()
userComponentPaths(root=None)

Returns the user component folder paths for the user.

This doesn’t include the environment variables value.

Parameters

root (str) – The root name to search, if None then all roots will be searched until the relativePath is found.

Returns

A list of folder paths.

Return type

list[str]

userBuildScriptPaths(root=None)

Returns the user build script folder paths for the user.

This doesn’t include the environment variables value.

Parameters

root (str) – The root name to search, if None then all roots will be searched until the relativePath is found.

Returns

A list of folder paths.

Return type

list[str]

userBuildScripts(root=None)

Returns a list of build script ids which should always be used in rigs.

Parameters

root (str) – The root name to search, if None then all roots will be searched until the relativePath is found.

Returns

The build script plugin ids.

Return type

list[str]

userTemplatePaths(root=None)

Returns the user template folder paths for the user.

This doesn’t include the environment variables value.

Parameters

root (str) – The root name to search, if None then all roots will be searched until the relativePath is found.

Returns

A list of folder paths.

Return type

list[str]

userTemplateSavePath(root=None)

Returns the component module paths for the user.

This doesn’t include the environment variables value.

Parameters

root (str) – The root name to search, if None then all roots will be searched until the relativePath is found.

Returns

The root folder path for saving templates

Return type

str

exporterPluginPaths(root=None)

Returns the list of exporter plugin path hive is current using in the preferences.

Parameters

root (str) – The root name to search, if None then all roots will be searched until the relativePath is found.

Return type

list[str]

exporterPluginOverrides(root=None)

Returns the exporter plugin id overrides done by the user.

Parameters

root (str or None) – The root name to search, if None then all roots will be searched until the relativePath is found.

Returns

The Mapping key is the exporter plugin id and the value is the remapped plugin id to use.

Return type

dict[str,str]

namingPresetPaths(root=None)
namingPresetHierarchy(root=None)
namingPresetSavePath(root=None)
setNamingPresetHierarchy(hierarchy, save=True)
setNamingPresetPaths(paths, save=True)
setNamingPresetSavePath(path, save=True)
setUserBuildScripts(scriptIds, save=True)

Sets which build script plugins to use by default.

Parameters
  • scriptIds (list[str]) – The build script plugin ids to always use by default for every rig.

  • save (bool) – Whether or not this change should immediately be save to disk.

setUserComponentPaths(paths, save=True)

Sets The user component paths for hive to search.

Parameters
  • paths (list[str]) – The list a folder paths

  • save (bool) – Save the paths to disk, default to True

setUserBuildScriptPaths(paths, save=True)

Sets The user build script paths for hive to search.

Parameters
  • paths (list[str]) – The list a folder paths

  • save (bool) – Save the paths to disk, default to True

setUserTemplatePaths(paths, save=True)

Sets The user template paths for hive to search.

Parameters
  • paths (list[str]) – The list a folder paths

  • save (bool) – Save the paths to disk, default to True

setUserTemplateSavePath(path, save=True)

Sets The user template Save path.

Parameters
  • path (str) – The absolute folder path where new templates will be saved.

  • save (bool) – Save the path to disk, default to True