Colander API

Exceptions

class colander.Invalid(node, msg=None, value=None)

An exception raised by data types and validators indicating that the value for a particular node was not valid.

The constructor receives a mandatory node argument. This must be an instance of the colander.SchemaNode class, or at least something with the same interface.

The constructor also receives an optional msg keyword argument, defaulting to None. The msg argument is a freeform field indicating the error circumstance.

The constructor additionally may receive an optional value keyword, indicating the value related to the error.

pos

An integer representing the position of this exception’s schema node relative to all other child nodes of this exception’s parent schema node. For example, if this exception is related to the third child node of its parent’s schema, pos might be the integer 3. pos may also be None, in which case this exception is the root exception.

children

A list of child exceptions. Each element in this list (if any) will also be an colander.Invalid exception, recursively, representing the error circumstances for a particular schema deserialization.

msg

A str or unicode object, or a translation string instance representing a freeform error value set by a particular type during an unsuccessful deserialization. If this exception is only structural (only exists to be a parent to some inner child exception), this value will be None.

node

The schema node to which this exception relates.

value

An attribute not used internally by Colander, but which can be used by higher-level systems to attach arbitrary values to Colander exception nodes. For example, In the system named Deform, which uses Colander schemas to define HTML form renderings, the value is used when raising an exception from a widget as the value which should be redisplayed when an error is shown.

add(exc, pos=None)

Add a child exception; exc must be an instance of colander.Invalid or a subclass.

pos is a value important for accurate error reporting. If it is provided, it must be an integer representing the position of exc relative to all other subexceptions of this exception node. For example, if the exception being added is about the third child of the exception which is self, pos might be passed as 3.

If pos is provided, it will be assigned to the pos attribute of the provided exc object.

asdict(translate=None)

Return a dictionary containing a basic (non-language-translated) error report for this exception.

If translate is supplied, it must be a callable taking a translation string as its sole argument and returning a localized, interpolated string.

messages()

Return an iterable of error messages for this exception using the msg attribute of this error node. If the msg attribute is iterable, it is returned. If it is not iterable, and is non-None, a single-element list containing the msg value is returned. If the value is None, an empty list is returned.

paths()

A generator which returns each path through the exception graph. Each path is represented as a tuple of exception nodes. Within each tuple, the leftmost item will represent the root schema node, the rightmost item will represent the leaf schema node.

Validators

class colander.All(*validators)

Composite validator which succeeds if none of its subvalidators raises an colander.Invalid exception

class colander.Any(*validators)

Composite validator which succeeds if at least one of its subvalidators does not raise an colander.Invalid exception.

class colander.Range(min=None, max=None, min_err=None, max_err=None)

Validator which succeeds if the value it is passed is greater or equal to min and less than or equal to max. If min is not specified, or is specified as None, no lower bound exists. If max is not specified, or is specified as None, no upper bound exists.

min_err is used to form the msg of the colander.Invalid error when reporting a validation failure caused by a value not meeting the minimum. If min_err is specified, it must be a string. The string may contain the replacement targets ${min} and ${val}, representing the minimum value and the provided value respectively. If it is not provided, it defaults to '${val} is less than minimum value ${min}'.

max_err is used to form the msg of the colander.Invalid error when reporting a validation failure caused by a value exceeding the maximum. If max_err is specified, it must be a string. The string may contain the replacement targets ${max} and ${val}, representing the maximum value and the provided value respectively. If it is not provided, it defaults to '${val} is greater than maximum value ${max}'.

class colander.Length(min=None, max=None)

Validator which succeeds if the value passed to it has a length between a minimum and maximum. The value is most often a string.

class colander.OneOf(choices)

Validator which succeeds if the value passed to it is one of a fixed set of values

class colander.ContainsOnly(choices)

Validator which succeeds if the value passed to is a sequence and each element in the sequence is also in the sequence passed as choices. This validator is useful when attached to a schemanode with, e.g. a colander.Set or another sequencetype.

class colander.Function(function, msg=None, message=None)

Validator which accepts a function and an optional message; the function is called with the value during validation.

If the function returns anything falsy (None, False, the empty string, 0, an object with a __nonzero__ that returns False, etc) when called during validation, an colander.Invalid exception is raised (validation fails); its msg will be the value of the msg argument passed to this class’ constructor.

If the function returns a stringlike object (a str or unicode object) that is not the empty string , a colander.Invalid exception is raised using the stringlike value returned from the function as the exeption message (validation fails).

