Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
163 lines (122 sloc) 5.72 KB

Extending Colander

You can extend Colander by defining a new :term:`type` or by defining a new :term:`validator`.

Defining a New Type

A new type is a class with two methods:: serialize and deserialize. serialize converts a Python data structure (an :term:`appstruct`) into a serialization (a :term:`cstruct`). deserialize converts a serialized value (a :term:`cstruct`) into a Python data structure (a :term:`appstruct`).

Here's a type which implements boolean serialization and deserialization. It serializes a boolean to the string true or false or the special :attr:`colander.null` sentinel; it then deserializes a string (presumably true or false, but allows some wiggle room for t, on, yes, y, and 1) to a boolean value.

Note that the deserialize method of a type does not need to explicitly deserialize the :attr:`colander.null` value. Deserialization of the null value is dealt with at a higher level (with the :meth:`colander.SchemaNode.deserialize` method); a type will never receive an :attr:`colander.null` value as a cstruct argument to its deserialize method.

Here's how you would use the resulting class as part of a schema:

The above schema has a member named interested which will now be serialized and deserialized as a boolean, according to the logic defined in the Boolean type class.

Note that the only two real constraints of a type class are:

  • it must deal specially with the value :attr:`colander.null` within serialize, translating it to a type-specific null value.
  • its serialize method must be able to make sense of a value generated by its deserialize method and vice versa, except that the deserialize method needn't deal with the :attr:`colander.null` value specially even if the serialize method returns it.

The serialize method of a type accepts two values: node, and appstruct. node will be the schema node associated with this type. It is used when the type must raise a :exc:`colander.Invalid` error, which expects a schema node as its first constructor argument. appstruct will be the :term:`appstruct` value that needs to be serialized.

The deserialize and method of a type accept two values: node, and cstruct. node will be the schema node associated with this type. It is used when the type must raise a :exc:`colander.Invalid` error, which expects a schema node as its first constructor argument. cstruct will be the :term:`cstruct` value that needs to be deserialized.

A type class does not need to implement a constructor (__init__), but it isn't prevented from doing so if it needs to accept arguments; Colander itself doesn't construct any types, only users of Colander schemas do, so how types are constructed is beyond the scope of Colander itself.

The :exc:`colander.Invalid` exception may be raised during serialization or deserialization as necessary for whatever reason the type feels appropriate (the inability to serialize or deserialize a value being the most common case).

For a more formal definition of a the interface of a type, see :class:`colander.interfaces.Type`.

Defining a New Validator

A validator is a callable which accepts two positional arguments: node and value. It returns None if the value is valid. It raises a :class:`colander.Invalid` exception if the value is not valid. Here's a validator that checks if the value is a valid credit card number.

Here's how the resulting luhnok validator might be used in a schema:

Note that the validator doesn't need to check if the value is a string: this has already been done as the result of the type of the cc_number schema node being :class:`colander.String`. Validators are always passed the deserialized value when they are invoked.

The node value passed to the validator is a schema node object; it must in turn be passed to the :exc:`colander.Invalid` exception constructor if one needs to be raised.

For a more formal definition of a the interface of a validator, see :class:`colander.interfaces.Validator`.

Jump to Line
Something went wrong with that request. Please try again.