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.Target(obj=None, getter=<object object>, setter=<object object>, signal=<object object>, datatype=<object object>, slot=None, auto_update_target=<object object>, auto_update_model=<object object>)

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.
targetChanged
auto_update_target

This property controls live updating of the target in response to model value changes. This may be modified at any time. Set it to DEFAULT to revert back to the original behavior.

auto_update_model

This property controls live updating of the model in response to target value changes. This may be modified at any time. Set it to DEFAULT to revert back to the original behavior.

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.

onModelParamChanged(value)
slot()
getValue()

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

setValue(value)

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

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()

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

setValue(value)

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

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()

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

setValue(value)

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

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.

The variables auto_update_target and auto_update_model can be set on the instance at any time to turn on or off live-updating of the target/model values.

targetValueChanged
auto_update_target = True
auto_update_model = True
targetGetValue()
targetSetValue(value)
class schrodinger.models.mappers.AccessType

Bases: enum.IntEnum

The different types of target access.

getter = 0
setter = 1
signal = 2
datatype = 3
schrodinger.models.mappers.qbuttongroup_access_factory(obj, access_type)
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.

suspend_auto_update_target()
TARGET_CLASS

alias of builtins.NotImplementedError

addMapping(target, param)

Maps a target (or collection of targets) to an abstract param (or collection of abstract params). 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:

A target may be mapped to multiple params, and multiple targets may be mapped to the same param. This is useful when the same param is associated with multiple targets (e.g. multiple views on a single data model) or vice versa (e.g. a single LineEdit sets the value of multiple fields in the model).

If the target is not an instance of self.TARGET_CLASS already, it will be automatically wrapped (i.e. self.TARGET_CLASS(target)). This allows common targets such as Qt widgets to be passed in directly.

Parameters:
  • param (parameters.Param or tuple) – an abstract param (ex. Atom.coord.x) or collection of abstract params
  • target (self.TARGET_CLASS or object that can be wrapped via self.TARGET_CLASS(target) or tuple) – the target or collection of targets mapped to a parameter.
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).
modelClass()
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()
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
resetMappedParams()
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.TargetParamMapper(auto_update_target=True, auto_update_model=True)

Bases: schrodinger.models.mappers.AbstractParamMapper

Maps Target objects to params in a model.

TARGET_CLASS

alias of Target

addGetSignalsAndSlotsCallback(callback)

Adds a “getSignalsAndSlots” function that will be called whenever a new model is set. See SignalsAndSlotsMixin.getSignalsAndSlots for information on parameters and return value for the callback.

connectSignalAndSlot(signal, slot)

Connects a signal/slot pair which will automatically be disconnected when the model is changed. The connection is discarded once disconnected and will not be reconnected when a new model is set.

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.

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.

class schrodinger.models.mappers.SignalsAndSlotsMixin

Bases: schrodinger.models.mappers.DefaultTargetMixin

Mixin for creating target objects that automatically disconnects and connects signals and slots whenever the model is changed. To use, override the method getSignalsAndSlots.

Whenever setModel is used to set a new model, all signal/slot pairs are disconnected from the old model and reconnected with the new model.

model_class = None
initLayOut()
initSetDefaults()
setDefaults()
setModel(model)

Sets the model object. Disconnects the old model, if one is set, and connects the new model. Pass in None to have no model set.

Note that setting the model will not actually cause anything to become synchronized to the model, just that signals are now connected.

Parameters:model – the model instance or None
getSignalsAndSlots(model)

Override this method to specify signal and slot pairs that need to be connected/disconnected whenever the model instance is switched using setModel. The model instance is provided as an argument so that instance-specific signals can be used, but any pairs of signals and slots may be returned from this method.

Returns:a list of 2-tuples where each tuple is a signal, slot pair
targetGetValue()
targetSetValue(value)
class schrodinger.models.mappers.MapperMixin

Bases: schrodinger.models.mappers.SignalsAndSlotsMixin

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

Works out of the box for widgetmixins.InitMixin or af2.baseapp.BasePanel (which covers af2.App and af2.JobApp). To use with other base classes, call _setupMixin during initialization.

By default, the mixin will attempt to create an empty model instance at construction and set it as the model. If the model class’ constructor requires arguments, the model will be set to None instead. In this case a model instance must be constructed and explicitly set using setModel before the MapperMixin can be used.

Variables:
  • mapper – an 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 list of tuples [(<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)]
setModel(model)

Sets the model object for the mapper. Disconnects the old model, if one is set, and connects the new model. Pass in None to have no model set.

Parameters:model – the model instance or None
schrodinger.models.mappers.make_mapper(mappings, model=None, mapper_class=None)

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

Parameters:mappings – a list of (target, abstract param) tuples. The target may

be an actual Target object or an object that can be wrapped by Target. :type mappings: list

Parameters:
  • model (object) – an optional parameter 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.