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

__contains__(key, /)

Return key in self.

__init__(*args, **kwargs)
__len__()

Return len(self).

append(object, /)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable, /)

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)

Insert object before index.

pop(index=- 1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.