Validation API

ValidationError

ValidationError is part of the validators module, but is so commonly used when implementing custom validation that it’s exposed as part of the top-level newforms API.

class ValidationError(message[, kwargs])

A validation error, containing validation messages.

Single messages (e.g. those produced by validators) may have an associated error code and error message parameters to allow customisation by fields.

Arguments:
  • message

    the message argument can be a single error, a list of errors, or an object that maps field names to lists of errors.

    What we define as an “error” can be either a simple string or an instance of ValidationError with its message attribute set, and what we define as list or object can be an actual list or object, or an instance of ValidationError with its errorList or errorObj property set.

  • kwargs (Object) – validation error options.
  • kwargs.code (String) – a code identifying the type of single message this validation error is.
  • kwargs.params (Object) – parameters to be interpolated into the validation error message. where the message contains curly-bracketed {placeholders} for parameter properties.

Prototype Functions

ValidationError#messageObj()

Returns validation messages as an object with field names as properties.

Throws an error if this validation error was not created with a field error object.

ValidationError#messages()

Returns validation messages as a list. If the ValidationError was constructed with an object, its error messages will be flattened into a list.

Errors

Validation errors for a whole form are held in an ErrorObject, while each field’s validation errors are (by default) held im an ErrorList.

class ErrorObject()

A collection of field errors that knows how to display itself in various formats.

Static Functions

ErrorObject.fromJSON(jsonObj[, errorConstructor])

Creates a new ErrorObject and populates it from an object with the same structure as that produced by this object’s toJSON() method.

Arguments:
  • jsonObj (Object) –
  • errorConstructor (Function) – Constructor for creating field errors - defaults to ErrorList().

Prototype Functions

ErrorObject#set(fieldName, errors)

Sets a field’s errors.

Arguments:
  • fieldName (String) –
  • errors (ErrorList) – validation errors for the field.
ErrorObject#get(fieldName)

Gets a field’s errors.

Arguments:
  • fieldName (String) –
ErrorObject#remove(fieldName)

Removes errors for a field.

Arguments:
  • fieldName (String) –
Returns Boolean:
 

true if there were errors for the field.

ErrorObject#removeAll(fieldNames)

Removes errors for multiple fields.

Arguments:
  • fieldNames (Array) –
ErrorObject#hasField(fieldName)
Arguments:
  • fieldName (String) –
Returns Boolean:
 

true if errors have been set for the given field.

ErrorObject#length()

Returns the number of fields errors have been set for.

ErrorObject#isPopulated()
Returns Boolean:
 true if any fields have validation errors set.
ErrorObject#render([kwargs])

Default rendering is as a <ul>. See below for arguments.

ErrorObject#asUl([kwargs])

Displays error details as a <ul>. Returns undefined if this object isn’t populated with any errors.

Arguments:
  • kwargs (Object) – rendering options, which are as follows:
  • kwargs.className (Object) – CSS class name(s) for the <ul>, defaults to 'errorlist'.
ErrorObject#asText()

Displays error details as text.

ErrorObject#asData()

Creates an “unwrapped” version of the data in the ErrorObject - a plain Object with lists of ValidationErrors as its properties.

ErrorObject#toJSON()

Creates a representation of all the contents of the ErrorObject for serialisation, to be called by JSON.stringify() if this object is passed to it.

ErrorObject#fromJSON(jsonObj[, errorConstructor])

Populates this ErrorObject from an object with the same structure as that produced by this object’s toJSON() method.

Arguments:
  • jsonObj (Object) –
  • errorConstructor (Function) – Constructor for creating field errors - defaults to ErrorList().
class ErrorList(list)

A list of errors which knows how to display itself in various formats.

Static Functions

ErrorList.fromJSON(jsonList)

Creates a new ErrorList and populates it from a list with the same structure as that produced by this object’s toJSON() method.

Prototype Functions

ErrorList#extend(errorList)

Adds more errors from the given list.

ErrorList#first()

Returns the first error message held in the list, or undefined if the list was empty.

New in version 0.9.

ErrorList#messages()

Returns the list of error messages held in the list, converting them from ValidationErrors to strings first if necessary.