If the function returns anything except a stringlike object object which is truthy (e.g. True, the integer 1, an object with a __nonzero__ that returns True, etc), an colander.Invalid exception is not raised (validation succeeds).

The default value for the msg when not provided via the constructor is Invalid value.

class colander.Regex(regex, msg=None)

Regular expression validator.

Initialize it with the string regular expression regex that will be compiled and matched against value when validator is called. If msg is supplied, it will be the error message to be used; otherwise, defaults to ‘String does not match expected pattern’.

The regex argument may also be a pattern object (the result of re.compile) instead of a string.

When calling, if value matches the regular expression, validation succeeds; otherwise, colander.Invalid is raised with the msg error message.

class colander.Email(msg=None)

Email address validator. If msg is supplied, it will be the error message to be used when raising colander.Invalid; otherwise, defaults to ‘Invalid email address’.

colander.luhnok(node, value)

Validator which checks to make sure that the value passes a luhn mod-10 checksum (credit cards). value must be a string, not an integer.

colander.url

A validator which ensures the value is a URL (via regex).

Types

class colander.Mapping(unknown='ignore')

A type which represents a mapping of names to nodes.

The subnodes of the colander.SchemaNode that wraps this type imply the named keys and values in the mapping.

The constructor of this type accepts one extra optional keyword argument that other types do not: unknown. An attribute of the same name can be set on a type instance to control the behavior after construction.

unknown

unknown controls the behavior of this type when an unknown key is encountered in the cstruct passed to the deserialize method of this instance. All the potential values of unknown are strings. They are:

• ignore means that keys that are not present in the schema associated with this type will be ignored during deserialization.
• raise will cause a colander.Invalid exception to be raised when unknown keys are present in the cstruct during deserialization.
• preserve will preserve the ‘raw’ unknown keys and values in the appstruct returned by deserialization.

Default: ignore.

Special behavior is exhibited when a subvalue of a mapping is present in the schema but is missing from the mapping passed to either the serialize or deserialize method of this class. In this case, the colander.null value will be passed to the serialize or deserialize method of the schema node representing the subvalue of the mapping respectively. During serialization, this will result in the behavior described in Serializing The Null Value for the subnode. During deserialization, this will result in the behavior described in Deserializing The Null Value for the subnode.

If the colander.null value is passed to the serialize method of this class, a dictionary will be returned, where each of the values in the returned dictionary is the serialized representation of the null value for its type.

class colander.Tuple

A type which represents a fixed-length sequence of nodes.

The subnodes of the colander.SchemaNode that wraps this type imply the positional elements of the tuple in the order they are added.

This type is willing to serialize and deserialized iterables that, when converted to a tuple, have the same number of elements as the number of the associated node’s subnodes.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

class colander.Set

A type representing a non-overlapping set of items. Deserializes an iterable to a set object.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

class colander.List

Type representing an ordered sequence of items.

Desrializes an iterable to a list object.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

class colander.Sequence(accept_scalar=False)

A type which represents a variable-length sequence of nodes, all of which must be of the same type.

The type of the first subnode of the colander.SchemaNode that wraps this type is considered the sequence type.

The optional accept_scalar argument to this type’s constructor indicates what should happen if the value found during serialization or deserialization does not have an __iter__ method or is a mapping type.

If accept_scalar is True and the value does not have an __iter__ method or is a mapping type, the value will be turned into a single element list.

If accept_scalar is False and the value does not have an __iter__ method or is a mapping type, an colander.Invalid error will be raised during serialization and deserialization.

The default value of accept_scalar is False.

If the colander.null value is passed to the serialize method of this class, the colander.null value is returned.

colander.Seq

alias of Sequence

class colander.String(encoding=None)

A type representing a Unicode string.

This type constructor accepts one argument:

encoding

Represents the encoding which should be applied to value serialization and deserialization, for example utf-8. If encoding is passed as None, the serialize method of this type will not do any special encoding of the appstruct it is provided, nor will the deserialize method of this type do any special decoding of the cstruct it is provided; inputs and outputs will be assumed to be Unicode. encoding defaults to None.

If encoding is None:

• A Unicode input value to serialize is returned untouched.
• A non-Unicode input value to serialize is run through the unicode() function without an encoding parameter (unicode(value)) and the result is returned.
• A Unicode input value to deserialize is returned untouched.
• A non-Unicode input value to deserialize is run through the unicode() function without an encoding parameter (unicode(value)) and the result is returned.

If encoding is not None:

