schrodinger.utils.preferences module¶

A module to make the interface to the mmpref library more Pythonic. It contains a single class that can be created once and then used to access preference data.

This class also provides data type-free .get(), .set() and .getAllPreferences() methods.

Simple script usage might look like this:

import preferences

# Initialize the preference handler
pref_handler = preferences.Preferences(preferences.SCRIPTS)

# Store and get all preferences from a group specific to this script
pref_handler.beginGroup('my_script')

# Set the preference 'hosts' to 5
pref_handler.set('hosts', 5)

# Get the value of the hosts preference
num_hosts = pref_handler.get('hosts', default=8)

# Get the value of the jobname preference, with myjob as the default
# name if no preference is set
jobname = pref_handler.get('jobname', default='myjob')

Slightly more complex script usage using groups might look like this:

import preferences

# Initialize the preference handler
pref_handler = preferences.Preferences(preferences.SCRIPTS)

# Store and get all preferences from a group specific to this script
pref_handler.beginGroup('my_script')

# Set the preference 'hosts' to 5
pref_handler.set('hosts', 5)

# Switch to the group 'my_script/dialogs'
pref_handler.beginGroup('dialogs')
# Set the value of the 'my_script/dialogs/import_directory preference
pref_handler.set('import_directory', directory)

# Reset the current group to the 'my_script' group
pref_handler.resetGroup(retain=1)

# Get the value of the hosts preference
num_hosts = pref_handler.get('hosts', default=8)

# Change the value of the 'my_script/dialogs/import_directory' preference
pref_handler.set('dialogs/import_directory', directory2)

# Switch to the group 'my_script/dialogs'
pref_handler.beginGroup('dialogs')

# Get the import directory
imdir = pref_handler.get('import_directory')

class schrodinger.utils.preferences.Preferences(product)¶

Bases: object

A class that allows Pythonic access to the mmpref library.

__init__(product)¶

Create a new Preferences object

Parameters

product (constant) – A product name constant supplied in this module or one from the pymmlibs module.

Raises

ValueError – If product is not a recognized constant
IOError – If the preferences file is inaccessible.
IOError – If the preferences file is inaccessible.
RuntimeError – If another error is encountered.

Constants supplied in this module:

CANVAS
COMBIGLIDE
DESMOND
EPIK
IMPACT
JAGUAR
KNIME
MACROMODEL
MAESTRO
PHASE
PSP
PYMOL
QIKPROP
SCRIPTS
SHARED
WATERMAP

sync()¶: Sync the settings to file and reload settings modified by other threads/process.

clear()¶: This will clear all preferences associated with this handle.

getKeyType(key)¶

Gets the type of data stored for this key.

Parameters: key (str) – key or group to remove
Return type: constant
Returns: A constant indicating the data type stored for this key. Valid constants are INT, STRING, FLOAT, BOOL.

If the key is not found, None is returned.

remove(key, key_type=None)¶

Remove the key or group and its values.

To remove a group and its associated keys, set type to NO_TYPE.

If a group is set using beginGroup, the search will happen within the group.

Parameters

key (str) – key or group to remove
key_type (constant) – A constant indicating the data type of this key or if it is a group. If not given, an attempt will be made to remove key if it is found as a key and if not it will be treated as a group. Valid constants are (INT, STRING, FLOAT, BOOL, NO_TYPE (groups))

Return type

int

Returns

The number of keys removed

Raises

ValueError – If key_type is not a recognized type

contains(key, key_type=None)¶

Check for the presence of key.

Check if the given key is available matching the give datatype.

If beginGroup is called before this function, the given key will be searched for relative to the group.

Keys specific to the running platform and non-platform specific keys attribute will be considered in the search.

Parameters

key (str) – key to search for
key_type (constant) – A constant indicating the data type of this key. If not given, an attempt will be made to find a key of any data type. Valid key_type are: (INT, STRING, FLOAT, BOOL).

Return type

bool

Returns

True if the key is found, False if not

Raises

ValueError – If key_type is not a valid type

beginGroup(group, toplevel=False)¶

Indicate the group for future key searches by appending group to the current group path. This group will be used for future group/key searches until endGroup is called. This is useful to avoid typing the common path again and again to query sets of keys.

