Included Validators

Scalars

class Present(**kw)

Bases: flatland.validation.base.Validator

Validates that a value is present.

Messages

missing

Emitted if the u string value of the element is empty, as in the case for an HTML form submitted with an input box left blank.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class IsTrue(**kw)

Bases: flatland.validation.base.Validator

Validates that a value evaluates to true.

Messages

false

Emitted if bool(element.value) is not True.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class IsFalse(**kw)

Bases: flatland.validation.base.Validator

Validates that a value evaluates to false.

Messages

true

Emitted if bool(element.value) is not False.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class ValueIn(valid_options=Unspecified, **kw)

Bases: flatland.validation.base.Validator

Validates that the value is within a set of possible values.

Example:

import flatland
from flatland.validation import ValueIn

is_yesno = ValueIn(valid_options=['yes', 'no'])
schema = flatland.String('yn', validators=[is_yesno])

Attributes

valid_options

A list, set, or other container of valid element values.

Messages

fail

Emitted if the element’s value is not within the valid_options.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class Converted(**kw)

Bases: flatland.validation.base.Validator

Validates that an element was converted to a Python value.

Example:

import flatland
from flatland.validation import Converted

not_bogus = Converted(incorrect='Please enter a valid date.')
schema = flatland.DateTime('when', validators=[not_bogus])

Messages

incorrect

Emitted if the value is None.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class ShorterThan(maxlength=Unspecified, **kw)

Bases: flatland.validation.base.Validator

Validates the length of an element’s string value is less than a bound.

Example:

import flatland
from flatland.validation import ShorterThan

valid_length = ShorterThan(8)
schema = flatland.String('password', validators=[valid_length])

Attributes

maxlength

A maximum character length for the u.

This attribute may be supplied as the first positional argument to the constructor.

Messages

exceeded

Emitted if the length of the element’s string value exceeds maxlength.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
NoLongerThan

alias of flatland.validation.scalars.ShorterThan

class LongerThan(minlength=Unspecified, **kw)

Bases: flatland.validation.base.Validator

Validates the length of an element’s string value is more than a bound.

Example:

import flatland
from flatland.validation import LongerThan

valid_length = LongerThan(4)
schema = flatland.String('password', validators=[valid_length])

Attributes

minlength

A minimum character length for the u.

This attribute may be supplied as the first positional argument to the constructor.

Messages

short

Emitted if the length of the element’s string value falls short of minlength.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class LengthBetween(minlength=Unspecified, maxlength=Unspecified, **kw)

Bases: flatland.validation.base.Validator

Validates the length of an element’s string value is within bounds.

Example:

import flatland
from flatland.validation import LengthBetween

valid_length = LengthBetween(4, 8)
schema = flatland.String('password', validators=[valid_length])

Attributes

minlength

A minimum character length for the u.

This attribute may be supplied as the first positional argument to the constructor.

maxlength

A maximum character length for the u.

This attribute may be supplied as the second positional argument to the constructor.

Messages

breached

Emitted if the length of the element’s string value is less than minlength or greater than maxlength.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class ValueLessThan(boundary, **kw)

Bases: flatland.validation.base.Validator

A validator that ensures that the value is less than a limit.

Example:

import flatland
from flatland.validation import ValueLessThan

schema = flatland.Integer('wishes', validators=[ValueLessThan(boundary=4)])

Attributes

boundary

Any comparable object.

Messages

failure

Emitted if the value is greater than or equal to boundary.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class ValueAtMost(maximum, **kw)

Bases: flatland.validation.base.Validator

A validator that enforces a maximum value.

Example:

import flatland
from flatland.validation import ValueAtMost

schema = flatland.Integer('wishes', validators=[ValueAtMost(maximum=3)])

Attributes

maximum

Any comparable object.

Messages

failure

Emitted if the value is greater than maximum.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class ValueGreaterThan(boundary, **kw)

Bases: flatland.validation.base.Validator

A validator that ensures that a value is greater than a limit.

Example:

import flatland
from flatland.validation import ValueGreaterThan

schema = flatland.Integer('wishes', validators=[ValueGreaterThan(boundary=4)])

Attributes

boundary

Any comparable object.

Messages

failure

Emitted if the value is greater than or equal to boundary.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class ValueAtLeast(minimum, **kw)

Bases: flatland.validation.base.Validator

A validator that enforces a minimum value.

Example:

