formencode.schema – Validate complete forms

Module Contents

class formencode.schema.Schema(*args, **kw)

A schema validates a dictionary of values, applying different validators (be key) to the different values. If allow_extra_fields=True, keys without validators will be allowed; otherwise they will raise Invalid. If filter_extra_fields is set to true, then extra fields are not passed back in the results.

Validators are associated with keys either with a class syntax, or as keyword arguments (class syntax is usually easier). Something like:

class MySchema(Schema):
    name = Validators.PlainText()
    phone = Validators.PhoneNumber()

These will not be available as actual instance variables, but will be collected in a dictionary. To remove a validator in a subclass that is present in a superclass, set it to None, like:

class MySubSchema(MySchema):
    name = None

Note that missing fields are handled at the Schema level. Missing fields can have the ‘missing’ message set to specify the error message, or if that does not exist the schema message ‘missingValue’ is used.

Messages

badDictType:

The input must be dict-like (not a %(type)s: %(value)r)

badType:

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

empty:

Please enter a value

missingValue:

Missing value

noneType:

The input must be a string (not None)

notExpected:

The input field %(name)s was not expected.

singleValueExpected:

Please provide only one value

class formencode.schema.SimpleFormValidator(*args, **kw)

This validator wraps a simple function that validates the form.

The function looks something like this:

>>> def validate(form_values, state, validator):
...     if form_values.get('country', 'US') == 'US':
...         if not form_values.get('state'):
...             return dict(state='You must enter a state')
...     if not form_values.get('country'):
...         form_values['country'] = 'US'

This tests that the field ‘state’ must be filled in if the country is US, and defaults that country value to ‘US’. The validator argument is the SimpleFormValidator instance, which you can use to format messages or keep configuration state in if you like (for simple ad hoc validation you are unlikely to need it).

To create a validator from that function, you would do:

>>> from formencode.schema import SimpleFormValidator
>>> validator = SimpleFormValidator(validate)
>>> validator.to_python({'country': 'US', 'state': ''}, None)
Traceback (most recent call last):
    ...
Invalid: state: You must enter a state
>>> sorted(validator.to_python({'state': 'IL'}, None).items())
[('country', 'US'), ('state', 'IL')]

The validate function can either return a single error message (that applies to the whole form), a dictionary that applies to the fields, None which means the form is valid, or it can raise Invalid.

Note that you may update the value_dict in place, but you cannot return a new value.

Another way to instantiate a validator is like this:

>>> @SimpleFormValidator.decorate()
... def MyValidator(value_dict, state):
...     return None # or some more useful validation

After this MyValidator will be a SimpleFormValidator instance (it won’t be your function).

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)