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()
orPreferenceManager.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.
- 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
- 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
- packagePreferenceRootLocation(packageName)¶
Returns the absolute path of the installed package preference root folder.
- packagePreferenceLocation(packageName)¶
Returns the installed package preference path by package name.
- Parameters
packageName – The install package name
- Type
- Raise
ValueError
- copyOriginalToRoot(root, force=False)¶
Method to copy the preference files and folders from each zoo repository into the default zoo_preference location
- 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
- Returns
first element is whether the root was copied, second element is the original root location
- Return type
- Raise
RootDoesntExistsError
- Raise
OSError
- Raise
RootDestinationAlreadyExistsError
- setRootLocation(root, destination)¶
Will only set the root location, without moving any of the files.
- 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.
- 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
- Returns
the settings value usually a standard python type. SettingObject or the value or ‘name’
- Return type
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
- 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 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
- defaultPreferencesPath()¶
- 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
- stylesheetSetting(key, theme=None)¶
Get one specific setting from a theme in the stylesheet.
- stylesheetSettingColour(key, theme=None)¶
Return colour setting from current theme
- 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
- 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
- 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
- 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
- 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
- defaultExportPluginPath()¶
Returns the default hive export plugin path.
We use the zootools assets/hive/exporters.
- Returns
The absolute hive Exporters folder path.
- Return type
- defaultBuildScriptPath()¶
- defaultNamingConfigPath()¶
- userComponentPaths(root=None)¶
Returns the user component folder paths for the user.
This doesn’t include the environment variables value.
- userBuildScriptPaths(root=None)¶
Returns the user build script folder paths for the user.
This doesn’t include the environment variables value.
- userBuildScripts(root=None)¶
Returns a list of build script ids which should always be used in rigs.
- userTemplatePaths(root=None)¶
Returns the user template folder paths for the user.
This doesn’t include the environment variables value.
- userTemplateSavePath(root=None)¶
Returns the component module paths for the user.
This doesn’t include the environment variables value.
- exporterPluginPaths(root=None)¶
Returns the list of exporter plugin path hive is current using in the preferences.
- exporterPluginOverrides(root=None)¶
Returns the exporter plugin id overrides done by the user.
- 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.
- setUserComponentPaths(paths, save=True)¶
Sets The user component paths for hive to search.
- setUserBuildScriptPaths(paths, save=True)¶
Sets The user build script paths for hive to search.
- setUserTemplatePaths(paths, save=True)¶
Sets The user template paths for hive to search.