import flatland
from flatland.validation import ValueAtLeast

schema = flatland.Integer('wishes', validators=[ValueAtLeast(minimum=3)])

Attributes

minimum

Any comparable object.

Messages

failure

Emitted if the value is less than minimum.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class ValueBetween(minimum, maximum, **kw)

Bases: flatland.validation.base.Validator

A validator that enforces minimum and maximum values.

Example:

import flatland
from flatland.validation import ValueBetween

schema = flatland.Integer('wishes',
                         validators=[ValueBetween(minimum=1, maximum=3)])

Attributes

minimum

Any comparable object.

maximum

Any comparable object.

inclusive

Boolean value indicating that minimum and maximum are included in the range. Defaults to True.

Messages

failure_inclusive

Emitted when inclusive is True if the expression minimum <= value <= maximum evaluates to False.

failure_exclusive

Emitted when inclusive is False if the expression minimum < value < maximum evaluates to False.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class MapEqual(*field_paths, **kw)

Bases: flatland.validation.base.Validator

A general field equality validator.

Validates that two or more fields are equal.

Attributes

field_paths

A sequence of field names or field paths. Path names will be evaluated at validation time and relative path names are resolved relative to the element holding this validator. See ValuesEqual for an example.

transform

A 1-arg callable, passed a Element, returning a value for equality testing.

Messages

unequal

Emitted if the transform(element) of all elements are not equal. labels will substitute to a comma-separated list of the label of all but the last element; last_label is the label of the last.

Construct a MapEqual.

Parameters:
  • *field_paths – a sequence of 2 or more elements names or paths.
  • **kw – passed to Validator.__init__().
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class ValuesEqual(*field_paths, **kw)

Bases: flatland.validation.scalars.MapEqual

Validates that the values of multiple elements are equal.

A MapEqual that compares the value of each element.

Example:

from flatland import Schema, String
from flatland.validation import ValuesEqual

class MyForm(Schema):
    password = String
    password_again = String
    validators = [ValuesEqual('password', 'password_again')]
transform

attrgetter(‘value’)

Construct a MapEqual.

Parameters:
  • *field_paths – a sequence of 2 or more elements names or paths.
  • **kw – passed to Validator.__init__().
class UnisEqual(*field_paths, **kw)

Bases: flatland.validation.scalars.MapEqual

Validates that the Unicode values of multiple elements are equal.

A MapEqual that compares the u of each element.

transform

attrgetter(‘u’)

Construct a MapEqual.

Parameters:
  • *field_paths – a sequence of 2 or more elements names or paths.
  • **kw – passed to Validator.__init__().

Containers

class NotDuplicated(**kw)

Bases: flatland.validation.base.Validator

A sequence member validator that ensures all sibling values are unique.

Marks the second and any subsequent occurrences of a value as invalid. Only useful on immediate children of sequence fields such as flatland.List.

Example:

import flatland
from flatland.schema.containers import List
from flatland.validation import NotDuplicated

validator = NotDuplicated(failure="Please enter each color only once.")
schema = List.of(String.named('favorite_color')).\
              using(validators=[validator])

Attributes

comparator

A callable boolean predicate, by default operator.eq. Called positionally with two arguments, element and sibling.

Can be used as a filter, for example ignoring any siblings that have been marked as “deleted” by a checkbox in a web form:

from flatland import Schema, List, String, Integer, Boolean
from flatland.validation import NotDuplicated

def live_addrs(element, sibling):
    thisval, thatval = element.value, sibling.value
    # data marked as deleted is never considered a dupe
    if thisval['deleted'] or thatval['deleted']:
        return False
    # compare elements on 'street' & 'city', ignoring 'id'
    return (thisval['street'] == thatval['street'] and
            thisval['city'] == thatval['city'])

class Address(Schema):
    validators = [NotDuplicated(comparator=live_addrs)]

    id = Integer.using(optional=True)
    deleted = Boolean
    street = String
    city = String

schema = List.of(Address)

Messages

failure

Emitted on an element that has already appeared in a parent sequence. container_label will substitute the label of the container. position is the position of the element in the parent sequence, counting up from 1.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
comparator()

eq(a, b) – Same as a==b.

validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class HasAtLeast(**kw)

Bases: flatland.validation.base.Validator

A sequence validator that ensures a minimum number of members.

May be applied to a sequence type such as a List.

Example:

from flatland import List, String
from flatland.validation import HasAtLeast

