schrodinger.models.mappers module

This module contains machinery for synchronizing models with various objects. Various terms used in this module are defined here.

param: a data element of the type schrodinger.models.parameters.Param. Params can be ints, bools, strings, etc., or more complex compound params that are themselves composed of multiple params. There are two types of param references: Abstract params and value params.

Abstract param: a param reference where the top level object is a class. For example, MyModelClass.atom.coord would be an abstract param reference. As the name suggests, the abstract param has no specific value, but is just a reference to the kind of parameter.

Value param: a param reference where the top level object is an instance. For example, my_model_object.atom.coord would a value param. The value param has a distinct value.

model: an object with one or more params, each representing some data elements of the model. The model can by synchronized to a target object via a mapper.

target: a target is any object that we want to keep in sync with a model param. Targets are generally GUI widgets like spinboxes or line edits, but can be a variety of other things, such as a specific signal we want a model param to listen to, or a pair of setter/getter functions to sync to a model param’s value. A target could also be something like a command line argument, such that each command line argument corresponds to a different param in a model.

access: a particular way of interacting with a target. A target can have one or more accesses - a setter, a getter, or a signal.

default access: certain target types will have default accesses defined in this module. The default accesses for QLineEdit, for example, are: QLineEdit.text as the getter, QLineEdit.setText as the setter, and QLineEdit.textChanged as the signal.

mapper: a manager object that is responsible for model/target synchronization.

mapping: a defined association between a target object and a model param. Note that the mapping is always between a specific target instance (for example a checkbox instance), and a model class param (ex. MyModel.myboolparam, where MyModel is the class). By making the association with the model’s class rather than a model instance, the mapper is able to switch between different instances of the same model. Consider, for example:

A model class Person, with params name and age
A GUI panel with panel.name_le and panel.age_sb
Mappings:
    panel.name_le -> Person.name
    panel.age_sb -> Person.age
Model instances amy, bob, and charlie

We can now user mapper.setModel to switch between model instances, and the GUI state will change accordingly.

class schrodinger.models.mappers.AbstractParamMapper(auto_update_target=False)

Bases: PyQt5.QtCore.QObject

A param mapper manages synchronization between target objects that represent various params and a model object that contains those params.

addMapping(target_obj, param)

Maps a target object to an abstract param. An abstract param is a param that is owned at the top level by the model’s class rather than an instance of the model. This allows the same mapping to be used on multiple model instances.

The details of the target object are left to derived mapper classes.

Notes:

If a target is already mapped to a param, the old mapping will be replaced by the new one.

A target may be mapped to only one param. However, multple targets may be mapped to the same param. This is useful when a the same param is associated with mutliple targets (e.g. multiple views on a single data model).

Parameters:

• param (parameters.Param) – an abstract param (ex. Atom.coord.x)
• target_obj (any object which can be operated on by AbstractParamMapper._getTargetValue and AbstractParamMapper._setTargetValue.) – the target object mapped to a parameter.

getSignalsAndSlots(model)

Given a model object, return all signals and slots that need to be connected to support auto updating. Override this method in subclasses.

Returns:a list of 2-tuples where each tuple is a signal, slot pair

model()

modelClass()

setModel(model)

Sets the model instance to map. This should be an instance of the model class that is being used in addMapping().

Parameters:model (object) – the model instance

setModelClass(model_class)

The first time this method is called, define self._model_class. For all subsequent calls, test the value of the model_class argument against the stored value. Meant to be called directly or through setModel.

Raises:TypeError – when the model class has already been set and this method is called with an argument that does not match the value of self._model_class. Parameters:model_class (parameters.Param class (not instance)) – the class of the model that this mapper will attempt to synchronize with external targets (views).

suspend_auto_update_target(*args, **kwds)

updateModel()

Updates all mapped parameters on the model object from the target objects. Any target values that are unchanged will be skipped.

updateTarget()

Updates all target objects from the mapped parameters on the model object. Any param values that are unchanged will be skipped.

class schrodinger.models.mappers.AccessType

Bases: enum.IntEnum

The different types of target access.

getter = 0

setter = 1

signal = 2

class schrodinger.models.mappers.AttrTarget(obj, name, signal=None)

Bases: schrodinger.models.mappers.Target

Allows an attribute on any object to be synchronized to a param. Example:

target = AttrTarget(my_obj, ‘x_data’)

This creates a target for synchronizing my_obj.x_data.

Note that attributes by default don’t have a signal, so auto-updating of the model param won’t work unless the optional signal argument is supplied.

getValue()

setValue(value)

