1   Introduction

Validation is used to check that supplied values conform to a specification.

The value can be supplied as a string, e.g. from a config file. In this case the check will also convert the value to the required type. This allows you to add validation as a transparent layer to access data stored as strings. The validation checks that the data is correct and converts it to the expected type.

Checks are also strings, and are easy to write. One generic system can be used to validate information from different sources via a single consistent mechanism.

Checks look like function calls, and map to function calls. They can include parameters and keyword arguments. These arguments are passed to the relevant function by the Validator instance, along with the value being checked.

The syntax for checks also allows for specifying a default value. This default value can be None, no matter what the type of the check. This can be used to indicate that a value was missing, and so holds no useful value.

Functions either return a new value, or raise an exception. See Validator Exceptions for the low down on the exception classes that validate.py defines.

Some standard functions are provided, for basic data types; these come built into every validator. Additional checks are easy to write: they can be provided when the Validator is instantiated, or added afterwards.

Validate was primarily written to support ConfigObj, but is designed to be applicable to many other situations.

For support and bug reports please use the ConfigObj Mailing List.

2   Downloading

The current version is 1.0.1, dated 9th January 2010.

You can get obtain validate in the following ways :

3   The standard functions

The standard functions come built-in to every Validator instance. They work with the following basic data types :

• integer
• float
• boolean
• string
• ip_addr

plus lists of these datatypes.

Adding additional checks is done through coding simple functions.

The full set of standard checks are :

integer()
integer(3, 9)    # any value from 3 to 9
integer(min=0) # any positive value
integer(max=9)

false, off, no, 0

int, str, boolean, float, ip_addr

mixed_list(str, str, int, int)

option('option 1', 'option 2', 'option 3')

The following code will work without you having to specifically add the functions yourself.

from validate import Validator
#
vtor = Validator()
newval1 = vtor.check('integer', value1)
newval2 = vtor.check('boolean', value2)
# etc ...

4   Using Validator

Using Validator is very easy. It has one public attribute and one public method.

Shown below are the different steps in using Validator.

The only additional thing you need to know, is about Writing check functions.

from validate import Validator
vtor = Validator()

from validate import Validator
#
fdict = {
    'check_name1': function1,
    'check_name2': function2,
    'check_name3': function3,
}
#
vtor = Validator(fdict)

from validate import Validator
#
vtor = Validator()
vtor.functions['check_name1'] = function1
vtor.functions['check_name2'] = function2
vtor.functions['check_name3'] = function3

keyword = int_list(max=6)

from validate import Validator, ValidateError
#
vtor = Validator()
check = "integer(0, 9)"
value = 3
try:
    newvalue = vtor.check(check, value)
except ValidateError:
    print 'Check Failed.'
else:
    print 'Check passed.'

check1 = 'integer(default=50)'
check2 = 'option("val 1", "val 2", "val 3", default="val 1")'

assert vtor.check(check1, '', missing=True) == 50
assert vtor.check(check2, '', missing=True) == "val 1"

checkname(default=list('val1', 'val2', 'val3'))

5   Validator Exceptions

vtor.check indicates that the check has failed by raising an exception. The appropriate error should be raised in the check function.

The base error class is ValidateError. All errors (except for VdtParamError) raised are sub-classes of this.

If an unrecognised check is specified then VdtUnknownCheckError is raised.

There are also VdtTypeError and VdtValueError.

If incorrect parameters are passed to a check function then it will (or should) raise VdtParamError. As this indicates programmer error, rather than an error in the value, it is a subclass of SyntaxError instead of ValidateError.

If the value supplied is the wrong type, then the check should raise VdtTypeError. e.g. the check requires the value to be an integer (or representation of an integer) and something else was supplied.

If the value supplied is the right type, but an unacceptable value, then the check should raise VdtValueError. e.g. the check requires the value to be an integer (or representation of an integer) less than ten and a higher value was supplied.

Both VdtTypeError and VdtValueError are initialised with the incorrect value. In other words you raise them like this :

raise VdtTypeError(value)
#
raise VdtValueError(value)

VdtValueError has the following subclasses, which should be raised if they are more appropriate.

• VdtValueTooSmallError
• VdtValueTooBigError
• VdtValueTooShortError
• VdtValueTooLongError

6   Writing check functions

Writing check functions is easy.

The check function will receive the value as its first argument, followed by any other parameters and keyword arguments.

If the check fails, it should raise a VdtTypeError or a VdtValueError (or an appropriate subclass).

All parameters and keyword arguments are always passed as strings. (Parsed from the check string).

The value might be a string (or list of strings) and need converting to the right type - alternatively it might already be a list of integers. Our function needs to be able to handle either.

If the check passes then it should return the value (possibly converted to the right type).

And that's it !

def special_list(value, length):
    """
    Check that the supplied value is a list of integers,
    with 'length' entries, and each entry between 0 and 99.
    """
    # length is supplied as a string
    # we need to convert it to an integer
    try:
        length = int(length)
    except ValueError:
        raise VdtParamError('length', length)
    #
    # Check the supplied value is a list
    if not isinstance(value, list):
        raise VdtTypeError(value)
    #
    # check the length of the list is correct
    if len(value) > length:
        raise VdtValueTooLongError(value)
    elif len(value) < length:
        raise VdtValueTooShortError(value)
    #
    # Next, check every member in the list
    # converting strings as necessary
    out = []
    for entry in value:
        if not isinstance(entry, (str, unicode, int)):
            # a value in the list
            # is neither an integer nor a string
            raise VdtTypeError(value)
        elif isinstance(entry, (str, unicode)):
            if not entry.isdigit():
                raise VdtTypeError(value)
            else:
                entry = int(entry)
        if entry < 0:
            raise VdtValueTooSmallError(value)
        elif entry > 99:
            raise VdtValueTooBigError(value)
        out.append(entry)
    #
    # if we got this far, all is well
    # return the new list
    return out

7   Known Issues

The following parses and then blows up. The resulting error message is confusing:

checkname(default=list(1, 2, 3, 4)

This is because it parses as: checkname(default="list(1", 2, 3, 4). That isn't actually unreasonable, but the error message won't help you work out what has happened.

8   TODO

• A regex check function ?
• A timestamp check function ? (Using the parse function from DateUtil perhaps).

9   ISSUES

If we could pull tuples out of arguments, it would be easier to specify arguments for 'mixed_lists'.

10   CHANGELOG

default=list("val", "val", "val")