Extending Cerberus¶
Though you can use functions in conjunction with the coerce
and the
check_with
rules, you can easily extend the Validator
class with custom rules
, types
, check_with
handlers, coercers
and default_setters
.
While the function-based style is more suitable for special and one-off uses,
a custom class leverages these possibilities:
custom rules can be defined with constrains in a schema
extending the available type s
use additional contextual data
schemas are serializable
The references in schemas to these custom methods can use space characters
instead of underscores, e.g. {'foo': {'check_with': 'is odd'}}
is an alias
for {'foo': {'check_with': 'is_odd'}}
.
Custom Rules¶
Suppose that in our use case some values can only be expressed as odd integers,
therefore we decide to add support for a new is_odd
rule to our validation
schema:
schema = {'amount': {'is odd': True, 'type': 'integer'}}
This is how we would go to implement that:
from cerberus import Validator
class MyValidator(Validator):
def _validate_is_odd(self, constraint, field, value):
""" Test the oddity of a value.
The rule's arguments are validated against this schema:
{'type': 'boolean'}
"""
if constraint is True and not bool(value & 1):
self._error(field, "Must be an odd number")
By subclassing Cerberus Validator
class and adding the custom
_validate_<rulename>
method, we just enhanced Cerberus to suit our needs.
The custom rule is_odd
is now available in our schema and, what really
matters, we can use it to validate all odd values:
>>> v = MyValidator(schema)
>>> v.validate({'amount': 10})
False
>>> v.errors
{'amount': ['Must be an odd number']}
>>> v.validate({'amount': 9})
True
As schemas themselves are validated, you can provide constraints as literal
Python expression in the docstring of the rule’s implementing method to
validate the arguments given in a schema for that rule. Either the docstring
contains solely the literal or the literal is placed at the bottom of the
docstring preceded by
The rule's arguments are validated against this schema:
See the source of the contributed rules for more examples.
Custom Data Types¶
Cerberus supports and validates several standard data types (see type). When building a custom validator you can add and validate your own data types.
Additional types can be added on the fly by assigning a
TypeDefinition
to the designated type name in
types_mapping
:
from decimal import Decimal
decimal_type = cerberus.TypeDefinition('decimal', (Decimal,), ())
Validator.types_mapping['decimal'] = decimal_type
Caution
As the types_mapping
property is a mutable type, any change to its
items on an instance will affect its class.
They can also be defined for subclasses of Validator
:
from decimal import Decimal
decimal_type = cerberus.TypeDefinition('decimal', (Decimal,), ())
class MyValidator(Validator):
types_mapping = Validator.types_mapping.copy()
types_mapping['decimal'] = decimal_type
Added in version 0.0.2.
Changed in version 1.0: The type validation logic changed, see Upgrading to Cerberus 1.0.
Changed in version 1.2: Added the types_mapping
property and marked
methods for testing types as deprecated.
Methods that can be referenced by the check_with rule¶
If a validation test doesn’t depend on a specified constraint from a schema or needs to be more complex than a rule should be, it’s possible to rather define it as value checker than as a rule. There are two ways to use the check_with rule.
One is by extending Validator
with a method prefixed with
_check_with_
. This allows to access the whole context of the validator
instance including arbitrary configuration values and state. To reference such
method using the check_with
rule, simply pass the unprefixed method name as
a string constraint.
For example, one can define an oddity
validator method as follows:
class MyValidator(Validator):
def _check_with_oddity(self, field, value):
if not value & 1:
self._error(field, "Must be an odd number")
Usage would look something like:
schema = {'amount': {'type': 'integer', 'check_with': 'oddity'}}
The second option to use the rule is to define a standalone function and pass
it as the constraint. This brings with it the benefit of not having to extend
Validator
. To read more about this implementation and see examples check
out the rule’s documentation.
Custom Coercers¶
You can also define custom methods that return a coerce
d value or point to
a method as rename_handler
. The method name must be prefixed with
_normalize_coerce_
.
class MyNormalizer(Validator):
def __init__(self, multiplier, *args, **kwargs):
super(MyNormalizer, self).__init__(*args, **kwargs)
self.multiplier = multiplier
def _normalize_coerce_multiply(self, value):
return value * self.multiplier
>>> schema = {'foo': {'coerce': 'multiply'}}
>>> document = {'foo': 2}
>>> MyNormalizer(multiplier=2).normalized(document, schema)
{'foo': 4}
Custom Default Setters¶
Similar to custom rename handlers, it is also possible to create custom default setters.
from datetime import datetime
class MyNormalizer(Validator):
def _normalize_default_setter_utcnow(self, document):
return datetime.utcnow()
>>> schema = {'creation_date': {'type': 'datetime', 'default_setter': 'utcnow'}}
>>> MyNormalizer().normalized({}, schema)
{'creation_date': datetime.datetime(...)}
Limitations¶
It may be a bad idea to overwrite particular contributed rules.
Attaching Configuration Data And Instantiating Custom Validators¶
It’s possible to pass arbitrary configuration values when instantiating a
Validator
or a subclass as keyword arguments (whose names
are not used by Cerberus). These can be used in all of the handlers described
in this document that have access to the instance.
Cerberus ensures that this data is available in all child instances that may
get spawned during processing. When you implement an __init__
method on
a customized validator, you must ensure that all positional and keyword
arguments are also passed to the parent class’ initialization method. Here’s
an example pattern:
class MyValidator(Validator):
def __init__(self, *args, **kwargs):
# assign a configuration value to an instance property
# for convenience
self.additional_context = kwargs.get('additional_context')
# pass all data to the base classes
super(MyValidator, self).__init__(*args, **kwargs)
# alternatively a dynamic property can be defined, rendering
# the __init__ method unnecessary in this example case
@property
def additional_context(self):
return self._config.get('additional_context', 'bar')
# an optional property setter if you deal with state
@additional_context.setter
def additional_context(self, value):
self._config["additional_context"] = value
def _check_with_foo(self, field, value):
make_use_of(self.additional_context)
Warning
It is neither recommended to access the _config
property in other
situations than outlined in the sketch above nor to to change its contents
during the processing of a document. Both cases are not tested and are
unlikely to get officially supported.
Added in version 0.9.
There’s a function validator_factory()
to get a
Validator
mutant with concatenated docstrings.
Added in version 1.0.
Relevant Validator-attributes¶
There are some attributes of a Validator
that you should be
aware of when writing custom Validators.
Validator.document¶
A validator accesses the document
property when
fetching fields for validation. It also allows validation of a field to happen
in context of the rest of the document.
Added in version 0.7.1.
Validator.schema¶
Alike, the schema
property holds the used schema.
Note
This attribute is not the same object that was passed as schema
to the
validator at some point. Also, its content may differ, though it still
represents the initial constraints. It offers the same interface like a
dict
.
Validator._error¶
There are three signatures that are accepted to submit errors to the
Validator
’s error stash. If necessary the given information will be parsed
into a new instance of ValidationError
.
Full disclosure¶
In order to be able to gain complete insight into the context of an error at a
later point, you need to call _error()
with two
mandatory arguments:
the field where the error occurred
an instance of a
ErrorDefinition
For custom rules you need to define an error as ErrorDefinition
with a
unique id and the causing rule that is violated. See errors
for a list of the contributed error definitions. Keep in mind that bit 7 marks
a group error, bit 5 marks an error raised by a validation against different
sets of rules.
Optionally you can submit further arguments as information. Error handlers
that are targeted for humans will use these as positional arguments when
formatting a message with str.format()
. Serializing handlers will keep
these values in a list.
Added in version 1.0.
Simple custom errors¶
A simpler form is to call _error()
with the field and a string
as message. However the resulting error will contain no information about the
violated constraint. This is supposed to maintain backward compatibility, but
can also be used when an in-depth error handling isn’t needed.
Multiple errors¶
When using child-validators, it is a convenience to submit all their errors
; which is a list of ValidationError
instances.
Added in version 1.0.
Validator._get_child_validator¶
If you need another instance of your Validator
-subclass, the
_get_child_validator()
-method returns another
instance that is initiated with the same arguments as self
was. You can
specify overriding keyword-arguments.
As the properties document_path
and schema_path
(see below) are
inherited by the child validator, you can extend these by passing a single
value or values-tuple with the keywords document_crumb
and
schema_crumb
.
Study the source code for example usages.
Added in version 0.9.
Changed in version 1.0: Added document_crumb
and schema_crumb
as optional keyword-
arguments.
Validator.root_document, .root_schema, .root_allow_unknown & .root_require_all¶
A child-validator - as used when validating a schema
- can access the first
generation validator’s document and schema that are being processed as well as
the constraints for unknown fields via its root_document
, root_schema
,
root_allow_unknown
and root_require_all
properties.
Added in version 1.0.
Changed in version 1.3: Added root_require_all
Validator.document_path & Validator.schema_path¶
These properties maintain the path of keys within the document respectively the schema that was traversed by possible parent-validators. Both will be used as base path when an error is submitted.
Added in version 1.0.
Validator.recent_error¶
The last single error that was submitted is accessible through the
recent_error
-attribute.
Added in version 1.0.
Validator.mandatory_validations, Validator.priority_validations & Validator._remaining_rules¶
You can use these class properties and instance instance property if you want
to adjust the validation logic for each field validation.
mandatory_validations
is a tuple that contains rules that will be validated
for each field, regardless if the rule is defined for a field in a schema or
not.
priority_validations
is a tuple of ordered rules that will be validated
before any other.
_remaining_rules
is a list that is populated under consideration of these
and keeps track of the rules that are next in line to be evaluated. Thus it can
be manipulated by rule handlers to change the remaining validation for the
current field.
Preferably you would call _drop_remaining_rules()
to remove particular rules or all at once.
Added in version 1.0.
Changed in version 1.2: Added _remaining_rules
for extended leverage.