Extending Cerberus
==================

Though you can use functions in conjunction with the ``coerce`` and the
``check_with`` rules, you can easily extend the :class:`~cerberus.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 :ref:`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:

.. testcode::

    schema = {'amount': {'is odd': True, 'type': 'integer'}}

This is how we would go to implement that:

.. testcode::

    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 :class:`~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:

.. doctest::

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


.. _new-types:

Custom Data Types
-----------------
Cerberus supports and validates several standard data types (see :ref:`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
:class:`~cerberus.TypeDefinition` to the designated type name in
:attr:`~cerberus.Validator.types_mapping`:

.. testcode::

    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 :class:`~cerberus.Validator`:

.. testcode::

    from decimal import Decimal

    decimal_type = cerberus.TypeDefinition('decimal', (Decimal,), ())

    class MyValidator(Validator):
        types_mapping = Validator.types_mapping.copy()
        types_mapping['decimal'] = decimal_type


.. versionadded:: 0.0.2

.. versionchanged:: 1.0
   The type validation logic changed, see :doc:`upgrading`.

.. versionchanged:: 1.2
   Added the :attr:`~cerberus.Validator.types_mapping` property and marked
   methods for testing types as deprecated.

.. _check-with-rule-methods:

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
:ref:`check_with rule <check-with-rule>`.

One is by extending :class:`~cerberus.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:

.. testcode::

    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:

.. testcode::

    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-coercer:

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_``.

.. testcode::

    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

.. doctest::

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

.. testcode::

    from datetime import datetime

    class MyNormalizer(Validator):
        def _normalize_default_setter_utcnow(self, document):
            return datetime.utcnow()

.. doctest::

   >>> 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
:class:`~cerberus.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:

.. testcode::

    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.

.. versionadded:: 0.9

There's a function :func:`~cerberus.utils.validator_factory` to get a
:class:`Validator` mutant with concatenated docstrings.

.. versionadded:: 1.0


Relevant `Validator`-attributes
-------------------------------
There are some attributes of a :class:`~cerberus.Validator` that you should be
aware of when writing custom Validators.

`Validator.document`
~~~~~~~~~~~~~~~~~~~~

A validator accesses the :attr:`~cerberus.Validator.document` property when
fetching fields for validation. It also allows validation of a field to happen
in context of the rest of the document.

.. versionadded:: 0.7.1

`Validator.schema`
~~~~~~~~~~~~~~~~~~

Alike, the :attr:`~cerberus.Validator.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
    :class:`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 :class:`~cerberus.errors.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 :meth:`~cerberus.Validator._error` with two
mandatory arguments:

  - the field where the error occurred
  - an instance of a :class:`~cerberus.errors.ErrorDefinition`

For custom rules you need to define an error as ``ErrorDefinition`` with a
unique id and the causing rule that is violated. See :mod:`~cerberus.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 :py:meth:`str.format`. Serializing handlers will keep
these values in a list.

.. versionadded:: 1.0

Simple custom errors
....................
A simpler form is to call :meth:`~cerberus._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 :class:`~cerberus.errors.ValidationError` instances.

.. versionadded:: 1.0

`Validator._get_child_validator`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you need another instance of your :class:`~cerberus.Validator`-subclass, the
:meth:`~cerberus.Validator._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.

.. versionadded:: 0.9

.. versionchanged:: 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.

.. versionadded:: 1.0

.. versionchanged:: 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.

.. versionadded:: 1.0

`Validator.recent_error`
~~~~~~~~~~~~~~~~~~~~~~~~

The last single error that was submitted is accessible through the
``recent_error``-attribute.

.. versionadded:: 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 :meth:`~cerberus.Validator._drop_remaining_rules`
to remove particular rules or all at once.

.. versionadded:: 1.0

.. versionchanged:: 1.2
    Added ``_remaining_rules`` for extended leverage.