formencode.api – Core classes for validation

Core classes for validation.

Module Contents

formencode.api.is_empty(value)

Check whether the given value should be considered “empty”.

formencode.api.is_validator(obj)

Check whether obj is a Validator instance or class.

class formencode.api.NoDefault

A dummy value used for parameters with no default.

class formencode.api.Invalid(msg, value, state, error_list=None, error_dict=None)

This is raised in response to invalid input. It has several public attributes:

msg:

The message, without values substituted. For instance, if you want HTML quoting of values, you can apply that.

substituteArgs:

The arguments (a dictionary) to go with msg.

str(self):

The message describing the error, with values substituted.

value:

The offending (invalid) value.

state:

The state that went with this validator. This is an application-specific object.

error_list:

If this was a compound validator that takes a repeating value, and sub-validator(s) had errors, then this is a list of those exceptions. The list will be the same length as the number of values – valid values will have None instead of an exception.

error_dict:

Like error_list, but for dictionary compound validators.

class formencode.api.Validator(*args, **kw)

The base class of most validators. See IValidator for more, and FancyValidator for the more common (and more featureful) class.

Messages

formencode.api.Identity

class formencode.api.FancyValidator(*args, **kw)

FancyValidator is the (abstract) superclass for various validators and converters. A subclass can validate, convert, or do both. There is no formal distinction made here.

Validators have two important external methods:

.to_python(value, state):

Attempts to convert the value. If there is a problem, or the value is not valid, an Invalid exception is raised. The argument for this exception is the (potentially HTML-formatted) error message to give the user.

.from_python(value, state):

Reverses .to_python().

These two external methods make use of the following four important internal methods that can be overridden. However, none of these have to be overridden, only the ones that are appropriate for the validator.

._convert_to_python(value, state):

This method converts the source to a Python value. It returns the converted value, or raises an Invalid exception if the conversion cannot be done. The argument to this exception should be the error message. Contrary to .to_python() it is only meant to convert the value, not to fully validate it.

._convert_from_python(value, state):

Should undo ._convert_to_python() in some reasonable way, returning a string.

._validate_other(value, state):

Validates the source, before ._convert_to_python(), or after ._convert_from_python(). It’s usually more convenient to use ._validate_python() however.

._validate_python(value, state):

Validates a Python value, either the result of ._convert_to_python(), or the input to ._convert_from_python().

You should make sure that all possible validation errors are raised in at least one these four methods, not matter which.

Subclasses can also override the __init__() method if the declarative.Declarative model doesn’t work for this.

Validators should have no internal state besides the values given at instantiation. They should be reusable and reentrant.

All subclasses can take the arguments/instance variables:

if_empty:

If set, then this value will be returned if the input evaluates to false (empty list, empty string, None, etc), but not the 0 or False objects. This only applies to .to_python().

not_empty:

If true, then if an empty value is given raise an error. (Both with .to_python() and also .from_python() if ._validate_python is true).

strip:

If true and the input is a string, strip it (occurs before empty tests).

if_invalid:

If set, then when this validator would raise Invalid during .to_python(), instead return this value.

if_invalid_python:

If set, when the Python value (converted with .from_python()) is invalid, this value will be returned.

accept_python:

If True (the default), then ._validate_python() and ._validate_other() will not be called when .from_python() is used.

These parameters are handled at the level of the external methods .to_python() and .from_python already; if you overwrite one of the internal methods, you usually don’t need to care about them.

Messages

badType:

The input must be a string (not a %(type)s: %(value)r)

empty:

Please enter a value

noneType:

The input must be a string (not None)