Using Validators

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:

• As a user you need to convert input data (usually strings) anyway into a more sensible format (e.g. int). These lines of code are redundant because you declared in the validator already what the value should be.
• During the validation process, it is very easy to do also the conversion. In fact many validations are done just by trying to do a conversion and catch all exceptions that were raised during that process.

Validation Errors

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()     # {}

Configuring Validators

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.

Context

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.