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.

exception schrodinger.models.mappers.WrappedObjDeletedError

Bases: RuntimeError

Custom exception for reporting “wrapped C/C++ object has been deleted”

class schrodinger.models.mappers.TargetSpec(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: PyQt6.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

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

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

Parameters

obj – this object, if specified, will be used to determine default access for this target.

For example, passing in a QCheckBox, my_chk, will make the default getter my_chk.isChecked, the default setter my_chk.setChecked, and the default signal my_chk.stateChanged.

Passing in None will disable default access. In this case only explicitly specified getters, setters, signals, and slots will be used.

Parameters

• getter (callable) – a function to get a value from the target. Overrides the default getter in obj, if specified. Passing in None will result in the target value always returning None.

• setter (callable) – a function that sets the value on the target. Overrides the default setter in obj, if specified. Passing in None will result in the target value never being changed.

• signal (QtCore.pyqtSignal) – the signal that indicates a change in target value. This will override the default signal in obj, if specified. The target signal is forwarded to targetChanged, to provide a common interface. Pass in None to disable monitoring of target changes.

• datatype (type) – the type of data expected by the target object. If set, this will be used to cast values being passed to the target object via the setter. Ex. setting the datatype to str for a QLineEdit allows the line edit to display IntParam data. Note: this does not work the other way - mapping a QLineEdit to an IntParam will cause the param to take on a string value.

• slot (callable) – a function that will get called whenever the corresponding model param is changed. Will get called regardless of whether a setter or obj is specified. By default there is no slot set.

• auto_update_target (bool) – whether the target should be automatically (and immediately) updated when the param is changed. Default behavior: if the obj has an attribute named auto_update_target, use that, otherwise True.

• auto_update_model (bool) – whether the model should be automatically (and immediately) updated when the target is changed. Default behavior: if the obj has an attribute named auto_update_model, use that, otherwise True.

property 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.

property 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.ParamTargetSpec(model, param)

Bases: schrodinger.models.mappers.TargetSpec

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

target = ParamTargetSpec(target_model, MyModelClass.param)

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

__init__(model, param)

Parameters

• model (parameters.CompoundParam) – the model which contains the param to be mapped

• param (parameters.Param) – the abstract param to be mapped (i.e. MyModelClass.param)

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.AttrTargetSpec(obj, name, signal=None)

Bases: schrodinger.models.mappers.TargetSpec

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

target = AttrTargetSpec(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.

__init__(obj, name, signal=None)

Parameters

• obj – the object that has the attribute to be mapped

• name (str) – the name of the target attribute on the object

• signal (QtCore.pyqtSignal) – a Qt signal that indicates a change in the attribute’s value.

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.TargetMixin

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

pyqtSignal(*types, name: str = …, revision: int = …, arguments: Sequence = …) -> PYQT_SIGNAL

types is normally a sequence of individual types. Each type is either a type object or a string that is the name of a C++ type. Alternatively each type could itself be a sequence of types each describing a different overloaded signal. name is the optional C++ name of the signal. If it is not specified then the name of the class attribute that is bound to the signal is used. revision is the optional revision of the signal that is exported to QML. If it is not specified then 0 is used. arguments is the optional sequence of the names of the signal’s arguments.

auto_update_target = True

auto_update_model = True

targetGetValue()

targetSetValue(value)

class schrodinger.models.mappers.TargetParamMapper(parent=None, auto_update_target=True, auto_update_model=True, *, _display_ok=True)

Bases: PyQt6.QtCore.QObject

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

Variables

setting_model – Context manager to set a flag indicating that the model is being set. Intended for use by MapperMixin.

TARGET_CLASS

alias of schrodinger.models.mappers.TargetSpec

updating_values()

setting_model()

__init__(parent=None, auto_update_target=True, auto_update_model=True, *, _display_ok=True)

Parameters

• auto_update_target (bool) – whether to update the target immediately when the model is changed

• auto_update_model (bool) – whether to update the model immediately when the target is changed

• _display_ok (bool) – whether it is safe to import modules that require display (e.g. QtWidgets).

property auto_update_target

This property controls live updating of the target in response to model value changes. This may be modified at any time.

property auto_update_model

This property controls live updating of the model in response to target value changes. This may be modified at any time.

mappedParams()

Return a list of the abstract params that are mapped to.

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.

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.

Note that the returned slots will only be called when the specified signal is emitted, and not when the model is changed using setModel().

Returns

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

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.

addGetSignalsAndSlotsCallback(callback)

Adds a “getSignalsAndSlots” function that will be called whenever a new model is set. See MapperMixin.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.MapperMixin(*args, **kwargs)

Bases: object

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 _setupMapperMixin() 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”).

model_class = None

setting_model()

__init__(*args, **kwargs)

property model

initLayOut()

@overrides: widgetmixins.InitMixin

initSetDefaults()

@overrides: widgetmixins.InitMixin

setDefaults()

@overrides: af2.App

makeInitialModel()

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

getModel()

resetMappedParams()

mappedParams()

Return a list of the abstract params that are mapped to.

defineMappings()

Override this in the subclass to define mappings. Should return a list of tuples [(<target>, <param>)]. Targets can be:

1. a basic widget, like QLineEdit or QComboBox

2. a custom object that inherits MapperMixin or TargetMixin

3. a TargetSpec instance

4. a slot

For common widgets, standard signals and getter/setter methods will be used, as defined in mappers._get_default_access_names().

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

Supplying a slot as the first element of the tuple is equivalent to providing TargetSpec(slot=my_slot).

Note that all target slots are triggered on setModel() as well as in response to the specified signal.

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),
            (TargetSpec(combo,
                    getter=combo.currentText,
                    setter=combo.setCurrentText), MyModel.style),
            (self.coord_widget, MyModel.coord),
            (self._onASLTextChanged, MyModel.asl_text)]

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

setModelWithoutSlots(model)

This is called when this MapperMixin is a sub-widget of a parent MapperMixin. Since the slots will all be called at the end of the parent setModel, they shouldn’t be called during the sub-widget’s setModel.

runAllSlots()

exception schrodinger.models.mappers.DefineMappingsException

Bases: ValueError

Exception to raise for improperly formatted DefineMappings in mappers

exception schrodinger.models.mappers.SignalsAndSlotsException

Bases: ValueError

Exception to raise for improperly formatted SignalsAndSlots

exception schrodinger.models.mappers.CantAccessModelError

Bases: RuntimeError

Exception to raise when accessing self.model during MapperMixin.setModel

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

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

Parameters

• mappings (list) – a list of (target, abstract param) tuples. The target may be an actual Target object or an object that can be wrapped by Target.

• 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.