schrodinger.ui.qt.appframework2.tasks module

<<<<< DEPRECATED >>>>> This module should not be used for new code. Instead, consider using schrodinger.tasks.tasks <<<<< !!!!!!!!! >>>>>

Task runner classes are designed to be subclassed to define runners for specific tasks. A “task” is a generic term that encompasses jobs, threads, and subprocess calls.

class schrodinger.ui.qt.appframework2.tasks.Status

Bases: object

NONE = '-'
RUNNING = 'Running'
FAILED = 'Failed'
DONE = 'Done'
ERROR = 'Error'
class schrodinger.ui.qt.appframework2.tasks.AbstractTaskWrapper(task, settings=None, name='', test_mode=False)

Bases: object

Provides a common interface for tasks that is independent of the underlying task object.

In main methods are self.isRunning() and self.status(), the self.getName() and self.setName()

TASK_CLASS

alias of None

__init__(task, settings=None, name='', test_mode=False)
Parameters
  • task (see derived class) – the underlying task object (depends on subclass)

  • name (str) – the task name

  • settings (dict) – the settings used to run this task

  • test_mode (bool) – disables type-checking of the task object. Used for mocking that task in tests

isRunning()

Whether this task is currently running.

status()

The current status of the task. The schema is flexible and can be agreed upon with the corresponding runner.

settings()

Returns the settings that were used to run this task.

getName()
setName(name)
class schrodinger.ui.qt.appframework2.tasks.AbstractTaskRunner(messaging_callback=None, settings_callback=None)

Bases: schrodinger.ui.qt.appframework2.validation.ValidationMixin, PyQt6.QtCore.QObject

stateChanged
startRequested
startFailed
taskStarted
taskEnded
nameChanged
resetAllRequested
__init__(messaging_callback=None, settings_callback=None)

Initializes a new task runner

Parameters

messaging_callback

callback used for interacting with the user. This includes both reporting results or errors and asking questions to the user. The callback should be of the form:

f(message_type, text, options=None, runner=None)

where message_type is one of ERROR, WARNING, or QUESTION, text is the text of the message to be displayed, and options is an optional dict which can be used by the callback. For example, a dialog title could be passed to the callback via the options dict. The callback should never depend on the presence or absence of any options. The runner is simply the runner that is making the call, so that the callback can tell which runner is invoking the callback.

When the message is a question, the function should return the user’s response, typically True or False for a yes/no question.

Parameters

settings_callback

callback for communicating state with the parent object. This callback can be used both to push state to or pull state from the parent object. The callback should be of the form:

f(settings=None, runner=None)

If no settings are passed in, the callback should return the state of the parent object (i.e. the panel state) in the form of a dictionary.

The runner can be passed in as well if the callback needs to access the runner to properly process the callback.

If a settings dictionary is passed in, the callback should apply any settings in the dictionary to the parent object (thus altering its state). Passing in an empty dictionary is a no-op.

setCallbacks(messaging_callback=None, settings_callback=None)
setRunnerOptions()

Optional override to set options for the runner. Not overriding this at all results in using all default values.

self.allow custom_name - whether name is user-editable. Default: False

self.allow_concurrent - whether another task can be started while one is still running. Default: True

self.history_length - how many past jobs to keep track of. Default: 5

self.base_name - the base for task names. The base name gets modified to generate unique task names. Ex. MyTask_3. Default: “task”

self.runner_name - a name to describe the type of task. Equivalent to program_name for jobs. Default: ‘task’

nextName(name_list=None)

Returns the name that will be assigned to the next task that gets run. There is no currentName(), as multiple tasks might be running concurrently. To get the name of an existing task, use task.getName().

If a custom name has been set, that will be used as the next name. Otherwise, the base name will be used to generate a new unique name.

This method can be overridden to alter the task naming behavior.

Parameters

name_list (list of basestring) – Optional list of names to uniquify against. If not given, the name will be compared against the stored self.names()

setCustomName(name)

Sets a custom name for the next task to be run.

Parameters

name (str) – the custom name. Pass in an empty string to return to standard naming.

preValidate()

Override this to include any logic that should be run prior to the validation step.

Returns

Whether this step has succeeded. Returning False will result in aborting the task

Return type

bool

postStart(task)

Override this to include any logic that should be run immediately after a task is started. This will only be run after a task actually starts.

