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