naval 0.8.0

Range

>>> Range(5, 10).validate(7)
7

>>> Range(5, 10).validate(-16)
...
ValidationError: The minimum is 5.

Length

>>> Length(max=3).validate(['one', 'two', 'three'])
['one', 'two', 'three']

>>> Length(max=3).validate(['one', 'two', 'three', 'four'])
ValidationError: The value is too long. Max length is 3.

# customizing the error message
>>> Length(max=3, too_long_error="Please, no more than {max_length} items").validate(
        ['one', 'two', 'three', 'four']
    )
...
ValidationError: Please, no more than 3 items

Type

>>> Type(int, float).validate(3.14)
3.14

By default, the type must match exactly. Use subclasses = True to allow for subclasses.

>>> from collections import OrderedDict

>>> Type(dict).validate(OrderedDict([('a', 1), ('b', 2)]))
...
ValidationError: Wrong type. Expected dict. Got OrderedDict instead.

>>> Type(dict, subclasses = True).validate(OrderedDict([('a', 1), ('b', 2)]))
OrderedDict([('a', 1), ('b', 2)])

Regex

The pattern must match exactly, from the beginning to the end of the string.

>>> Regex('[A-Za-z][-_A-Za-z0-9]+').validate('TheKing!!!')
...
ValidationError: Incorrect value.

>>> Regex('[A-Za-z][-_A-Za-z0-9]+').validate('TheKing')
'TheKing'

Email

Email validator.

Internally, this filter uses the email validation function from the validators library: https://github.com/kvesteri/validators

>>> Email.validate('email@example.com')
'email@example.com'

>>> Email.validate('user@92.80.0.1')
...
ValidationError: This is not a valid email address.

Url

Url validator. The regex used to validate urls was borrowed from the Spoon php library: http://spoon-library.be

>>> Url.validate('http://www.example.com/v1/?sort=asc')
'http://www.example.com/v1/?sort=asc'

>>> Url.validate('http://0.0.0.0')
...
ValidationError: This is not a valid url.

Domain

Domain name validator.

Internally, this filter uses the domain name validation function from the validators library: https://github.com/kvesteri/validators

>>> Domain.validate('example.com')
'example.com'

>>> Domain.validate('example.com/')
...
ValidationError: This is not a valid domain name.

Assert

Assert builds a filter from a boolean function.

>>> only_digits = Assert(str.isdigit, error_message = "Only digits are allowed")

>>> only_digits.validate('12345')
'12345'

>>> only_digits.validate('12-345')
...
ValidationError: Only digits are allowed

Apply

Apply applies a function to its argument and returns the result. By default, it will reraise any exception as a ValidationError, but you can specify what kind of exception (if any) is expected.

>>> hex_to_int = Apply(lambda h: int(h, 16))

>>> hex_to_int.validate('aa')
170

>>> hex_to_int.validate('zz')
...
ValidationError: invalid literal for int() with base 16: 'zz'

You rarely have to use Apply inside a Schema, because any callable is converted implicitly to an Apply filter.

forum_post = Schema(
    ['title', Length(max=100), str.lower, str.capitalize, Save],
    ['post', Length(max=4000)]
)

However, it can sometimes be useful to explicitly use Apply to customize the error message, or to specify exactly what kind of exception is expected.

>>> import numpy as np
>>> matrix_inverter = Schema(
        ['matrix',
            np.array,
            Apply(
                np.linalg.inv,
                catch = (np.linalg.LinAlgError,),
                error_message = "Please supply an invertible square matrix"
            ),
            (lambda mat: mat.tolist()),
            MoveTo('inverse')
        ]
    )

This example uses three Apply filters. np.array and (lambda mat: mat.tolist()) are implicitly converted to Apply filters by the Schema constructor.

>>> matrix_inverter.validate({'matrix': [[1,1],[1,0]]})
{'inverse': [[0.0, 1.0], [1.0, -1.0]]}

>>> matrix_inverter.validate({'matrix': [[1,1],[1,1]]})
...
ValidationError: {'matrix': 'Please supply an invertible square matrix', 'inverse': "Couldn't compute field."}

In

>>> In(['red', 'blue', 'yellow']).validate('blue')
'blue'

>>> In(['red', 'blue', 'yellow']).validate("broccoli")
...
ValidationError: Incorrect value.

>>> In(
        ['red', 'blue', 'yellow'],
        error_message = "Please choose one of the available colors."
    ).validate("broccoli")
...
ValidationError: Please choose one of the available colors.

You rarely have to use In explicitly in a Schema. Any object that implements the __contains__ special method (like for example, python lists, tuples, set, and many more) will be automatically converted to an In filter by the Schema constructor.

shipping_schema = Schema(
    ['address', address_schema],
    ['shipping method', ('priority mail', 'parcel post', 'bottle to the sea')]
)

As you can see, unless you want to customize the error message, you don’t have to build a In filter explicitly, when you define a Schema.

Do

Do creates a new filter from existing filters. The filters will be applied one after another. For example, the Url validator is actually defined this way:

