Basic Validation — flatland 0.8.1 documentation

# Basic Validation

All elements support validation. The default, built-in validation logic is simple: if the element is empty, it is invalid. Otherwise it is valid.

If that sounds too simple don’t worry- you can customize validation to suit your needs.

## Validating an Element

    >>> from flatland import String
    >>> form = String()
    >>> form.is_empty
    True
    >>> form.valid
    Unevaluated
    >>> form.validate()
    False
    >>> form.valid
    False

Validation sets the `valid` attribute of each element it inspects. `validate()` may be invoked more than once.

    >>> form.set('Squiznart')
    True
    >>> form.is_empty
    False
    >>> form.validate()
    True
    >>> form.valid
    True

Note that default validation does not set any error messages that might be displayed to an interactive user. Messages are easily added through custom validation.

## Validating Entire Forms At Once

`validate()` is recursive by default. Called on a parent node, it will descend through all of its children, validating each. If the parent or any one of its children are invalid, `validate` returns false. Note that recursion does not stop if it finds an invalid child: all children are evaluated, and each will have its `valid` attribute updated.

## Optional Elements

If an element is marked as `optional`, it is exempt from validation when empty. With the default validation strategy, this effectively means that element can never be invalid. With custom validation, optional fields become more useful.

    >>> from flatland import Dict, Integer
    >>> schema = Dict.of(Integer.named('x'),
    ...                  Integer.named('y'),
    ...                  Integer.named('z').using(optional=True))
    >>> form = schema(dict(x=1))
    >>> form.validate()
    False
    >>> form.valid
    True
    >>> form['x'].valid
    True
    >>> form['y'].valid
    False
    >>> form['z'].valid
    True

## Validation Signals

The `flatland.signals.validator_validated` signal is emitted each time a validator evaluates an element. The signal’s sender is the validator (or the symbol `flatland.validation.NotEmpty` for the default validation strategy). The signal also sends the `element`, the `state`, and the `result` of the validation function.

During development, it can be convenient to connect the `validator_validated` signal to a logging function to aid in debugging.

    from flatland.signals import validator_validated

    @validator_validated.connect
    def monitor_validation(sender, element, state, result):
        # print or logging.debug validations as they happen:
        print "validation: %s(%s) valid == %r" % (
          sender, element.flattened_name(), result)

    >>> from flatland import String
    >>> form = String(name='surname')
    >>> form.validate()
    validation: NotEmpty(surname) valid == False
    False