schema = List.of(String.named('wish')).\
              using(validators=[HasAtLeast(minimum=3)])

Attributes

minimum

Any positive integer.

Messages

failure

Emitted if the sequence contains less than minimum members. child_label will substitute the label of the child schema.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class HasAtMost(**kw)

Bases: flatland.validation.base.Validator

A sequence validator that ensures a maximum number of members.

May be applied to a sequence type such as a List.

Example:

from flatland import List, String
from flatland.validation import HasAtMost

schema = List.of(String.named('wish')).\
              using(validators=[HasAtMost(maximum=3)])

Attributes

maximum

Any positive integer.

Messages

failure

Emitted if the sequence contains more than maximum members. child_label will substitute the label of the child schema.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class HasBetween(**kw)

Bases: flatland.validation.base.Validator

Validates that the number of members of a sequence lies within a range.

May be applied to a sequence type such as a List.

Example:

from flatland import List, String
from flatland.validation import HasBetween

schema = List.of(String.named('wish')).\
              using(validators=[HasBetween(minimum=1, maximum=3)])

Attributes

minimum

Any positive integer.

maximum

Any positive integer.

Messages

range

Emitted if the sequence contains fewer than minimum members or more than maximum members. child_label will substitute the label of the child schema.

exact

Like range, however this message is emitted if minimum and maximum are the same.

schema = List.of(String.named('wish')).\
              using(validators=[HasBetween(minimum=3, maximum=3)])
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class SetWithKnownFields(**kw)

Bases: flatland.validation.base.Validator

A mapping validator that ensures no unexpected fields were set().

May be applied to a mapping type such as a Dict.

Example:

from flatland import Dict, Integer
from flatland.validation import SetWithKnownFields

schema = Dict.of(Integer.named('x'), Integer.named('y')).\
              validated_by(SetWithKnownFields())
schema.policy = None
element = schema()

element.set({'x': 123, 'y': 456})
assert element.validate()

element.set({'x': 123, 'y': 456, 'z': 789})
assert not element.validate()

#from flatland import Dict, Integer
#from flatland.validation import SetWithKnownFields
#
#schema = Dict.of(Integer.named('x'), Integer.named('y')).\
#              validated_by(SetWithKnownFields())
#schema.policy = None
#element = schema()
#
#element.set({'x': 123})
#assert element.validate()  # assertion error, issue #25, FIXME!
#
#element.set({'x': 123, 'z': 789})
#assert not element.validate()  # no assertion error, but maybe due to #25 also.

This validator collects the keys from raw and compares them to the allowed keys for the element. Only elements in which raw is available and iterable will be considered for validation; all others are deemed valid.

Warning

This validator will not enforce policy on mappings initialized with set_flat() because raw is unset.

Note

This validator obsoletes and deprecates the Dict.policy = 'subset' feature. During the deprecation period, policy is still enforced by set() by default. To allow this validator to run, disable the default by setting policy = None on the element or its schema.

Messages

unexpected

Emitted if the initializing value contains unexpected keys. unexpected will substitute a comma-separated list of unexpected keys, and n_unexpected a count of those keys.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
class SetWithAllFields(**kw)

Bases: flatland.validation.base.Validator

A mapping validator that ensures all fields were set().

May be applied to a mapping type such as a Dict.

Example:

from flatland import Dict, Integer
from flatland.validation import SetWithAllFields

schema = Dict.of(Integer.named('x'), Integer.named('y')).\
              validated_by(SetWithAllFields())
schema.policy = None
element = schema()

element.set({'x': 123, 'y': 456})
assert element.validate()

element.set({'x': 123})
assert not element.validate()

element.set({'x': 123, 'y': 456, 'z': 789})
assert not element.validate()

This validator collects the keys from raw and compares them to the allowed keys for the element. Only elements in which raw is available and iterable will be considered for validation; all others are deemed valid.

Warning

This validator will not enforce policy on mappings initialized with set_flat() because raw is unset.

Note

This validator obsoletes and deprecates the Dict.policy = 'strict' feature. During the deprecation period, policy is still enforced by set() by default. To allow this validator to run, disable the default by setting policy = None on the element or its schema.

Messages

unexpected

Emitted if the initializing value contains unexpected keys. unexpected will substitute a comma-separated list of unexpected keys, and n_unexpected a count of those keys.

missing