• A Unicode input value to serialize is run through the unicode function with the encoding parameter (unicode(value, encoding)) and the result (a str object) is returned.
• A non-Unicode input value to serialize is converted to a Unicode using the encoding (unicode(value, encoding)); subsequently the Unicode object is reeencoded to a str object using the encoding and returned.
• A Unicode input value to deserialize is returned untouched.
• A non-Unicode input value to deserialize is converted to a str object using str(value). The resulting str value is converted to Unicode using the encoding (unicode(value, encoding)) and the result is returned.

A corollary: If a string (as opposed to a unicode object) is provided as a value to either the serialize or deserialize method of this type, and the type also has an non-None encoding, the string must be encoded with the type’s encoding. If this is not true, an colander.Invalid error will result.

The subnodes of the colander.SchemaNode that wraps this type are ignored.

colander.Str

alias of String

class colander.Integer

A type representing an integer.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

The subnodes of the colander.SchemaNode that wraps this type are ignored.

colander.Int

alias of Integer

class colander.Float

A type representing a float.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

The subnodes of the colander.SchemaNode that wraps this type are ignored.

class colander.Decimal(quant=None, rounding=None)

A type representing a decimal floating point. Deserialization returns an instance of the Python decimal.Decimal type.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

The Decimal constructor takes two optional arguments, quant and rounding. If supplied, quant should be a string, (e.g. 1.00). If supplied, rounding should be one of the Python decimal module rounding options (e.g. decimal.ROUND_UP, decimal.ROUND_DOWN, etc). The serialized and deserialized result will be quantized and rounded via result.quantize(decimal.Decimal(quant), rounding). rounding is ignored if quant is not supplied.

The subnodes of the colander.SchemaNode that wraps this type are ignored.

class colander.Boolean(false_choices=('false', '0'), true_choices=(), false_val='false', true_val='true')

A type representing a boolean object.

The constructor accepts these keyword arguments:

• false_choices: The set of strings representing a False value on deserialization.
• true_choices: The set of strings representing a True value on deserialization.
• false_val: The value returned on serialization of a False value.
• true_val: The value returned on serialization of a True value.

During deserialization, a value contained in false_choices, will be considered False.

The behaviour for values not contained in false_choices depends on true_choices: if it’s empty, any value is considered True; otherwise, only values contained in true_choices are considered True, and an Invalid exception would be raised for values outside of both false_choices and true_choices.

Serialization will produce true_val or false_val based on the value.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

The subnodes of the colander.SchemaNode that wraps this type are ignored.

colander.Bool

alias of Boolean

class colander.GlobalObject(package)

A type representing an importable Python object. This type serializes ‘global’ Python objects (objects which can be imported) to dotted Python names.

Two dotted name styles are supported during deserialization:

• pkg_resources-style dotted names where non-module attributes of a module are separated from the rest of the path using a ‘:’ e.g. package.module:attr.
• zope.dottedname-style dotted names where non-module attributes of a module are separated from the rest of the path using a ‘.’ e.g. package.module.attr.

These styles can be used interchangeably. If the serialization contains a : (colon), the pkg_resources resolution mechanism will be chosen, otherwise the zope.dottedname resolution mechanism will be chosen.

The constructor accepts a single argument named package which should be a Python module or package object; it is used when relative dotted names are supplied to the deserialize method. A serialization which has a . (dot) or : (colon) as its first character is treated as relative. E.g. if .minidom is supplied to deserialize, and the package argument to this type was passed the xml module object, the resulting import would be for xml.minidom. If a relative package name is supplied to deserialize, and no package was supplied to the constructor, an colander.Invalid error will be raised.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

The subnodes of the colander.SchemaNode that wraps this type are ignored.

class colander.DateTime(default_tzinfo=<object object>)

A type representing a Python datetime.datetime object.

This type serializes python datetime.datetime objects to a ISO8601 string format. The format includes the date, the time, and the timezone of the datetime.

The constructor accepts an argument named default_tzinfo which should be a Python tzinfo object. If default_tzinfo is not specified the default tzinfo will be equivalent to UTC (Zulu time). The default_tzinfo tzinfo object is used to convert ‘naive’ datetimes to a timezone-aware representation during serialization. If default_tzinfo is explicitly set to None then no default tzinfo will be applied to naive datetimes.

You can adjust the error message reported by this class by changing its err_template attribute in a subclass on an instance of this class. By default, the err_template attribute is the string Invalid date. This string is used as the interpolation subject of a dictionary composed of val and err. val and err are the unvalidatable value and the exception caused trying to convert the value, respectively. These may be used in an overridden err_template as ${val} and ${err} respectively as necessary, e.g. _('${val} cannot be parsed as an iso8601 date: ${err}').

