Edit me on GitHub

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 at 0x7fa9091a7a80>)

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.

Table Of Contents

Previous topic

Interfaces

Next topic

Glossary