Colander

==================

- Make it possible to use ``colander.null`` as a ``missing`` argument
to ``colander.SchemaNode`` for roundtripping purposes.

- Make it possible to pickle ``colander.null``.

=====

A release centered around normalizing the treatment of default and
missing values.

Bug Fixes
---------

- Allow ``colander.Regex`` validator to accept a pattern object
instead of just a string.

- Get rid of circular reference in Invalid exceptions: Invalid
exceptions now no longer have a ``parent`` attribute. Instead, they
have a ``positional`` attribute, which signifies that the parent
node type of the schema node to which they relate inherits from
Positional. This attribute isn't an API; it's used only internally
for reporting.

- Raise a ``TypeError`` when bogus keyword arguments are passed to
``colander.SchemaNode``.

Backwards Incompatiblities / New Features
-----------------------------------------

- ``missing`` constructor arg to SchemaNode: signifies
*deserialization* default, disambiguated from ``default`` which acted
as both serialization and deserialization default previously.

Changes necessitated / made possible by SchemaNode ``missing``
addition:

- The ``allow_empty`` argument of the ``colander.String`` type was
removed (use ``missing=''`` as a wrapper SchemaNode argument
instead).

- New concept: ``colander.null`` input to serialization and
deserialization. Use of ``colander.null`` normalizes serialization
and deserialization default handling.

Changes necessitated / made possible by ``colander.null`` addition:

- ``partial`` argument and attribute of colander.MappingSchema has
been removed; all serializations are partial, and partial
deserializations are not necessary.

- ``colander.null`` values are added to the cstruct for partial
serializations instead of omitting missing node values from
the cstruct.

- ``colander.null`` may now be present in serialized and
deserialized data structures.

- ``sdefault`` attribute of SchemaNode has been removed; we never need
to serialize a default anymore.

- The value ``colander.null`` will be passed as ``appstruct`` to
each type's ``serialize`` method when a mapping appstruct doesn't
have a corresponding key instead of ``None``, as was the practice
previously.

- The value ``colander.null`` will be passed as ``cstruct`` to
each type's ``deserialize`` method when a mapping cstruct
doesn't have a corresponding key instead of ``None``, as was the
practice previously.

- Types now must handle ``colander.null`` explicitly during
serialization.

- Updated and expanded documentation, particularly with respect to new
``colander.null`` handling.

- The ``value`` argument to the ``serialize`` method of a SchemaNode
is now named ``appstruct``. It is no longer a required argument; it
defaults to ``colander.null`` now.

The ``value`` argument to the ``deserialize`` method of a SchemaNode
is now named ``cstruct``. It is no longer a required argument; it
defaults to ``colander.null`` now.

- The ``value`` argument to the ``serialize`` method of each built-in
type is now named ``appstruct``, and is now required: it is no
longer a keyword argument that has a default.

The ``value`` argument to the ``deserialize`` method of each
built-in type is now named ``cstruct``, and is now required: it is
no longer a keyword argument that has a default.

==================

- The default ``encoding`` parameter value to the ``colander.String``
type is still ``None``, however its meaning has changed. An
encoding of ``None`` now means that no special encoding and decoding
of Unicode values is done by the String type. This differs from the
previous behavior, where ``None`` implied that the encoding was
``utf-8``. Pass the encoding as ``utf-8`` specifically to get the
older behavior back. This is in support of Deform.

- The default ``err_template`` value attached to the ``colander.Date``
and ``colander.Datetime`` types was changed. It is now simply
``Invalid date`` instead of ``_('${val} cannot be parsed as an
iso8601 date: ${err}')``. This is in support of Deform.

- Fix bug in ``colander.Boolean`` that attempted to call ``.lower`` on
a bool value when a default value was found for the schema node.

==================

- Add a Decimal type (number type which uses ``decimal.Decimal`` as a
deserialization target).

==================

- (Hopefully) fix intermittent datetime-granularity-related test
failures.

- Internationalized error messages. This required some changes to
error message formatting, which may impact you if you were feeding
colander an error message template.

- New project dependency: ``translationstring`` package for
internationalization.

- New argument to ``colander.String`` constructor: ``allow_empty``.
This is a boolean representing whether an empty string is a valid
value during deserialization, defaulting to ``False``.

- Add minimal documentation about the composition of a
colander.Invalid exception to the narrative docs.

- Add (existing, but previously non-API) colander.Invalid attributes
to its interface within the API documentation.

==================

- Add Email and Regex validators (courtesy Steve Howe).

- Raise a ``colander.Invalid`` error if a ``colander.SequenceSchema``
is created with more than one member.

- Add ``Function`` validator.

- Fix bug in serialization of non-Unicode values in the ``String`` class.

- Get rid of ``pserialize`` in favor of making ``serialize`` always
partially serialize.

- Get rid of ``pdeserialize``: it existed only for symmetry. We'll
add something like it back later if we need it.