For convenience, this type is also willing to coerce datetime.date objects to a DateTime ISO string representation during serialization. It does so by using midnight of the day as the time, and uses the default_tzinfo to give the serialization a timezone.

Likewise, for convenience, during deserialization, this type will convert YYYY-MM-DD ISO8601 values to a datetime object. It does so by using midnight of the day as the time, and uses the default_tzinfo to give the serialization a timezone.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

The subnodes of the colander.SchemaNode that wraps this type are ignored.

class colander.Date

A type representing a Python datetime.date object.

This type serializes python datetime.date objects to a ISO8601 string format. The format includes the date only.

The constructor accepts no arguments.

You can adjust the error message reported by this class by changing its err_template attribute in a subclass on an instance of this class. By default, the err_template attribute is the string Invalid date. This string is used as the interpolation subject of a dictionary composed of val and err. val and err are the unvalidatable value and the exception caused trying to convert the value, respectively. These may be used in an overridden err_template as ${val} and ${err} respectively as necessary, e.g. _('${val} cannot be parsed as an iso8601 date: ${err}').

For convenience, this type is also willing to coerce datetime.datetime objects to a date-only ISO string representation during serialization. It does so by stripping off any time information, converting the datetime.datetime into a date before serializing.

Likewise, for convenience, this type is also willing to coerce ISO representations that contain time info into a datetime.date object during deserialization. It does so by throwing away any time information related to the serialized value during deserialization.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

The subnodes of the colander.SchemaNode that wraps this type are ignored.

class colander.Time

A type representing a Python datetime.time object.

Note

This type is new as of Colander 0.9.3.

This type serializes python datetime.time objects to a ISO8601 string format. The format includes the time only.

The constructor accepts no arguments.

You can adjust the error message reported by this class by changing its err_template attribute in a subclass on an instance of this class. By default, the err_template attribute is the string Invalid date. This string is used as the interpolation subject of a dictionary composed of val and err. val and err are the unvalidatable value and the exception caused trying to convert the value, respectively. These may be used in an overridden err_template as ${val} and ${err} respectively as necessary, e.g. _('${val} cannot be parsed as an iso8601 date: ${err}').

For convenience, this type is also willing to coerce datetime.datetime objects to a time-only ISO string representation during serialization. It does so by stripping off any date information, converting the datetime.datetime into a time before serializing.

Likewise, for convenience, this type is also willing to coerce ISO representations that contain time info into a datetime.time object during deserialization. It does so by throwing away any date information related to the serialized value during deserialization.

If the colander.null value is passed to the serialize method of this class, the colander.null value will be returned.

The subnodes of the colander.SchemaNode that wraps this type are ignored.

Schema-Related

class colander.SchemaNode(*arg, **kw)

Fundamental building block of schemas.

The constructor accepts these positional arguments:

• typ: The ‘type’ for this node. It should be an instance of a class that implements the colander.interfaces.Type interface. If typ is not passed, it defaults to colander.Mapping().
• *children: a sequence of subnodes. If the subnodes of this node are not known at construction time, they can later be added via the add method.

The constructor accepts these keyword arguments:

• name: The name of this node.
• typ: The ‘type’ for this node can optionally be passed in as a keyword argument. See the documentation for the positional arg above.
• default: The default serialization value for this node. Default: colander.null.
• missing: The default deserialization value for this node. If it is not provided, the missing value of this node will be the special marker value colander.required, indicating that it is considered ‘required’. When missing is colander.required, the required computed attribute will be True. When missing is colander.drop, the node is dropped from the schema if it isn’t set during serialization/deserialization.
• missing_msg: Optional error message to be used if the value is required and missing.
• preparer: Optional preparer for this node. It should be an object that implements the colander.interfaces.Preparer interface.
• validator: Optional validator for this node. It should be an object that implements the colander.interfaces.Validator interface.
• after_bind: A callback which is called after a clone of this node has ‘bound’ all of its values successfully. This callback is useful for performing arbitrary actions to the cloned node, or direct children of the cloned node (such as removing or adding children) at bind time. A ‘binding’ is the result of an execution of the bind method of the clone’s prototype node, or one of the parents of the clone’s prototype nodes. The deepest nodes in the node tree are bound first, so the after_bind methods of the deepest nodes are called before the shallowest. The after_bind callback should accept two values: node and kw. node will be a clone of the bound node object, kw will be the set of keywords passed to the bind method.
• title: The title of this node. Defaults to a titleization of the name (underscores replaced with empty strings and the first letter of every resulting word capitalized). The title is used by higher-level systems (not by Colander itself).
• description: The description for this node. Defaults to '' (the empty string). The description is used by higher-level systems (not by Colander itself).
• widget: The ‘widget’ for this node. Defaults to None. The widget attribute is not interpreted by Colander itself, it is only meaningful to higher-level systems such as Deform.