A product’s keys can be grouped together under various paths. For instance, the SCRIPT product may have a PoseExplorer group, and that group may have Paths and Dialogs subgroups. One could access the ‘import’ key under the PoseExplorer/Paths group via:

handler = Preferences(SCRIPTS)
handler.beginGroup('PoseExplorer')
handler.beginGroup('Paths')
import_dir = handler.get('import')

or:

handler = PreferenceHandler(SCRIPTS)
handler.beginGroup('PoseExplorer/Paths')
import_dir = handler.get('import')

or:

handler = Preferences(SCRIPTS)
import_dir = handler.get('PoseExplorer/Paths/import')

Parameters

group (str) – the group to append to the current group path
toplevel (bool) – If True, treat this group as a toplevel group - i.e. the group path will simply be ‘group’ after this. If False (default), this group should be appended to the current group path.

Raises

ValueError – if key contain invalid character
MmException – otherwise

getGroup()¶

Get the current group set via the beginGroup method.

Return type: str
Returns: The current group, or “” if no group is set

endGroup()¶: Remove the current group set via the beginGroup method from the group search path. The new group path will be the same as it was before the last invocation of beginGroup.

changeGroup(group, toplevel=False)¶

Indicate the group to use for key searches by appending group to the current group path.

Parameters

group (str) – the group to append to the current group path
toplevel (bool) – If True, treat this group as a toplevel group - i.e. the group path will simply be ‘group’ after this. If False (default), this group should be appended to the current group path.

resetGroup(retain=0)¶

Unset the group path so that searches begin at the top level for the product.

Parameters: retain (int) – The number of groups in the path to retain below the top level. For instance, if the current group is a/b/c/d, self.resetGroup(retain=1) would set the current group to a.

set(key: str, value: Union[int, bool, float, str], os_specific: bool = False)¶

Set the value of key. Note that the underlying library stores keys in a type specific way, but this function and the get function abstract that away.

If key does not exist, it is created.

If the group path has been set via beginGroup, it is honored.

Parameters

key – The key to set the value for. Can be a key name or a group path/key name.
value – The value to set key to
os_specific – Adds the key with os specific attribute if set to True. This ties the key to the platform it is invoked.

Raises

ValueError – if key contain invalid character
TypeError – if type of existing key is being changed
MmException – otherwise

get(key, default=<object object>)¶

Get the value of key. Note that the underlying library stores keys in a type specific way, but this function and the set function abstract that away.

If key does not exist, the value of the default argument is returned if it is given. If the key does not exist and default is not given, a KeyError is raised.

If the group path has been set via beginGroup, it is honored.

If the OS has been set via beginOS, it is honored. OS-specific key values get higher preference when searching for keys.

The user-specific preference file is checked for the key first, then the default installation files are checked.

Parameters: key (str) – The key to get the value for. Can be a key name or a group path/key name.
Raises: KeyError – If the key is not found and default is not given

getAllPreferences(group='')¶

Get a dictionary of all preferences in the current group path. The dictionary keys will be preference names and the dictionary values will be preference values. Note that preference names will include the relative group path starting at the current group.

If the OS has been set via beginOS, it is honored. OS-specific key values get higher preference when searching for keys.

Parameters: group (str) – Append this group path to the current group path before searching for keys. Note that this persists during this operation only, after returning the dictionary the group path returns to its previous value.
Return type: dict
Returns: dictionary of preferences with preference names as keys and preference values as values.

schrodinger.utils.preferences.get_preference(key, group, product=13, default=<object object>)¶

Get the value of key in the specified group under product. See documentation for Preferences.get for more information.

Parameters

key (str) – The key to get the value for. Can be a key name or a group path/key name.
group (str) – the group path to append to the product
product (constant) – A product name constant supplied in this module or one from the pymmlibs module.
default (any) – The default value to return if the key does not exist.

Return type

bool, int, float, str, or default

Returns

The value for the key.

Raises

KeyError – If the key is not found and default is not given

schrodinger.utils.preferences.set_preference(key, group, value, product=13)¶

Set the value of key in the specified group under product. See documentation for Preferences.set for more information.

Parameters

key (str) – The key to set the value for. Can be a key name or a group path/key name.
group (str) – the group path to append to the product
value (bool, int, float, or str) – The value to set key to
product (constant) – A product name constant supplied in this module or one from the pymmlibs module.