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)

preference: zoo.preferences.core.PreferenceManager

pluginPath()