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:

  1. 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, a ValueError is raised.
  2. 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. The properties.validators_disabled and properties.listeners_disabled context managers may be used to disable these validators.
  3. 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. See properties.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:

  1. 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.
  2. 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.

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