The started task is passed in as a parameter to allow interaction with the task instance. Note that there is no guarantee that the task is still running when this method is called.

Parameters

task (AbstractTaskWrapper) – the task that was just started

postProcess(task)

Override this to include any logic that should be run whenever a task completes. This method is called whenever a task stops running, whether it succeeded, failed, or encounrtered an error.

The completed task is passed in as a parameter to allow querying and modification of the task instance.

There is currently no mechanism for ensuring this logic gets run between maestro sesions. If a session is closed while the job is running, this method will never be called. Use this method to perform only actions that make sense in the context of a single session.

Parameters

task (AbstractTaskWrapper) – the task that has ended

start()

Starts the task. This includes the preliminary work of calling preValidate() and running validation before attempting to actually start the task itself.

The actual starting of the task should be handled in the _start method in the derived classes and will vary depening on the type of runner.

names()
tasks()
addTask(task)

Add a new task to be tracked. This should be called whenever a task is started.

Parameters

task (AbstractTaskWrapper) – the task

findTask(name)
showMessage(message_type, text, options=None)

Communicates with the parent object via the messaging_callback. This method generally doesn’t need to be called; call error, warning, question, or info instead.

Parameters
  • message_type (int) – the type of message to send

  • text (str) – the main text of the message

  • options (dict) – a dictionary of other options to be processed by the messaging_callback.

error(text, caption='Error')
warning(text, caption='Warning')
question(text, caption='Question')
info(text, caption='Info')
status(text, timeout=3000, color=None)

Request a status message to be displayed by the runner’s parent.

Parameters
  • text (str) – the text to display

  • timeout (int) – duration in ms to display the status. A timeout of 0 results in a permanent message.

  • color (QtGui.QColor) – color of the status message.

updateStatusText()

Override this to update the status, for example, when settings have changed or the current task runner is switched.

pullSettings()

This method calls the settings callback, which should return the user’s input for this job, such as input files, options, etc. For GUI panels, this is how the panel state is applied to the job runner.

pushSettings(settings=None)

Pushes a settings dictionary via the settings callback. Doing this will alter the state of the parent object (generally the panel). This function can be used to reset the panel or load saved presets.

If a settings dictionary is not passed in, the current job settings will be used.

Parameters

settings (dict) – a settings dictionary to push to the parent object

settings()
defaultSettings()

Override this method to define default values for any settings. This dictionary of default settings will be used to reset the parent.

resetAll()
reset()

Resets the parent object using the default settings defined by the task runner.

reportValidation(results)

Present validation messages to the user. This is an implmentation of the ValidationMixin interface and does not need to be called directly.

Parameters

results (ValidationResults) – Set of results generated by validate()

isRunning()
blockSignals(self, b: bool) bool
childEvent(self, a0: QChildEvent)
children(self) List[QObject]
connectNotify(self, signal: QMetaMethod)
customEvent(self, a0: QEvent)
deleteLater(self)
destroyed

destroyed(self, object: typing.Optional[QObject] = None) [signal]

