Document deferred validators with new API

[leplatrem]

In Cornice 1.2 the schema was bound to the request before validation (for deferred fields).
https://github.com/Cornices/cornice/blob/1.2.1/cornice/schemas.py#L35
#288
https://github.com/Cornices/cornice/blob/1.2.1/cornice/tests/test_schemas.py#L62-L65

Now, it can be achieve just this way:

def bound_schema_validator(request, **kwargs):
    schema  = kwargs['schema']
    kwargs['schema'] = schema.bind(request=request)
    return colander_validator(request, **kwargs)

[dairiki]

I don't think this quite works, at the moment.

Colander_validator currently wants a schema class. (It calls it to instantiate a schema object.)
https://github.com/Cornices/cornice/blob/master/cornice/validators/_colander.py#L65

(It could be argued that colander_validator should be expecting a schema instance rather than a class.)

[leplatrem]

You're right, and I can't say why schema is expected to be a class to be honest :|

We could test if schema is a class here: https://github.com/Cornices/cornice/blob/master/cornice/validators/_colander.py#L65 and adjust the above snippet.
That's still a lot lighter that the 1.2 approach with the optional bind_request parameter.

What do you think?

[dairiki]

I think changing colander_validator so that it can accept a schema instance is a good idea. (Note that schema instances can be constructed imperatively, too, in which case there is no corresponding schema class.)

My personal preference would be to deprecate passing a schema class, so as to encourage consistency about always passing a schema node (instance). (As an example to emulate, deform.Form only accepts an instance, not a schema class.)

[leplatrem]

Sounds like a plan! ;)