Arbitrary keyword arguments remaining will be attached to the node object unmolested.

__delitem__(name)

Remove a subnode by name

__getitem__(name)

Get a subnode by name.

__iter__()

Iterate over the children nodes of this schema node

add(node)

Append a subnode to this node. node must be a SchemaNode.

add_before(name, node)

Insert a subnode into the position before the node named name

bind(**kw)

Resolve any deferred values attached to this schema node and its children (recursively), using the keywords passed as kw as input to each deferred value. This function clones the schema it is called upon and returns the cloned value. The original schema node (the source of the clone) is not modified.

clone()

Clone the schema node and return the clone. All subnodes are also cloned recursively. Attributes present in node dictionaries are preserved.

cstruct_children(cstruct)

Will call the node’s type’s cstruct_children method with this node as a first argument, and cstruct as a second argument.

deserialize(cstruct=<colander.null>)

Deserialize the cstruct into an appstruct based on the schema, run this appstruct through the preparer, if one is present, then validate the prepared appstruct. The cstruct value is deserialized into an appstruct unconditionally.

If appstruct returned by type deserialization and preparation is the value colander.null, do something special before attempting validation:

• If the missing attribute of this node has been set explicitly, return its value. No validation of this value is performed; it is simply returned.
• If the missing attribute of this node has not been set explicitly, raise a colander.Invalid exception error.

If the appstruct is not colander.null and cannot be validated , a colander.Invalid exception will be raised.

If a cstruct argument is not explicitly provided, it defaults to colander.null.

flatten(appstruct)

Create and return a data structure which is a flattened representation of the passed in struct based on the schema represented by this node. The return data structure is a dictionary; its keys are dotted names. Each dotted name represents a path to a location in the schema. The values of of the flattened dictionary are subvalues of the passed in struct.

get(name, default=None)

Return the subnode associated with name or default if no such node exists.

get_value(appstruct, dotted_name)

Traverses the nested data structure using the schema and retrieves the value specified by the dotted name path.

insert(index, node)

Insert a subnode into the position index. node must be a SchemaNode.

raise_invalid(msg, node=None)

Raise a colander.Invalid exception with the message msg. node, if supplied, should be an instance of a colander.SchemaNode. If it is not supplied, node will be this node. Example usage:

class CustomSchemaNode(SchemaNode):
    def validator(self, node, cstruct):
        if cstruct != 'the_right_thing':
            self.raise_invalid('Not the right thing')

required

A property which returns True if the missing value related to this node was not specified.

A return value of True implies that a missing value wasn’t specified for this node or that the missing value of this node is colander.required. A return value of False implies that a ‘real’ missing value was specified for this node.

serialize(appstruct=<colander.null>)

Serialize the appstruct to a cstruct based on the schema represented by this node and return the cstruct.

If appstruct is colander.null, return the serialized value of this node’s default attribute (by default, the serialization of colander.null).

If an appstruct argument is not explicitly provided, it defaults to colander.null.

set_value(appstruct, dotted_name, value)

Uses the schema to set a value in a nested datastructure from a dotted name path.

unflatten(fstruct)

Create and return a data structure with nested substructures based on the schema represented by this node using the flattened representation passed in. This is the inverse operation to colander.SchemaNode.flatten().

class colander.Schema(*arg, **kw)

colander.MappingSchema

alias of Schema

class colander.TupleSchema(*arg, **kw)

class colander.SequenceSchema(*args, **kw)

class colander.deferred(wrapped)

A decorator which can be used to define deferred schema values (missing values, widgets, validators, etc.)

class colander.instantiate(*args, **kw)

A decorator which can be used to instantiate SchemaNode elements inline within a class definition.

All parameters passed to the decorator and passed along to the SchemaNode during instantiation.

colander.null

Represents a null value in colander-related operations.

colander.required

Represents a required value in colander-related operations.

colander.drop

Represents a value that will be dropped from the schema if it is missing during deserialization. Passed as a value to the missing keyword argument of SchemaNode.