ErrorList#length()

Returns the number of errors in the list.

ErrorList#isPopulated()

Returns true if the list contains any errors.

ErrorList#first()

Returns the first error message in the list.

ErrorList#messages()

Returns all error message in the list.

ErrorObject#render([kwargs])

Default rendering is as a <ul>. See below for arguments.

ErrorObject#asUl([kwargs])

Displays error details as a <ul>. Returns undefined if this object isn’t populated with any errors.

Arguments:
  • kwargs (Object) – rendering options, which are as follows:
  • kwargs.className (Object) – CSS class name(s) for the <ul>, defaults to 'errorlist'.
ErrorList#render([kwargs])

Default rendering is as a <ul>. See below for arguments.

ErrorList#asUl([kwargs])

Displays errors as a <ul>. Returns undefined if this list isn’t populated with any errors.

Arguments:
  • kwargs (Object) – rendering options, which are as follows:
  • kwargs.className (Object) – CSS class name(s) for the <ul>, defaults to 'errorlist'.
ErrorList#asText()

Displays errors as text.

ErrorList#asData()

Creates an “unwrapped” version of the data in the ErrorList - a plain Array containing ValidationErrors.

ErrorList#toJSON()

Creates a representation of all the contents of the ErrorList for serialisation, to be called by JSON.stringify() if this object is passed to it.

ErrorList#fromJSON(jsonList)

Populates this ErrorList from a list with the same structure as that produced by this object’s toJSON() method.

Validators

Newforms depends on the validators module and exposes its version of it as forms.validators.

Constructors in the validators module are actually validation function factories – they can be called with or without new and will return a Function which performs the configured validation when called.

class RegexValidator(kwargs)

Creates a validator which validates that input matches a regular expression.

Arguments:
  • kwargs (Object) – validator options, which are as follows:
  • kwargs.regex (RegExp or String) – the regular expression pattern to search for the provided value, or a pre-compiled RegExp. By default, matches any string (including an empty string)
  • kwargs.message (String) – the error message used by ValidationError if validation fails. Defaults to "Enter a valid value".
  • kwargs.code (String) – the error code used by ValidationError if validation fails. Defaults to "invalid".
  • kwargs.inverseMatch (Boolean) – the match mode for regex. Defaults to false.
class URLValidator(kwargs)

Creates a validator which validates that input looks like a valid URL.

Arguments:
  • kwargs (Object) – validator options, which are as follows:
  • kwargs.schemes (Array.<String>) – allowed URL schemes. Defaults to ['http', 'https', 'ftp', 'ftps'].
class EmailValidator(kwargs)

Creates a validator which validates that input looks like a valid e-mail address.

Arguments:
  • kwargs (Object) – validator options, which are as follows:
  • kwargs.message (String) – error message to be used in any generated ValidationError.
  • kwargs.code (String) – error code to be used in any generated ValidationError.
  • kwargs.whitelist (Array.<String>) – a whitelist of domains which are allowed to be the only thing to the right of the @ in a valid email address – defaults to ['localhost'].
validateEmail(value)

Validates that input looks like a valid e-mail address – this is a preconfigured instance of an EmailValidator().

validateSlug(value)

Validates that input consists of only letters, numbers, underscores or hyphens.

validateIPv4Address(value)

Validates that input looks like a valid IPv4 address.

validateIPv6Address(value)

Validates that input is a valid IPv6 address.

validateIPv46Address(value)

Validates that input is either a valid IPv4 or IPv6 address.

validateCommaSeparatedIntegerList(value)

Validates that input is a comma-separated list of integers.

class MaxValueValidator(maxValue)

Throws a ValidationError with a code of 'maxValue' if its input is greater than maxValue.

class MinValueValidator(minValue)

Throws a ValidationError with a code of 'minValue' if its input is less than maxValue.

class MaxLengthValidator(maxLength)

Throws a ValidationError with a code of 'maxLength' if its input’s length is greater than maxLength.

class MinLengthValidator(minLength)

Throws a ValidationError with a code of 'minLength' if its input’s length is less than minLength.