val 0.4.0

Python object validator

val
===

A validator for arbitrary Python objects.

Inspired by some of the wonderful ideas in schema and flatland:

https://github.com/halst/schema

http://discorporate.us/projects/flatland/

many of which I outright stole.

The goal is to make validation faster than either, while keeping the very
pythonic and minimal style of schema, at the expense of more advanced features.

One of the shortcuts I took is bailing out on the first encountered validation
error. The rationale (or rationalization, if you must) is that the library is
meant to validate API inputs, rather than direct user input, so the burden is
somewhat shifted to the client side to send valid requests. I do not suggest
using val for validating web form input.

Current status is: used in production code, but only in one place that I know of. ;)

I have not optimized much, but for the kind of schemas I need (specifically: to
validate JSON that has been loaded into python structures,) I have extremely
anecdotal evidence that it's around 10x faster than both schema and flatland.
(Again, that is mostly because it does way less, and I intend to keep it that
way.)

The schemas understood by lazyval are very similar to the ones in schema:

from val import Schema, Or

schema = Schema({
'invisible': bool,
'immutable': bool,
Optional('favorite_colors'): [basestring],
Optional('favorite_foods'): [basestring],
'lucky_number': Or(int, None),
'shoe_size': int,
'mother': {
'name': basestring,
'nested': {'id': basestring}},
Optional('father'): {
'name': basestring,
'nested': {'id': basestring}}})

result = schema.validate(some_value)
# result will be the validated value, or a NotValid exception will be
# raised.

result = schema.validates(some_value)
# result will be True or False depending on whether some_value was valid
# for the schema.

Elements that can occur in a schema are:

* simple literal values that will match equal values:

* `12`, will validate `12`
* `'foo'` will validate `'foo'`

* types that will validate anything that is an instance of the type:

* `int`, will validate `12`
* `basestring`, will validate `'foo'` and `u'fnørd'`
* `list`, will validate `[12, 'foo']`
* `dict`, will validate `{'foo': 12}`
* `object`, will validate any object, so all of the above and more

* lists of elements that will validate list values all of whose elements are
validated by one of the elements in the elements in the list (order or
number of elements do not matter, see Ordered):

* `[str, int]`, will validate `[12, 'foo', 'bar', 'baz', 42]`
* `['foo', 'bar', 13]`, will validate `['foo']` and `['foo', 13]` and
`['bar', 'bar', 13, 'bar']`, etc,

* dictionaries with elements as keys and values, that will validate
dictionaries all of whose key value pairs are validated by at least one of
the key value pairs in the schema:

* `{'foo': int, str: int}` will match `{'foo': 83}` and
`{'foo': 12, 'bar': 888, 'baz': 299}`, but not `{'foo': 'bar'}` or
`{'foo': 21, 12: 'bar'}`

* callables (that aren't of type `type`) will validate any value for which
the callable returns a truthy value. TypeErrors or ValueErrors in the call
will result in a NotValid exception.

* `lambda x: x < 10` will validate `9` but not `10`, etc.

* `Convert(callable)`, will call the callable on the value being validated,
and substitute the result of that call for the original value in the
validated structure. TypeErrors or ValueErrors in the call will result in a
NotValid exception. This and supplying a default value to an Optional key
are the only ways to the data being validated.
Convert is useful to convert between representations (for
instance from timestamps to datetime objects, or uuid string
representations to uuid objects, etc.)

* `Convert(int)` will validate `'12'` and put `12` in the result, or
`42.34` and put `42` in the result, but it will not validate `'foo'`.

* `Or(element1, element2, ...)` will validate a value validated by any of the
elements passed into the Or.

* `Or('foo', int)` matches `'foo'`, or `12`, or `54`, etc.

* `And(element1, element2, ...)` will validate a value validated by all of
the elements passed into the And.

* `And(Convert(int), lambda x: x < 12, lambda x: x >= 3)` will validate
`'3'` and return `3` or `11.6` and return `11`, but not `'12'`, `42.77`,
or `'foo'`

* `{Optional(simple_literal_key): value}` will match any key value pair that
matches `simple_literal_key: value` but the schema will still validate
dictionary values with no matching key.

`Optional` can take an optional `default` parameter, whose value will be
substituted in the result if the key is not in the data, *or*, when
a `null_values` parameter is also specified, if the key has a value that is
one of the null values.

* `{Optional('foo'): 12}` matches `{'foo': 12}` and `{}` but not
`{'foo': 13}` or `{'foo': 'bar'}`
* `{Optional('foo', default=13): int}` matches `{'foo': 12}` and `{}`
(which will become `{'foo': 13}`) but not `{'foo': 'bar'}`
* `{Optional('foo', default=13, null_values=(0, None): Or(int, None)}`
matches `{'foo': 12}` and `{'foo': 0}` (which will become `{'foo': 13}`)
and `{'foo': None}` (which will also become `{'foo': 13}`) but not
`{'foo': 'bar'}`

* `Ordered([element1, element2, element3])` will validate a list with
*exactly* 3 elements, each of which must be validated by the corresponding
element in the schema. If order and number of elements do not matter, just
use a list.

* Other parsed schema objects. So this works:

sub_schema = Schema({'foo': str, str: int})
schema = Schema(
{'key1': sub_schema,
'key2': sub_schema,
str: sub_schema})
schema.validate(
{'key1': {'foo': 'bar'},
'key2': {'foo': 'qux', 'baz': 43},
'whatever': {'foo': 'doo', 'fsck': 22, 'tsk': 2992}}))