schrodinger.ui.qt.appframework2.validation module¶

schrodinger.ui.qt.appframework2.validation.cast_validation_result(result)¶

Casts the result of a validation method into a ValidationResult instance

Parameters: result (bool or (bool, str) or schrodinger.ui.qt.appframework2.validation.ValidationResult) – The result of a validation check
Returns: A ValidationResult instance
Return type: schrodinger.ui.qt.appframework2.validation.ValidationResult

schrodinger.ui.qt.appframework2.validation.validator(validation_order=100)¶

Decorator function to mark a method as a validation test and define the order in which is should be called. Validation order is optional and relative only to the other validation methods within a class instance.

When the decorated method is called, the original method’s result is cast to a ValidationResult. This makes it a bit more natural to test validation objects. A ValidationResult object evaluates to True or False depending on whether the validation succeeded or not.

schrodinger.ui.qt.appframework2.validation.multi_validator(validation_order=100)¶: Use this decorator to mark methods that need to return multiple validation results. This may be a list of validator return values (e.g. bool or (bool, str)) or may be yielded from a generator.

schrodinger.ui.qt.appframework2.validation.add_validator(obj, validator_func, validation_order=100)¶

Function that allows validators to be added dynamically at runtime. See the validator decorator for more information.

Note

The validator_func is not bound to obj. If you want it to behave like a method (ie take in obj as its first argument), then the validator_func should be cast using types.MethodType(obj, validator_func).

Warning

The validator is added as an attribute to obj using the name of the validator function. This means that any attributes or methods with the same name will be overwritten.

Parameters

obj (object) – An instance of a class that subclasses ValidationMixin.
validator_func (callable) – A function to use as a validator. The function should return a bool or a tuple consisting of a bool and a string.
validation_order (int) – The order to call validator_func. This number is used relative to other validators’ validation_order values.

schrodinger.ui.qt.appframework2.validation.remove_validator(obj, validator_func)¶

This function is the inverse of add_validator. Note that this should only be used with validators that were added wtih add_validator, not validators that were built into a class using the @validator decorator.

Parameters

obj (object) – An instance of a class that subclasses ValidationMixin.
validator_func (callable) – A function that’s been added as a validator to obj.

class schrodinger.ui.qt.appframework2.validation.ValidationMixin¶

Bases: object

This mix-in provides validation functionality to other classes, including the ability to designate methods as validation methods, which will be called when the validate method is invoked. These methods can be designated using the validator decorator.

To enable validation functionality in a class, this mix-in can be inherited as an additional parent class. It expects to be inherited by a class that has defined error and question methods, e.g. a class that also inherits from widgetmixins.MessageBoxMixin.

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

reportValidation(results)¶

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

This method assumes that error and question methods have been defined in the subclass, as in e.g. widget_mixins.MessageBoxMixin.

Parameters: results (validation.ValidationResults) – Set of validation results generated by validate
Returns: if True, there were no validation errors and the user decided to continue despite any warnings. If False, there was at least one validation error or the user decided to abort when faced with a warning.

schrodinger.ui.qt.appframework2.validation.find_validators(obj)¶

Searches through the methods on an object and finds methods that have been decorated with the @validator decorator.

Parameters: obj (object) – the object containing validator methods
Returns: the validator methods, sorted by validation_order
Return type: list of callable

schrodinger.ui.qt.appframework2.validation.validate_obj(obj, stop_on_fail=False)¶

Runs validation on an object containing validator methods. Will not recursively validate child objects.

Parameters

obj (object) – the object to be validated.
stop_on_fail (bool) – whether to stop validation at the first failure

Returns

the validation results

Return type

ValidationResults

class schrodinger.ui.qt.appframework2.validation.ValidationResult(passed=True, message=None)¶

Bases: object

A class to store a single validation result.

__init__(passed=True, message=None)¶

If passed is True and there is a message, this is generally interpreted as a warning.

Parameters

passed (bool) – Whether validation passed
message (str) – Message to present to user, if applicable

class schrodinger.ui.qt.appframework2.validation.ValidationResults(iterable=(), /)¶

Bases: list, object

A class to store validation results. This class can store multiple results, and has methods for iterating through the results.

Inherits from object in order to fix issues from python 3 transition

add(result)¶

Adds another result or list of validation results to the list. A list of results must be of the ValidationResults type. Single results to add can be given in several ways.

A ValidationResult can be added.

A tuple consisting of a (bool, message) will be converted into a ValidationResult.

Any other value that has a bool value will be converted into a ValidationResult with no message.

Parameters: result (ValidationResult, ValidationResults, tuple, or any type with a truth value.) – The result(s) to be added