API Reference¶

Preference Manager¶

class PreferenceManager(configurationManager)¶

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 subdirectory of the preferences i.e. 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 instance
force (bool) – If True 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 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 instance
destination (str) – The absolute fullpath to the destination folder

Returns:

classmethod assetPath()¶

Asset Path

eg. ~/zoo_preferences/assets

Returns:

classmethod prefsPath()¶

Prefs Path

e.g. ~/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.core.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) – e.g. 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.core.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.core.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)¶

autoLoadPlugin()¶

Auto Load Plugin

Returns:
Return type:: bool

setAutoLoad(state)¶

pluginPath()¶

class ToolsetPreference(preference)¶

Bases: PreferenceInterface

id = 'toolsets_interface'¶

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