disconnect(a0: QMetaObject.Connection) bool
disconnect(self) None
disconnectNotify(self, signal: QMetaMethod)
dumpObjectInfo(self)
dumpObjectTree(self)
dynamicPropertyNames(self) List[QByteArray]
event(self, a0: QEvent) bool
eventFilter(self, a0: QObject, a1: QEvent) bool
findChild(self, type: type, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) QObject
findChild(self, types: Tuple, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) QObject
findChildren(self, type: type, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, types: Tuple, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, type: type, re: QRegularExpression, options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, types: Tuple, re: QRegularExpression, options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
inherits(self, classname: str) bool
installEventFilter(self, a0: QObject)
isSignalConnected(self, signal: QMetaMethod) bool
isWidgetType(self) bool
isWindowType(self) bool
killTimer(self, id: int)
metaObject(self) QMetaObject
moveToThread(self, thread: QThread)
objectName(self) str
objectNameChanged

objectNameChanged(self, objectName: str) [signal]

parent(self) QObject
property(self, name: str) Any
pyqtConfigure(...)

Each keyword argument is either the name of a Qt property or a Qt signal. For properties the property is set to the given value which should be of an appropriate type. For signals the signal is connected to the given value which should be a callable.

receivers(self, signal: PYQT_SIGNAL) int
removeEventFilter(self, a0: QObject)
runValidation(silent=False, validate_children=True, stop_on_fail=True)

Runs validation and reports the results (unless run silently).

Parameters
  • silent (bool) – run without any reporting (i.e. error messages to the user). This is useful if we want to programmatically test validity. Changes return value of this method from ValidationResults to a boolean.

  • validate_children (bool) – run validation on all child objects. See _validateChildren for documentation on what this entails.

  • stop_on_fail (bool) – stop validation when first failure is encountered

Returns

if silent is False, returns the validation results. If silent is True, returns a boolean generated by reportValidation.

Return type

ValidationResults or bool

sender(self) QObject
senderSignalIndex(self) int
setObjectName(self, name: str)
setParent(self, a0: QObject)
setProperty(self, name: str, value: Any) bool
signalsBlocked(self) bool
startTimer(self, interval: int, timerType: Qt.TimerType = Qt.CoarseTimer) int
staticMetaObject = <PyQt6.QtCore.QMetaObject object>
thread(self) QThread
timerEvent(self, a0: QTimerEvent)
tr(sourceText: str, disambiguation: typing.Optional[str] = None, n: int = - 1) str
class schrodinger.ui.qt.appframework2.tasks.BaseFunctionRunner(func=None, messaging_callback=None, settings_callback=None)

Bases: schrodinger.ui.qt.appframework2.tasks.AbstractTaskRunner

Base class for runners that can take a callable on instantiation or define task logic in the runMain() method. Passing in a callable will override any implementation runMain().

__init__(func=None, messaging_callback=None, settings_callback=None)
Parameters

func (callable) – the callable that will be run as the main task. Overrides self.runMain(). If self.runMain() is not defined, a func must be provided.

runMain(task)
addTask(task)

Add a new task to be tracked. This should be called whenever a task is started.

Parameters

task (AbstractTaskWrapper) – the task

blockSignals(self, b: bool) bool
childEvent(self, a0: QChildEvent)
children(self) List[QObject]
connectNotify(self, signal: QMetaMethod)
customEvent(self, a0: QEvent)
defaultSettings()

Override this method to define default values for any settings. This dictionary of default settings will be used to reset the parent.

deleteLater(self)
destroyed

destroyed(self, object: typing.Optional[QObject] = None) [signal]

disconnect(a0: QMetaObject.Connection) bool
disconnect(self) None
disconnectNotify(self, signal: QMetaMethod)
dumpObjectInfo(self)
dumpObjectTree(self)
dynamicPropertyNames(self) List[QByteArray]
error(text, caption='Error')
event(self, a0: QEvent) bool
eventFilter(self, a0: QObject, a1: QEvent) bool
findChild(self, type: type, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) QObject
findChild(self, types: Tuple, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) QObject
findChildren(self, type: type, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, types: Tuple, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, type: type, re: QRegularExpression, options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, types: Tuple, re: QRegularExpression, options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findTask(name)
info(text, caption='Info')
inherits(self, classname: str) bool
installEventFilter(self, a0: QObject)
isRunning()
isSignalConnected(self, signal: QMetaMethod) bool
isWidgetType(self) bool
isWindowType(self) bool
killTimer(self, id: int)
metaObject(self) QMetaObject
moveToThread(self, thread: QThread)
nameChanged
names()
nextName(name_list=None)

Returns the name that will be assigned to the next task that gets run. There is no currentName(), as multiple tasks might be running concurrently. To get the name of an existing task, use task.getName().

If a custom name has been set, that will be used as the next name. Otherwise, the base name will be used to generate a new unique name.

This method can be overridden to alter the task naming behavior.

Parameters

name_list (list of basestring) – Optional list of names to uniquify against. If not given, the name will be compared against the stored self.names()

objectName(self) str
objectNameChanged

objectNameChanged(self, objectName: str) [signal]

parent(self) QObject
postProcess(task)

Override this to include any logic that should be run whenever a task completes. This method is called whenever a task stops running, whether it succeeded, failed, or encounrtered an error.

The completed task is passed in as a parameter to allow querying and modification of the task instance.

There is currently no mechanism for ensuring this logic gets run between maestro sesions. If a session is closed while the job is running, this method will never be called. Use this method to perform only actions that make sense in the context of a single session.

Parameters

task (AbstractTaskWrapper) – the task that has ended

postStart(task)

Override this to include any logic that should be run immediately after a task is started. This will only be run after a task actually starts.

The started task is passed in as a parameter to allow interaction with the task instance. Note that there is no guarantee that the task is still running when this method is called.

Parameters

task (AbstractTaskWrapper) – the task that was just started

preValidate()

Override this to include any logic that should be run prior to the validation step.

Returns

Whether this step has succeeded. Returning False will result in aborting the task

Return type

bool

property(self, name: str) Any
pullSettings()

This method calls the settings callback, which should return the user’s input for this job, such as input files, options, etc. For GUI panels, this is how the panel state is applied to the job runner.

pushSettings(settings=None)

Pushes a settings dictionary via the settings callback. Doing this will alter the state of the parent object (generally the panel). This function can be used to reset the panel or load saved presets.

If a settings dictionary is not passed in, the current job settings will be used.

Parameters

settings (dict) – a settings dictionary to push to the parent object

pyqtConfigure(...)

Each keyword argument is either the name of a Qt property or a Qt signal. For properties the property is set to the given value which should be of an appropriate type. For signals the signal is connected to the given value which should be a callable.

question(text, caption='Question')
receivers(self, signal: PYQT_SIGNAL) int
removeEventFilter(self, a0: QObject)
reportValidation(results)

Present validation messages to the user. This is an implmentation of the ValidationMixin interface and does not need to be called directly.

Parameters

results (ValidationResults) – Set of results generated by validate()

reset()

Resets the parent object using the default settings defined by the task runner.

resetAll()
resetAllRequested
runValidation(silent=False, validate_children=True, stop_on_fail=True)

Runs validation and reports the results (unless run silently).

Parameters
  • silent (bool) – run without any reporting (i.e. error messages to the user). This is useful if we want to programmatically test validity. Changes return value of this method from ValidationResults to a boolean.

  • validate_children (bool) – run validation on all child objects. See _validateChildren for documentation on what this entails.

  • stop_on_fail (bool) – stop validation when first failure is encountered

Returns

if silent is False, returns the validation results. If silent is True, returns a boolean generated by reportValidation.

Return type

ValidationResults or bool

sender(self) QObject
senderSignalIndex(self) int
setCallbacks(messaging_callback=None, settings_callback=None)
setCustomName(name)

Sets a custom name for the next task to be run.

Parameters

name (str) – the custom name. Pass in an empty string to return to standard naming.

setObjectName(self, name: str)
setParent(self, a0: QObject)
setProperty(self, name: str, value: Any) bool
setRunnerOptions()

Optional override to set options for the runner. Not overriding this at all results in using all default values.

self.allow custom_name - whether name is user-editable. Default: False

self.allow_concurrent - whether another task can be started while one is still running. Default: True

self.history_length - how many past jobs to keep track of. Default: 5

self.base_name - the base for task names. The base name gets modified to generate unique task names. Ex. MyTask_3. Default: “task”

self.runner_name - a name to describe the type of task. Equivalent to program_name for jobs. Default: ‘task’

settings()
showMessage(message_type, text, options=None)

Communicates with the parent object via the messaging_callback. This method generally doesn’t need to be called; call error, warning, question, or info instead.

Parameters
  • message_type (int) – the type of message to send

  • text (str) – the main text of the message

  • options (dict) – a dictionary of other options to be processed by the messaging_callback.

signalsBlocked(self) bool
start()

Starts the task. This includes the preliminary work of calling preValidate() and running validation before attempting to actually start the task itself.

The actual starting of the task should be handled in the _start method in the derived classes and will vary depening on the type of runner.

startFailed
startRequested
startTimer(self, interval: int, timerType: Qt.TimerType = Qt.CoarseTimer) int
stateChanged
staticMetaObject = <PyQt6.QtCore.QMetaObject object>
status(text, timeout=3000, color=None)

Request a status message to be displayed by the runner’s parent.

Parameters
  • text (str) – the text to display

  • timeout (int) – duration in ms to display the status. A timeout of 0 results in a permanent message.

  • color (QtGui.QColor) – color of the status message.

taskEnded
taskStarted
tasks()
thread(self) QThread
timerEvent(self, a0: QTimerEvent)
tr(sourceText: str, disambiguation: typing.Optional[str] = None, n: int = - 1) str
updateStatusText()

Override this to update the status, for example, when settings have changed or the current task runner is switched.

warning(text, caption='Warning')
class schrodinger.ui.qt.appframework2.tasks.BlockingRunner(func=None, messaging_callback=None, settings_callback=None)

Bases: schrodinger.ui.qt.appframework2.tasks.BaseFunctionRunner

Runner class that makes a blocking call to its main function. Useful for quick calculations.

This can either be subclassed with runMain() being implemented with the main logic, or used directly by passing in a callable.

__init__(func=None, messaging_callback=None, settings_callback=None)
Parameters

func (callable) – the callable that will be run as the main task. Overrides self.runMain(). If self.runMain() is not defined, a func must be provided.

addTask(task)

Add a new task to be tracked. This should be called whenever a task is started.

Parameters

task (AbstractTaskWrapper) – the task

blockSignals(self, b: bool) bool
childEvent(self, a0: QChildEvent)
children(self) List[QObject]
connectNotify(self, signal: QMetaMethod)
customEvent(self, a0: QEvent)
defaultSettings()

Override this method to define default values for any settings. This dictionary of default settings will be used to reset the parent.

deleteLater(self)
destroyed

destroyed(self, object: typing.Optional[QObject] = None) [signal]

disconnect(a0: QMetaObject.Connection) bool
disconnect(self) None
disconnectNotify(self, signal: QMetaMethod)
dumpObjectInfo(self)
dumpObjectTree(self)
dynamicPropertyNames(self) List[QByteArray]
error(text, caption='Error')
event(self, a0: QEvent) bool
eventFilter(self, a0: QObject, a1: QEvent) bool
findChild(self, type: type, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) QObject
findChild(self, types: Tuple, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) QObject
findChildren(self, type: type, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, types: Tuple, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, type: type, re: QRegularExpression, options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, types: Tuple, re: QRegularExpression, options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findTask(name)
info(text, caption='Info')
inherits(self, classname: str) bool
installEventFilter(self, a0: QObject)
isRunning()
isSignalConnected(self, signal: QMetaMethod) bool
isWidgetType(self) bool
isWindowType(self) bool
killTimer(self, id: int)
metaObject(self) QMetaObject
moveToThread(self, thread: QThread)
nameChanged
names()
nextName(name_list=None)

Returns the name that will be assigned to the next task that gets run. There is no currentName(), as multiple tasks might be running concurrently. To get the name of an existing task, use task.getName().

If a custom name has been set, that will be used as the next name. Otherwise, the base name will be used to generate a new unique name.

This method can be overridden to alter the task naming behavior.

Parameters

name_list (list of basestring) – Optional list of names to uniquify against. If not given, the name will be compared against the stored self.names()

objectName(self) str
objectNameChanged

objectNameChanged(self, objectName: str) [signal]

parent(self) QObject
postProcess(task)

Override this to include any logic that should be run whenever a task completes. This method is called whenever a task stops running, whether it succeeded, failed, or encounrtered an error.

The completed task is passed in as a parameter to allow querying and modification of the task instance.

There is currently no mechanism for ensuring this logic gets run between maestro sesions. If a session is closed while the job is running, this method will never be called. Use this method to perform only actions that make sense in the context of a single session.

Parameters

task (AbstractTaskWrapper) – the task that has ended

postStart(task)

Override this to include any logic that should be run immediately after a task is started. This will only be run after a task actually starts.

The started task is passed in as a parameter to allow interaction with the task instance. Note that there is no guarantee that the task is still running when this method is called.

Parameters

task (AbstractTaskWrapper) – the task that was just started

preValidate()

Override this to include any logic that should be run prior to the validation step.

Returns

Whether this step has succeeded. Returning False will result in aborting the task

Return type

bool

property(self, name: str) Any
pullSettings()

This method calls the settings callback, which should return the user’s input for this job, such as input files, options, etc. For GUI panels, this is how the panel state is applied to the job runner.

pushSettings(settings=None)

Pushes a settings dictionary via the settings callback. Doing this will alter the state of the parent object (generally the panel). This function can be used to reset the panel or load saved presets.

If a settings dictionary is not passed in, the current job settings will be used.

Parameters

settings (dict) – a settings dictionary to push to the parent object

pyqtConfigure(...)

Each keyword argument is either the name of a Qt property or a Qt signal. For properties the property is set to the given value which should be of an appropriate type. For signals the signal is connected to the given value which should be a callable.

question(text, caption='Question')
receivers(self, signal: PYQT_SIGNAL) int
removeEventFilter(self, a0: QObject)
reportValidation(results)

Present validation messages to the user. This is an implmentation of the ValidationMixin interface and does not need to be called directly.

Parameters

results (ValidationResults) – Set of results generated by validate()

reset()

Resets the parent object using the default settings defined by the task runner.

resetAll()
resetAllRequested
runMain(task)
runValidation(silent=False, validate_children=True, stop_on_fail=True)

Runs validation and reports the results (unless run silently).

Parameters
  • silent (bool) – run without any reporting (i.e. error messages to the user). This is useful if we want to programmatically test validity. Changes return value of this method from ValidationResults to a boolean.

  • validate_children (bool) – run validation on all child objects. See _validateChildren for documentation on what this entails.

  • stop_on_fail (bool) – stop validation when first failure is encountered

Returns

if silent is False, returns the validation results. If silent is True, returns a boolean generated by reportValidation.

Return type

ValidationResults or bool

sender(self) QObject
senderSignalIndex(self) int
setCallbacks(messaging_callback=None, settings_callback=None)
setCustomName(name)

Sets a custom name for the next task to be run.

Parameters

name (str) – the custom name. Pass in an empty string to return to standard naming.

setObjectName(self, name: str)
setParent(self, a0: QObject)
setProperty(self, name: str, value: Any) bool
setRunnerOptions()

Optional override to set options for the runner. Not overriding this at all results in using all default values.

self.allow custom_name - whether name is user-editable. Default: False

self.allow_concurrent - whether another task can be started while one is still running. Default: True

self.history_length - how many past jobs to keep track of. Default: 5

self.base_name - the base for task names. The base name gets modified to generate unique task names. Ex. MyTask_3. Default: “task”

self.runner_name - a name to describe the type of task. Equivalent to program_name for jobs. Default: ‘task’

settings()
showMessage(message_type, text, options=None)

Communicates with the parent object via the messaging_callback. This method generally doesn’t need to be called; call error, warning, question, or info instead.

Parameters
  • message_type (int) – the type of message to send

  • text (str) – the main text of the message

  • options (dict) – a dictionary of other options to be processed by the messaging_callback.

signalsBlocked(self) bool
start()

Starts the task. This includes the preliminary work of calling preValidate() and running validation before attempting to actually start the task itself.

The actual starting of the task should be handled in the _start method in the derived classes and will vary depening on the type of runner.

startFailed
startRequested
startTimer(self, interval: int, timerType: Qt.TimerType = Qt.CoarseTimer) int
stateChanged
staticMetaObject = <PyQt6.QtCore.QMetaObject object>
status(text, timeout=3000, color=None)

Request a status message to be displayed by the runner’s parent.

Parameters
  • text (str) – the text to display

  • timeout (int) – duration in ms to display the status. A timeout of 0 results in a permanent message.

  • color (QtGui.QColor) – color of the status message.

taskEnded
taskStarted
tasks()
thread(self) QThread
timerEvent(self, a0: QTimerEvent)
tr(sourceText: str, disambiguation: typing.Optional[str] = None, n: int = - 1) str
updateStatusText()

Override this to update the status, for example, when settings have changed or the current task runner is switched.

warning(text, caption='Warning')
class schrodinger.ui.qt.appframework2.tasks.BlockingWrapper(settings=None, name='', **kwargs)

Bases: schrodinger.ui.qt.appframework2.tasks.AbstractTaskWrapper

Since a blocking call has no real associated object, this is essentially an empty wrapper to provide the right interface for the runner.

TASK_CLASS

alias of dict

__init__(settings=None, name='', **kwargs)
Parameters
  • task (see derived class) – the underlying task object (depends on subclass)

  • name (str) – the task name

  • settings (dict) – the settings used to run this task

  • test_mode (bool) – disables type-checking of the task object. Used for mocking that task in tests

isRunning()

Whether this task is currently running.

getName()
setName(name)
settings()

Returns the settings that were used to run this task.

status()

The current status of the task. The schema is flexible and can be agreed upon with the corresponding runner.

class schrodinger.ui.qt.appframework2.tasks.ThreadRunner(*args, **kwargs)

Bases: schrodinger.ui.qt.appframework2.tasks.BaseFunctionRunner

An object to run tasks in threads. To use, subclass this class and override the runMain() method with logic to be run by the thread.

Options can be set by overriding setOptions(). See parent class for more information.

This can either be subclassed with runMain() being implemented with the main logic, or used directly by passing in a callable.

use_event_loop = False
__init__(*args, **kwargs)
Parameters

func (callable) – the callable that will be run as the main task. Overrides self.runMain(). If self.runMain() is not defined, a func must be provided.

addTask(task)

Add a new task to be tracked. This should be called whenever a task is started.

Parameters

task (AbstractTaskWrapper) – the task

blockSignals(self, b: bool) bool
childEvent(self, a0: QChildEvent)
children(self) List[QObject]
connectNotify(self, signal: QMetaMethod)
customEvent(self, a0: QEvent)
defaultSettings()

Override this method to define default values for any settings. This dictionary of default settings will be used to reset the parent.

deleteLater(self)
destroyed

destroyed(self, object: typing.Optional[QObject] = None) [signal]

disconnect(a0: QMetaObject.Connection) bool
disconnect(self) None
disconnectNotify(self, signal: QMetaMethod)
dumpObjectInfo(self)
dumpObjectTree(self)
dynamicPropertyNames(self) List[QByteArray]
error(text, caption='Error')
event(self, a0: QEvent) bool
eventFilter(self, a0: QObject, a1: QEvent) bool
findChild(self, type: type, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) QObject
findChild(self, types: Tuple, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) QObject
findChildren(self, type: type, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, types: Tuple, name: str = '', options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, type: type, re: QRegularExpression, options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findChildren(self, types: Tuple, re: QRegularExpression, options: Qt.FindChildOption = Qt.FindChildrenRecursively) List[QObject]
findTask(name)
info(text, caption='Info')
inherits(self, classname: str) bool
installEventFilter(self, a0: QObject)
isRunning()
isSignalConnected(self, signal: QMetaMethod) bool
isWidgetType(self) bool
isWindowType(self) bool
killTimer(self, id: int)
metaObject(self) QMetaObject
moveToThread(self, thread: QThread)
nameChanged
names()
nextName(name_list=None)

Returns the name that will be assigned to the next task that gets run. There is no currentName(), as multiple tasks might be running concurrently. To get the name of an existing task, use task.getName().

If a custom name has been set, that will be used as the next name. Otherwise, the base name will be used to generate a new unique name.

This method can be overridden to alter the task naming behavior.

Parameters

name_list (list of basestring) – Optional list of names to uniquify against. If not given, the name will be compared against the stored self.names()

objectName(self) str
objectNameChanged

objectNameChanged(self, objectName: str) [signal]

parent(self) QObject
postProcess(task)

Override this to include any logic that should be run whenever a task completes. This method is called whenever a task stops running, whether it succeeded, failed, or encounrtered an error.

The completed task is passed in as a parameter to allow querying and modification of the task instance.

There is currently no mechanism for ensuring this logic gets run between maestro sesions. If a session is closed while the job is running, this method will never be called. Use this method to perform only actions that make sense in the context of a single session.

Parameters

task (AbstractTaskWrapper) – the task that has ended

postStart(task)

Override this to include any logic that should be run immediately after a task is started. This will only be run after a task actually starts.

The started task is passed in as a parameter to allow interaction with the task instance. Note that there is no guarantee that the task is still running when this method is called.

Parameters

task (AbstractTaskWrapper) – the task that was just started

preValidate()

Override this to include any logic that should be run prior to the validation step.

Returns

Whether this step has succeeded. Returning False will result in aborting the task

Return type

bool

property(self, name: str) Any
pullSettings()

This method calls the settings callback, which should return the user’s input for this job, such as input files, options, etc. For GUI panels, this is how the panel state is applied to the job runner.

pushSettings(settings=None)

Pushes a settings dictionary via the settings callback. Doing this will alter the state of the parent object (generally the panel). This function can be used to reset the panel or load saved presets.

If a settings dictionary is not passed in, the current job settings will be used.

Parameters

settings (dict) – a settings dictionary to push to the parent object

pyqtConfigure(...)

Each keyword argument is either the name of a Qt property or a Qt signal. For properties the property is set to the given value which should be of an appropriate type. For signals the signal is connected to the given value which should be a callable.

question(text, caption='Question')
receivers(self, signal: PYQT_SIGNAL) int
removeEventFilter(self, a0: QObject)
reportValidation(results)

Present validation messages to the user. This is an implmentation of the ValidationMixin interface and does not need to be called directly.

Parameters

results (ValidationResults) – Set of results generated by validate()

reset()

Resets the parent object using the default settings defined by the task runner.

resetAll()
resetAllRequested
runMain(task)
runValidation(silent=False, validate_children=True, stop_on_fail=True)

Runs validation and reports the results (unless run silently).

Parameters
  • silent (bool) – run without any reporting (i.e. error messages to the user). This is useful if we want to programmatically test validity. Changes return value of this method from ValidationResults to a boolean.

  • validate_children (bool) – run validation on all child objects. See _validateChildren for documentation on what this entails.

  • stop_on_fail (bool) – stop validation when first failure is encountered

Returns

if silent is False, returns the validation results. If silent is True, returns a boolean generated by reportValidation.

Return type

ValidationResults or bool

sender(self) QObject
senderSignalIndex(self) int
setCallbacks(messaging_callback=None, settings_callback=None)
setCustomName(name)

Sets a custom name for the next task to be run.

Parameters

name (str) – the custom name. Pass in an empty string to return to standard naming.

setObjectName(self, name: str)
setParent(self, a0: QObject)
setProperty(self, name: str, value: Any) bool
setRunnerOptions()

Optional override to set options for the runner. Not overriding this at all results in using all default values.

self.allow custom_name - whether name is user-editable. Default: False

self.allow_concurrent - whether another task can be started while one is still running. Default: True

self.history_length - how many past jobs to keep track of. Default: 5

self.base_name - the base for task names. The base name gets modified to generate unique task names. Ex. MyTask_3. Default: “task”

self.runner_name - a name to describe the type of task. Equivalent to program_name for jobs. Default: ‘task’

settings()
showMessage(message_type, text, options=None)

Communicates with the parent object via the messaging_callback. This method generally doesn’t need to be called; call error, warning, question, or info instead.

Parameters
  • message_type (int) – the type of message to send

  • text (str) – the main text of the message

  • options (dict) – a dictionary of other options to be processed by the messaging_callback.

signalsBlocked(self) bool
start()

Starts the task. This includes the preliminary work of calling preValidate() and running validation before attempting to actually start the task itself.

The actual starting of the task should be handled in the _start method in the derived classes and will vary depening on the type of runner.

startFailed
startRequested
startTimer(self, interval: int, timerType: Qt.TimerType = Qt.CoarseTimer) int
stateChanged
staticMetaObject = <PyQt6.QtCore.QMetaObject object>
status(text, timeout=3000, color=None)

Request a status message to be displayed by the runner’s parent.

Parameters
  • text (str) – the text to display

  • timeout (int) – duration in ms to display the status. A timeout of 0 results in a permanent message.

  • color (QtGui.QColor) – color of the status message.

taskEnded
taskStarted
tasks()
thread(self) QThread
timerEvent(self, a0: QTimerEvent)
tr(sourceText: str, disambiguation: typing.Optional[str] = None, n: int = - 1) str
updateStatusText()

Override this to update the status, for example, when settings have changed or the current task runner is switched.

warning(text, caption='Warning')
class schrodinger.ui.qt.appframework2.tasks.ThreadWrapper(task, settings=None, name='', test_mode=False)

Bases: schrodinger.ui.qt.appframework2.tasks.AbstractTaskWrapper

Wraps a QtCore.QThread to present a common task API.

TASK_CLASS

alias of PyQt6.QtCore.QThread

__init__(task, settings=None, name='', test_mode=False)
Parameters
  • task (see derived class) – the underlying task object (depends on subclass)

  • name (str) – the task name

  • settings (dict) – the settings used to run this task

  • test_mode (bool) – disables type-checking of the task object. Used for mocking that task in tests

getName()
setName(name)
settings()

Returns the settings that were used to run this task.

status()

The current status of the task. The schema is flexible and can be agreed upon with the corresponding runner.

isRunning()

Whether this task is currently running.