class schrodinger.models.mappers.DefaultTargetMixin

Bases: object

Use this mixin to enable get default Target behavior from a custom object the way it works for standard widgets like QCheckBox and QLineEdit. It is up to the subclass to implement targetGetValue and targetSetValue as well as to emit the targetValueChanged signal with the new value at the appropriate time.

After subclassing, the new custom object can be passed in as the obj argument to the Target constructor.

Using this mixin requires that the class also inherits from QObject.

targetGetValue()

targetSetValue(value)

targetValueChanged

class schrodinger.models.mappers.MapperMixin(*args, **kwargs)

Bases: schrodinger.models.mappers.DefaultTargetMixin

Mixin that can facilitate the use of parameters and mappers for storing the state of its subclasses.

Any data members that need to be mapped should be mapped within subclasses using the mapper instance variable.

By defining af2SettingsGetValue and af2SettingsSetValue, the subclass of this mixin can be set as a mapped object in SettingsParamMapper. In order to enable this functionality, subclasses must

1. add any necessary mappings to the mapper instance variable
2. Define the class variable model_class

Variables:

• mapper – a AbstractParamMapper instance that can be used to keep track of data members of this mixin’s subclasses.
• model_class – to be defined in subclasses. The model class that stores information about the subclass of this mixin (which can be though of as a “view”).

defineMappings()

Override this in the subclass to define mappings. Should return a dict mapping {<target> : <param>}. Most commonly, targets will be a basic widget, like QLineEdit or QComboBox, or a custom widget that inherits from MapperMixin or DefaultTargetMixin.

For more fine-grain custom control, instantiate a Target object, which allows custom setters, getters, and signals to be specified.

The param is an abstract param reference, e.g. MyModel.my_param.

Example:

def defineMappings(self):
    combo = self.style_combo
    return {self.name_le : MyModel.name,
            Target(combo,
                   getter=combo.currentText,
                   setter=combo.setCurrentText) : MyModel.style,
            self.coord_widget : MyModel.coord}

model_class = None

onValueChanged()

targetGetValue()

targetSetValue(value)

class schrodinger.models.mappers.ParamTarget(obj, param)

Bases: schrodinger.models.mappers.Target

Class to allow a param to be synchronized to another param. Example:

target = ParamTarget(target_model, MyModelClass.param)

This creates a target for synchronizing target_model.param, where target_model is an instance of MyModelClass.

getValue()

setValue(value)

class schrodinger.models.mappers.SettingsParamMapper(auto_update_target=False)

Bases: schrodinger.models.mappers.AbstractParamMapper

This class is now deprecated in favor of TargetParamMapper.

This mapper allows mapping via appframework2’s settings module. Any object that can be “get” and “set” in the settings module can be mapped to a param. This includes most basic Qt widgets as well as any classes that support the af2 settings getter and setter API.

getSignalsAndSlots(model)

onModelValueChanged()

class schrodinger.models.mappers.Target(obj=None, getter=<object object>, setter=<object object>, signal=<object object>, slot=None)

Bases: PyQt5.QtCore.QObject

Describes a target that maps to a model param.

Variables:targetChanged (QtCore.pyqtSignal) – signal that gets emitted when a change in the target’s value is detected.

getValue()

The standard method for getting a target’s value, regardless of whether this is using a default getter or a custom one.

onModelParamChanged(value)

onTargetSignal()

We connect this slot to the target’s specific signal and emit the generic targetChanged signal with the new value. This provides a uniform interface for the mapper to connect to.

setValue(value)

The standard method for setting a target’s value, regardless of whether this is using a default setter or a custom one.

slot()

targetChanged

class schrodinger.models.mappers.TargetParamMapper(auto_update_target=True, auto_update_model=True)

Bases: schrodinger.models.mappers.AbstractParamMapper

Maps Target objects to params in a model.

getParamSlot(param)

Gets the param-specific slot function for responding to target change. If no slot exists for this param, a new one is created.

getSignalsAndSlots(model)

getTargetSlot(target)

Gets the target-specific slot function for responding to param change. If no slot exists for this target, a new one is created.

schrodinger.models.mappers.make_mapper(map_dict, model=None, mapper_class=None)

Convenience function for adding many mappings at once via a dictionary.

Parameters:

• map_dict (dict) – a dictionary with abstract parameters as keys and target objects as values.
• model (object) – an optional paramter for setting a specific model object to this mapper. Doing so will also set this mapper as the model’s primary mapper, if possible
• mapper_class (type) – an optional parameter to use if the mapper is not meant to be a SettingsParamMapper.