Emitted if the initializing value did not contain all expected keys. missing will substitute a comma-separated list of missing keys, and n_missing a count of those keys.

both

Emitted if both of the previous conditions hold, and both sets of substitution keys are available.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid

Numbers

class Luhn10(**kw)

Bases: flatland.validation.base.Validator

True if a numeric value passes luhn10 checksum validation.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
validate(element, state)

Validate an element returning True if valid.

Abstract.

Parameters:
Returns:

True if valid
luhn10_check(number)

Return True if the number passes the Luhn checksum algorithm.

Email Addresses

class IsEmail(**kw)

Bases: flatland.validation.base.Validator

Validates email addresses.

The default behavior takes a very permissive stance on allowed characters in the local-part and a relatively strict stance on the domain. Given local-part@domain:

  • local-part must be present and contain at least one non-whitespace character. Any character is permitted, including international characters.
  • domain must be preset, less than 253 characters and each dot-separated component must be 63 characters or less. domain may contain non-ASCII international characters, and will be converted to IDN representation before length assertions are applied. No top level domain validations are applied.

Attributes

non_local

Default True. When true, require at minimum two domain name components and reject local email addresses such as postmaster@localhost or user@workstation.

local_part_pattern

No default. If present, a compiled regular expression that will be matched to the local-part. Override this to implement more stringent checking such as RFC-compliant addresses.

domain_pattern

Defaults to a basic domain-validating regular expression with no notion of valid top level domains. Override this to require certain TLDs (or alternately and more simply, add another validator to your chain that checks the endings of the string against your list of TLDs.)

The default pattern rejects the valid but obscure quoted IP-address form ([1.2.3.4]).

Messages

invalid

Emitted if the email address is not valid.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.

URLs

class URLValidator(**kw)

Bases: flatland.validation.base.Validator

A general URL validator.

Validates that a URL is well-formed and may optionally restrict the set of valid schemes and other URL components.

Attributes

allowed_schemes

Restrict URLs to just this sequence of named schemes, or allow all schemes with (‘*’,). Defaults to all schemes. Example:

allowed_schemes = ('http', 'https', 'ssh')
allowed_parts

A sequence of 0 or more part names in urlparse’s vocabulary:

'scheme', 'netloc', 'path', 'params', 'query', 'fragment'

Defaults to all parts allowed.

urlparse

By default the urlparse module, but may be replaced by any object that implements urlparse.urlparse() and urlparse.urlunparse().

Messages

bad_format

Emitted for an unparseable URL.

blocked_scheme

Emitted if the URL scheme: is not present in allowed_schemes.

blocked_part

Emitted if the URL has a component not present in allowed_parts.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
class HTTPURLValidator(**kw)

Bases: flatland.validation.base.Validator

Validates http and https URLs.

Validates that an http-like URL is well-formed and may optionally require and restrict the permissible values of its components.

Attributes

all_parts

A sequence of known URL parts. Defaults to the full 10-tuple of names in urlparse’s vocabulary for HTTP-like URLs.

required_parts

A mapping of part names. If value is True, the part is required. The value may also be a sequence of strings; the value of the part must be present in this collection to validate.

The default requires a scheme of 'http' or 'https'.

forbidden_parts

A mapping of part names. If value is True, the part is forbidden and validation fails. The value may also be a sequence of strings; the value of the part must not be present in this collection to validate.

The default forbids username and password parts.

urlparse

By default the urlparse module, but may be replaced by any object that implements urlparse.urlparse() and urlparse.urlunparse().

Messages

bad_format

Emitted for an unparseable URL.

required_part

Emitted if URL is missing a part present in required_parts.

forbidden_part

Emitted if URL contains a part present in forbidden_parts.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.
class URLCanonicalizer(**kw)

Bases: flatland.validation.base.Validator

A URL canonicalizing validator.

Given a valid URL, re-writes it with unwanted parts removed. The default implementation drops the #fragment from the URL, if present.

Attributes

discard_parts

A sequence of 0 or more part names in urlparse’s vocabulary:

'scheme', 'netloc', 'path', 'params', 'query', 'fragment'
urlparse

By default the urlparse module, but may be replaced by any object that implements urlparse.urlparse() and urlparse.urlunparse().

Messages

bad_format

Emitted for an unparseable URL. This is impossible to hit with the Python’s standard library implementation of urlparse.

Construct a validator.

Parameters:**kw – override any extant class attribute on this instance.