Url = Do(
    Type(str),
    Length(max=2083),
    Regex("a huge regex here"),
    error_message = _("This is not a valid url.")
)

As you can see, it is possible to specify an error message. This error message will override any error message that could be triggered by the filters in the sequence.

Each

Use Each if you want to apply a filter to every element of a collection.

For example, to validate that a field is a list of integers:

>>> schema = Schema(
        ['integers', Type(list), Each(Type(int))]
    )

>>> schema.validate({'integers': [1, 2, 3, 5]})
{'integers': [1, 2, 3, 5]}

>>> schema.validate({'integers': [8, "broccoli", 21]})
...
ValidationError: {'integers': 'Item #2: Wrong type. Expected int. Got str instead.'}

You can use Each0 if you want the items to be numbered from 0 when generating the error messages:

>>> Each0(Type(int)).validate([8, "broccoli", 21])
...
ValidationError: Item #1: Wrong type. Expected int. Got str instead.

It can prove useful to use Each in combination with Do in order to apply many filters to each elements of a list. For example:

>>> schema = Schema(
    ['keywords', Type(list), Each( Do( Type(str), Length(min=2, max=30), str.lower) ), Save]
)

>>> schema.validate({'keywords': ['PANCAKES', 'FOOD', 'Recipe']})
{'keywords': ['pancakes', 'food', 'recipe']}

Schema

Schema is the class used to define validation and transformation rules for python dictionaries. Each rule is expressed as a list. Like this:

address_schema = Schema(
    ['house number', Type(int), Range(1, 10000)],
    ['street', Type(str), Length(min=5, max=255)],
    ['zipcode', Type(str), Regex('\d{4,5}')],
    ['country', ('France', 'Germany', 'Spain')],
)

or this:

registration_form = Schema(
    ['username', Type(str), Length(min=3, max=16)],
    ['password', Type(str)],
    ['password2'],
    [
        Assert(
            (lambda d: d['password'] == d['password2']),
            error_message = "Passwords don't match"
        )
    ],
    ['password', lambda s: s.encode('utf-8'), bcrypt.encrypt, Save],
    ['password2', Delete],
    ['email', Email]
)

Each rule either apply to a particular field of the dictionary, or it applies to the dictionary as a whole. If a rule starts with a filter, or a callable, then the rule applies to the whole dictionary. Otherwise (for example if the rule starts with a string like "username"), then the rule applies to this particular item of the dictionary.

In the preceding example, the rule

[
    Assert(
        (lambda d: d['password'] == d['password2']),
        error_message = "Passwords don't match"
    )
]

is a global rule. The Assert filter is called on the whole dictionary.

Here’s another example:

schema = Schema(
    ['first name', Type(str), Length(min=1, max=50)],
    ['last name', Type(str), Length(min=1, max=50)],
    [lambda d: d['first name'] + ' ' + d['last name'], SaveAs('full name')]
)

The last rule starts with a callable so it applies to the whole dictionary. I guess it’s time to introduce the SaveAs instruction.

Each rule can optionally end with a storage instruction: SaveAs, MoveTo, Save or Delete.

>>> original = {'age': 25.4}

>>> Schema(['age', round, SaveAs('age_round')]).validate(original)
{'age': 25.4, 'age_round': 25}

>>> original
{'age': 25.4}

>>> original = {'age': 25.4}

>>> Schema(['age', round, MoveTo('age_round')]).validate(original)
{'age_round': 25}

>>> >>> original
{'age': 25.4}

>>> original = {'age': 25.4}

>>> Schema(['age', round, Save]).validate()
{'age': 25}

>>> original
{'age': 25.4}

>>> icecream_order = Schema(
        ['flavour', ('vanilla', 'chocolate', 'pistachio')],
        ['topping', Optional, ('whipped cream', 'chocolate sprinkles', 'peanuts')],
        ['quantity', int, Range(1, 12)]
    )

>>> icecream_order.validate({'flavour': 'vanilla', 'quantity': 4})
{'flavour': 'vanilla', 'quantity': 4}

['currency', Default('USD')]

['username', Default(lambda d: ''.join(random.choice(string.ascii_lowercase) for _ in range(6)))]

>>> schema = Schema(
        ['email', Email],
        ['username', Default(lambda d: d['email'])]
    )

>>> schema.validate({'email': 'the-king@example.com'})
{'email': 'the-king@example.com', 'username': 'the-king@example.com'}

>>> schema = Schema(
        ['name', Type(str)],
        ['address', Discard(''), Type(str)]
    )

>>> schema.validate({'name': 'Marcel Bichon', 'address': ''})
...
ValidationError: {'address': 'Field is missing.'}

>>> schema = Schema(
        ['name', Type(str)],
        ['address', Discard(''), Optional, Type(str)]
    )

>>> schema.validate({'name': 'Marcel Bichon', 'address': ''})
{'name': 'Marcel Bichon'}

>>> household_schema = Schema(
        ['married', Type(bool)],
        ['number of children', Discard(''), Default('0'), int, Save]
    )

>>> household_schema.validate({'married': False, 'number of children': ''})
{'married': False, 'number of children': 0}

['task_id', Discard('', None)]