In pycerberus “Validators” are used to specify validation rules which ensure that the input matches your expectations. Every basic validator validates a just single value (e.g. one specific input field in a web application). When the validation was successful, the validated and converted value is returned. If something is wrong with the data, an exception is raised:
from pycerberus.validators import IntegerValidator
IntegerValidator().process('42') # returns 42 as int
pycerberus puts conversion and validation together in one call because of two main reasons:
Every validation error will trigger an exception, usually an InvalidDataError. This exception will contain a translated error message which can be presented to the user, a key so you can identify the exact error programmatically and the original, unmodified value:
from pycerberus.errors import InvalidDataError
from pycerberus.validators import IntegerValidator
try:
IntegerValidator().process('foo')
except InvalidDataError, e:
details = e.details()
details.msg() # u'Please enter a number.'
details.key() # 'invalid_number'
details.value() # 'foo'
details.context() # {}
You can configure the behavior of the validator when instantiating it. For example, if you pass required=False to the constructor, most validators will also accept None as a valid value:
IntegerValidator(required=True).process(None) # -> validation error
IntegerValidator(required=False).process(None) # None
Validators support different configuration options which are explained along the validator description.
All validators support an optional context argument (which defaults to an emtpy dict). It is used to plug validators into your application and make them aware of the overall system state: For example a validator must know which locale it should use to translate an error message to the correct language without relying on some global variables:
context = {'locale': 'de'}
validator = IntegerValidator()
validator.process('foo', context=context) # u'Bitte geben Sie eine Zahl ein.'
The context variable is especially useful when writing custom validators - locale is the only context information that pycerberus itself cares about.