Class Preferences

Create a new Preferences object

Parameters:

• product (constant) - A product name constant supplied in this module or one from the pymmlibs module. Constants supplied in this module:
  • CANVAS
  • COMBIGLIDE
  • DESMOND
  • EPIK
  • IMPACT
  • JAGUAR
  • KNIME
  • MACROMODEL
  • MAESTRO
  • MCPRO
  • PHASE
  • PSP
  • PYMOL
  • QIKPROP
  • SCRIPTS
  • SHARED
  • WATERMAP

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.

Overrides: object.__init__

Gets the type of data stored for this key.

Parameters:

• key (str) - key or group to remove

Returns: constant

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 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. If a comment is set for the key, it will be removed automatically. The key matching the running platform is given higher preference over the general one.

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)

Returns: int

The number of keys removed

Raises:

• ValueError - If key_type is not a recognized type

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. Note that the platform searched for the key is the running platform and not the platform set by beginOS.

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 values are
  • INT
  • STRING
  • FLOAT
  • BOOL

Returns: bool

True if the key is found, False if not

Raises:

• ValueError - If key_type is not a valid type

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

Get the current group set via the beginGroup method.

Returns: str

The current group, or "" if no group is set

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.

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 the OS. Future set() and set_x() commands will set OS-specific values for keys. Without calling this method, set() and set_x() will set non-OS-specific values.

Keys specific to the running platform get higher preference in get functions.

To stop setting platform specific key(s), use endOS.

Parameters:

• platform (constant) - One of the OS constants. By default, the running platform is used.
  • WINDOWS
  • LINUX
  • DARWIN
  • NO_OS (non-OS specific, same as using endOS

Raises:

• ValueError - If platform is not a valid type

Unset the OS. Future set() and set_x() commands will set non-OS-specific values for keys.

Keys specific to the running platform get higher preference in get functions.

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.

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

Parameters:

• key (str) - The key to set the value for. Can be a key name or a group path/key name.
• value (bool, int, float, or str) - The value to set key to

Raises:

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

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

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.

Returns: dict

dictionary of preferences with preference names as keys and preference values as values.

Set a comment for the given key.

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.

Parameters:

• key (str) - The key to set the value for. Can be a key name or a group path/key name.
• comment (str) - The commment for the key
• 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 values are
  • INT
  • STRING
  • FLOAT
  • BOOL

Raises:

• KeyError - If key is not found
• Exception - Unknown error condition