Validation¶
Validation is used for type-checking, value coercion, and checking
HasProperties instances are composed correctly. Invalid values raises a
ValueError
. There are three components of validation:
- Property validation - This occurs when the
Property.validate
method is called. It contains Property-specific type checking and coersion. On a HasProperties class, every time a Property value is set, the corresponding validate method is called and the output of the validate function is used for the new Property value. If the value is not valid, aValueError
is raised. - HasProperties property validators - These are callback methods registered
to fire on specific HasProperties-class properties. They are called when the
property is set after Property validation but before the property is
saved (unlike observers which fire after the
value is saved). These validators may perform further type-checking or
coercion that is related to the HasProperties class. See
properties.validator
(Mode 1) for more details on using these validators. Theproperties.validators_disabled
andproperties.listeners_disabled
context managers may be used to disable these validators. - HasProperties class validators - These are callback methods registered to
fire only when
HasProperties.validate
is called. They are used to cross-validate Properties and ensure that a HasProperties instance is correctly constructed. Seeproperties.validator
(Mode 2) for more details on using these validators.
-
properties.
validator
(names_or_instance, names=None, func=None)[source]¶ Specify a callback function to fire on class validation OR property set
This function has two modes of operation:
- Registering callback functions that validate Property values when
they are set, before the change is saved to the HasProperties instance.
This mode is very similar to the
observer
function. - Registering callback functions that fire only when the HasProperties
validate
method is called. This allows for cross-validation of Properties that should only fire when all required Properties are set.
Mode 1:
Validator functions on a HasProperties class fire on set but before the observed Property or Properties have been changed (unlike observer functions that fire after the value has been changed).
You can use this method as a decorator inside a HasProperties class
@properties.validator('variable_name') def callback_function(self, change): print(change)
or you can use it to register a function to a single HasProperties instance
properties.validator(my_has_props, 'variable_name', callback_function)
The variable name must refer to a Property name on the HasProperties class. A list of Property names may also be used; the same callback function will fire when any of these Properties change. Also,
properties.everything
may be specified instead of the variable name. In that case, the callback function will fire when any Property changes.The callback function must take two arguments. The first is the HasProperties instance; the second is the change notification dictionary. This dictionary contains:
- ‘name’ - the name of the changed Property
- ‘previous’ - the value of the Property prior to change (this will be
properties.undefined
if the value was not previously set) - ‘value’ - the new value of the Property (this will be
properties.undefined
if the value is deleted) - ‘mode’ - the mode of the change; for validators, this is ‘validate’
Mode 2:
When used as a decorator without arguments (i.e. called directly on a HasProperties method), the decorated method is registered as a class validator. These methods execute only when
validate()
is called on the HasProperties instance.@properties.validator def validation_method(self): print('validating instance of {}'.format(self.__class__))
The decorated function must only take one argument, the HasProperties instance.
- Registering callback functions that validate Property values when
they are set, before the change is saved to the HasProperties instance.
This mode is very similar to the
-
class
properties.
validators_disabled
[source]¶ Context manager for disabling all property change validators
This context manager behaves like
properties.listeners_disabled
, but only affects HasProperties methods decorated with@validator