API Reference

Data

lollipop.types.MISSING = <MISSING>

Special singleton value (like None) to represent case when value is missing.

Types

class lollipop.types.Type(name=None, description=None, validate=None, *args, **kwargs)[source]

Base class for defining data types.

Parameters:
  • name (string) – Name of type or None for unnamed types
  • description (string) – Description of type or None
  • validate (list) – A validator or list of validators for this data type. Validator is a callable that takes serialized data and raises ValidationError if data is invalid. Validator return value is ignored.
  • error_messages (dict) – Mapping of error message keys to error message text. Error messages can contain placeholders in standard string.format() format (e.g. “Invalid value: {value}”). Consult particular type’s documentation on available data.
Error message keys:
  • invalid - value is invalid. Interpolation data:
    • data - actual value
  • required - value is required
dump(value, context=None)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, context=None)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
validate(data, context=None)[source]

Takes serialized data and returns validation errors or None.

Parameters:
  • data – Data to validate.
  • context – Context data.
Returns:

validation errors or None
class lollipop.types.Any(name=None, description=None, validate=None, *args, **kwargs)[source]

Any type. Does not transform/validate given data.

class lollipop.types.String(name=None, description=None, validate=None, *args, **kwargs)[source]

A string type.

Error message keys:
  • invalid - invalid value type. Interpolation data:
    • data - actual value
dump(value, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.Integer(name=None, description=None, validate=None, *args, **kwargs)[source]

An integer type.

Error message keys:
  • invalid - invalid value type. Interpolation data:
    • data - actual value
num_type

alias of __builtin__.int

class lollipop.types.Float(name=None, description=None, validate=None, *args, **kwargs)[source]

A float type.

Error message keys:
  • invalid - invalid value type. Interpolation data:
    • data - actual value
num_type

alias of __builtin__.float

class lollipop.types.Boolean(name=None, description=None, validate=None, *args, **kwargs)[source]

A boolean type.

Error message keys:
  • invalid - invalid value type. Interpolation data:
    • data - actual value
dump(value, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.Date(format=None, *args, **kwargs)[source]

A date type which serializes into string.

Parameters:
  • format (str) – Format string (see datetime.datetime.strptime()) or one of predefined format names (e.g. ‘iso8601’, ‘rfc3339’, etc. See FORMATS)
  • kwargs – Same keyword arguments as for Type.
Predefined formats:
  • iso - shortcut for iso8601 (default)
  • iso8601 - %Y-%m-%d (e.g. “2015-12-31”)
  • rfc - shortcut for rfc3339
  • rfc3339 - %Y-%m-%d (e.g. “2015-12-31”)
  • rfc822 - %d %b %y (e.g. “31 Dec 2015”)
Error message keys:
  • invalid - invalid date value (on dump). Interpolation data:
    • data - actual value
  • invalid_type - value is not a string (on load). Interpolation data:
    • data - actual value
  • invalid_format - string does not match date format (on load).
    Interpolation data:
    • data - actual value
    • format - format string
class lollipop.types.DateTime(format=None, *args, **kwargs)[source]

A date and time type which serializes into string.

Parameters:
  • format (str) – Format string (see datetime.datetime.strptime()) or one of predefined format names (e.g. ‘iso8601’, ‘rfc3339’, etc. See FORMATS)
  • kwargs – Same keyword arguments as for Type.

Instead of specifying format strings explicitly, you can instead use one of predefined strings for formats. E.g. DateTime(format='rfc3339').

Predefined formats:
  • iso - shortcut for iso8601 (default)
  • iso8601 - %Y-%m-%dT%H:%M:%S%Z (e.g. “2015-12-31T14:59:59PDT”)
  • rfc - shortcut for rfc3339
  • rfc3339 - %Y-%m-%dT%H:%M:%S%Z (e.g. “2015-12-31T14:59:59UTC”)
  • rfc822 - %d %b %y %H:%M:%S %Z (e.g. “31 Dec 2015 14:59:59 PDT”)
Error message keys:
  • invalid - invalid datetime value (on dump). Interpolation data:
    • data - actual value
  • invalid_type - value is not a string (on load). Interpolation data:
    • data - actual value
  • invalid_format - string does not match datetime format (on load).
    Interpolation data:
    • data - actual value
    • format - format string
dump(value, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.Time(format=None, *args, **kwargs)[source]

A time type which serializes into string.

Parameters:
  • format (str) – Format string (see datetime.datetime.strptime()) or one of predefined format names (e.g. ‘iso8601’, ‘rfc3339’, etc.)
  • kwargs – Same keyword arguments as for Type.
Predefined formats:
  • iso - shortcut for iso8601 (default)
  • iso8601 - %H:%M:%S (e.g. “14:59:59”)
Error message keys:
  • invalid - invalid time value (on dump). Interpolation data:
    • data - actual value
  • invalid_type - value is not a string (on load). Interpolation data:
    • data - actual value
  • invalid_format - string does not match date format (on load).
    Interpolation data:
    • data - actual value
    • format - format string
class lollipop.types.List(item_type, **kwargs)[source]

A homogenous list type.

Example:

List(String()).load(['foo', 'bar', 'baz'])
Parameters:
  • item_type (Type) – Type of list elements.
  • kwargs – Same keyword arguments as for Type.
Error message keys:
  • invalid - invalid list value. Interpolation data:
    • data - actual value
dump(value, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.Tuple(item_types, **kwargs)[source]

A heterogenous list type.

Example:

Tuple([String(), Integer(), Boolean()]).load(['foo', 123, False])
# => ('foo', 123, False)
Parameters:
  • item_types (list) – List of item types.
  • kwargs – Same keyword arguments as for Type.
Error message keys:
  • invalid - invalid list value. Interpolation data:
    • data - actual value
  • invalid_length: tuple has invalid length: Interpolation data:
    • expected_length
    • actual_length
dump(value, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.Dict(value_types=None, key_type=None, **kwargs)[source]

A dict type. You can specify either a single type for all dict values or provide a dict-like mapping object that will return proper Type instance for each given dict key.

Example:

Dict(Integer()).load({'key0': 1, 'key1': 5, 'key2': 15})

Dict({'foo': String(), 'bar': Integer()}).load({
    'foo': 'hello', 'bar': 123,
})
Parameters:
  • value_types (dict) – A single Type for all dict values or mapping of allowed keys to Type instances (defaults to Any)
  • key_type (Type) – Type for dictionary keys (defaults to Any). Can be used to either transform or validate dictionary keys.
  • kwargs – Same keyword arguments as for Type.
Error message keys:
  • invalid - invalid value type. Interpolation data:
    • data - actual value
dump(value, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.OneOf(types, load_hint=<function type_name_hint>, dump_hint=<function type_name_hint>, *args, **kwargs)[source]

Type that alternates between several other types.

There are two ways to use it:
  • with sequence of types
  • with mapping of types

When used with sequence of types, it tries to load/dump data with each type in a sequence until operation succeeds, proceeding to next type if operation fails.

Types sequence example:

ValueType = OneOf([String(), List(String())])

ValutType.dump('foo')           # => 'foo'
ValueType.dump(['foo', 'bar'])  # => ['foo', 'bar']

When used with a mapping of types, it requires two hint functions to be provided: one to determine type name for dumped object and other one to determine type name for loaded data. E.g. dump hint can be based on object class. Load hint can be done either by inspecting data structure or using injected data: you can modify schema of your objects (assuming your data is objects) and add extra field called e.g. “type” and put some constant there. Then you can consult that field value to know what type to use for loading.

Hint function example:

def dump_hint(data):
    return data.__class__.__name__

def load_hint(key):
    def hinter(data):
        return data.get(key)
    return hinter

Type mapping example:

from collections import namedtuple

Foo = namedtuple('Foo', ['foo'])
Bar = namedtuple('Bar', ['bar'])

FooType = Object({'foo': String()}, constructor=Foo)
BarType = Object({'bar': Integer()}, constructor=Bar)

def object_with_type(name, subject_type):
    return Object(subject_type, {'type': DumpOnly(Constant(name))},
                  constructor=subject_type.constructor)

FooBarType = OneOf({
    'Foo': object_with_type('Foo', FooType),
    'Bar': object_with_type('Bar', BarType),
}, dump_hint=type_name_hint, load_hint=dict_value_hint('type'))

List(FooBarType).dump([Foo(foo='hello'), Bar(bar=123)])
# => [{'type': 'Foo', 'foo': 'hello'}, {'type': 'Bar', 'bar': 123}]

List(FooBarType).load([{'type': 'Foo', 'foo': 'hello'},
                       {'type': 'Bar', 'bar': 123}])
# => [Foo(foo='hello'), Bar(bar=123)]

Using hint functions can be handier because when trying different types in sequence it is impossible to distinguish between cases when data is obviously of different types vs data of that particular type but invalid.

Example:

NameType = String(validate=Length(max=32))
ValueType = OneOf([NameType, List(NameType)])

# Most likely if you specify long string, you will get error that
# data is of invalid type.

# Here is an alternative:

def value_type_hint(data):
    if isinstance(data, (str, unicode)):
        return 'string'
    elif isinstance(data, collections.Sequence):
        return 'list-of-names'
    else:
        return None

ValueType = OneOf(
    {
        'name': NameType,
        'list-of-names': List(NameType),
    },
    load_hint=value_type_hint,
    dump_hint=value_type_hint,
)
Error message keys:
  • invalid - invalid value type. Interpolation data:
    • data - actual value
  • unknown_type_id - unknown type ID. Interpolation data:
    • data - actual value
    • type_id - hinted type ID
  • no_type_matched - in case of sequence of types error when no types matched.
    Interpolation data:
    • value
dump(data, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
lollipop.types.type_name_hint(data)[source]

Returns type name of given value.

To be used as a type hint in OneOf.

lollipop.types.dict_value_hint(key, mapper=None)[source]

Returns a function that takes a dictionary and returns value of particular key. The returned value can be optionally processed by mapper function.

To be used as a type hint in OneOf.

class lollipop.types.Field(field_type, *args, **kwargs)[source]

Base class for describing Object fields. Defines a way to access object fields during serialization/deserialization. Usually it extracts data to serialize/deserialize and call self.field_type.load() to do data transformation.

Parameters:field_type (Type) – Field type.
dump(name, obj, context=None)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • name (str) – Name of attribute to serialize.
  • obj – Application object to extract serialized value from.
Returns:

Serialized data.
Raises:

ValidationError
get_value(name, obj, context=None)[source]

Get value of field name from object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Returns:Field value.
load(name, data, context=None)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • name (str) – Name of attribute to deserialize.
  • data – Raw data to get value to deserialize from.
  • kwargs – Same keyword arguments as for Type.load().
Returns:

Loaded data.
Raises:

ValidationError
load_into(obj, name, data, inplace=True, context=None)[source]

Deserialize data from primitive types updating existing object. Raises ValidationError if data is invalid.

Parameters:
  • obj – Object to update with deserialized data.
  • name (str) – Name of attribute to deserialize.
  • data – Raw data to get value to deserialize from.
  • inplace (bool) – If True update data inplace; otherwise - create new data.
  • kwargs – Same keyword arguments as for load().
Returns:

Loaded data.
Raises:

ValidationError
set_value(name, obj, value, context=None)[source]

Set given value of field name to object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Params value:Field value to set.
class lollipop.types.AttributeField(field_type, attribute=None, *args, **kwargs)[source]

Field that corresponds to object attribute. Subclasses can use name_to_attribute field to convert field names to attribute names.

Parameters:
  • field_type (Type) – Field type.
  • attribute – Can be either string or callable. If string, use given attribute name instead of field name defined in object type. If callable, should take a single argument - name of field - and return name of corresponding object attribute to obtain value from.
get_value(name, obj, context=None)[source]

Get value of field name from object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Returns:Field value.
set_value(name, obj, value, context=None)[source]

Set given value of field name to object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Params value:Field value to set.
class lollipop.types.IndexField(field_type, key=None, *args, **kwargs)[source]

Field that corresponds to object value at a particular index (e.g. key of a dictionary). Subclasses can use name_to_key field to convert field names to index keys.

Parameters:
  • field_type (Type) – Field type.
  • key – Can be either string or callable. If string, use given key instead of field name defined in object type. If callable, should take a single argument - name of field - and return name of corresponding object key to obtain value from.
get_value(name, obj, context=None)[source]

Get value of field name from object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Returns:Field value.
set_value(name, obj, value, context=None)[source]

Set given value of field name to object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Params value:Field value to set.
class lollipop.types.MethodField(field_type, get=None, set=None, *args, **kwargs)[source]

Field that is result of method invocation.

Example:

class Person(object):
    def __init__(self, first_name, last_name):
        self.first_name = first_name
        self.last_name = last_name

    def get_name(self):
        return self.first_name + ' ' + self.last_name

PersonType = Object({
    'name': MethodField(String(), 'get_name'),
}, constructor=Person)
Parameters:
  • field_type (Type) – Field type.
  • get – Can be either string or callable. If string, use target object method with given name to obain value. If callable, should take field name and return name of object method to use. Referenced method should take no argument - new field value to set.
  • set – Can be either string or callable. If string, use target object method with given name to set value in object. If callable, should take field name and return name of object method to use. Referenced method should take 1 argument - new field value to set.
  • kwargs – Same keyword arguments as for Field.
get_value(name, obj, context=None)[source]

Get value of field name from object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Returns:Field value.
set_value(name, obj, value, context=None)[source]

Set given value of field name to object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Params value:Field value to set.
class lollipop.types.FunctionField(field_type, get=None, set=None, *args, **kwargs)[source]

Field that is result of function invocation.

Example:

class Person(object):
    def __init__(self, first_name, last_name):
        self.first_name = first_name
        self.last_name = last_name

def get_name(person):
    return person.first_name + ' ' + person.last_name

PersonType = Object({
    'name': FunctionField(String(), get_name),
}, constructor=Person)
Parameters:
  • field_type (Type) – Field type.
  • get (callable) – Function that takes source object and returns field value.
  • set (callable) – Function that takes source object and new field value and sets that value to object field. Function return value is ignored.
get_value(name, obj, context=None)[source]

Get value of field name from object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Returns:Field value.
set_value(name, obj, value, context=None)[source]

Set given value of field name to object obj.

Params str name:
 Field name.
Params obj:Object to get field value from.
Params value:Field value to set.
class lollipop.types.Object(bases_or_fields=None, fields=None, constructor=None, default_field_type=None, allow_extra_fields=None, only=None, exclude=None, immutable=None, ordered=None, **kwargs)[source]

An object type. Serializes to a dict of field names to serialized field values. Parametrized with field names to types mapping. The way values are obtained during serialization is determined by type of field object in fields mapping (see AttributeField, MethodField or FunctionField for details). You can specify either Field object, a Type object or any other value.

In case of Type, it will be automatically wrapped with a default field type, which is controlled by default_field_type constructor argument.

In case of any other value it will be transformed into Constant.

Example:

class Person(object):
    def __init__(self, name, age):
        self.name = name
        self.age = age

PersonType = Object({
    'name': String(),
    'age': Integer(),
}, constructor=Person)
PersonType.load({'name': 'John', 'age': 42})
# => Person(name='John', age=42)
Parameters:
  • base_or_fields – Either Object instance or fields (See fields argument). In case of fields, the actual fields argument should not be specified.
  • fields – List of name-to-value tuples or mapping of object field names to Type, Field objects or constant values.
  • contructor (callable) – Deserialized value constructor. Constructor should take all fields values as keyword arguments.
  • default_field_type (Field) – Default field type to use for fields defined by their type.
  • allow_extra_fields – If False, it will raise ValidationError for all extra dict keys during deserialization. If True, will ignore all extra fields. If Type or Field, extra fields will be loaded and validated with given type/field and stored in load result.
  • only – Field name or list of field names to include in this object from it’s base classes. All other base classes’ fields won’t be used. Does not affect own fields.
  • exclude – Field name or list of field names to exclude from this object from base classes. All other base classes’ fields will be included. Does not affect own fields.
  • ordered (bool) – Serialize data into OrderedDict following fields order. Fields in this case should be declared with a dictionary which also supports ordering or with a list of tuples.
  • immutable (bool) – If False, object is allowed to be modified in-place; if True - always create a copy with constructor.
  • kwargs – Same keyword arguments as for Type.
Error message keys:
  • required - value is required
  • invalid - invalid value type. Interpolation data:
    • data - actual value
  • unknown - reported for unknown fields
dump(obj, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
load_into(obj, data, inplace=True, *args, **kwargs)[source]

Load data and update existing object.

Parameters:
  • obj – Object to update with deserialized data.
  • data – Raw data to get value to deserialize from.
  • inplace (bool) – If True update data inplace; otherwise - create new data.
  • kwargs – Same keyword arguments as for Type.load().
Returns:

Updated object.
Raises:

ValidationError
validate_for(obj, data, *args, **kwargs)[source]

Takes target object and serialized data, tries to update that object with data and validate result. Returns validation errors or None. Object is not updated.

Parameters:
  • obj – Object to check data validity against. In case the data is partial object is used to get the rest of data from.
  • data – Data to validate. Can be partial (not all schema field data is present).
  • kwargs – Same keyword arguments as for Type.load().
Returns:

validation errors or None
class lollipop.types.Modifier(inner_type, **kwargs)[source]

Base class for modifiers - a wrapper for types that modify how those types work. Also, it tries to be as transparent as possible in regard to inner type, so it proxies all unknown attributes to inner type.

Parameters:inner_type (Type) – Actual type that should be optional.
class lollipop.types.Constant(value, field_type=<Any>, *args, **kwargs)[source]

Type that always serializes to given value and checks this value on deserialize.

Parameters:
  • value – Value constant for this field.
  • field_type (Type) – Field type.
Error message keys:
  • required
  • value - incorrect value. Interpolation keys:
    • expected_value - expected value
    • actual_value - actual value
dump(value, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.Optional(inner_type, load_default=None, dump_default=None, **kwargs)[source]

A modifier which makes values optional: if value is missing or None, it will not transform it with an inner type but instead will return None (or any other configured value).

Example:

UserType = Object({
    'email': String(),           # by default types require valid values
    'name': Optional(String()),  # value can be omitted or None
    'role': Optional(            # when value is omitted or None, use given value
        String(validate=AnyOf(['admin', 'customer'])),
        load_default='customer',
    ),
})
Parameters:
  • inner_type (Type) – Actual type that should be optional.
  • load_default – Value or callable. If value - it will be used when value is missing on deserialization. If callable - it will be called with no arguments to get value to use when value is missing on deserialization.
  • dump_default – Value or callable. If value - it will be used when value is missing on serialization. If callable - it will be called with no arguments to get value to use when value is missing on serialization.
  • kwargs – Same keyword arguments as for Type.
dump(data, context=None, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, context=None, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.LoadOnly(inner_type, **kwargs)[source]

A wrapper type which proxies loading to inner type but always returns MISSING on dump.

Example:

UserType = Object({
    'name': String(),
    'password': LoadOnly(String()),
})
Parameters:inner_type (Type) – Data type.
dump(data, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.DumpOnly(inner_type, **kwargs)[source]

A wrapper type which proxies dumping to inner type but always returns MISSING on load.

Example:

UserType = Object({
    'name': String(),
    'created_at': DumpOnly(DateTime()),
})
Parameters:inner_type (Type) – Data type.
dump(data, *args, **kwargs)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, *args, **kwargs)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
class lollipop.types.Transform(inner_type, pre_load=<function identity>, post_load=<function identity>, pre_dump=<function identity>, post_dump=<function identity>)[source]

A wrapper type which allows us to convert data structures to an inner type, then loaded or dumped with a customized format.

Example:

Point = namedtuple('Point', ['x', 'y'])

PointType = Transform(
    Tuple(Integer(), Integer()),
    post_load=lambda values: Point(values[0], values[1]),
    pre_dump=lambda point: [point.x, point.y],
)

PointType.dump((Point(x=1, y=2)))
# => [1,2]

PointType.load([1,2])
# => Point(x=1, y=2)
Parameters:
  • inner_type (Type) – Data type.
  • pre_load – Modify data before it is passed to inner_type load. Argument should be a callable taking one argument - data - and returning updated data. Optionally it can take a second argument - context.
  • post_load – Modify data after it is returned from inner_type load. Argument should be a callable taking one argument - data - and returning updated data. Optionally it can take a second argument - context.
  • pre_dump – Modify value before it passed to inner_type dump. Argument should be a callable taking one argument - value - and returning updated value. Optionally it can take a second argument - context.
  • post_dump – Modify value after it is returned from inner_type dump. Argument should be a callable taking one argument - value - and returning updated value. Optionally it can take a second argument - context.
dump(value, context=None)[source]

Serialize data to primitive types. Raises ValidationError if data is invalid.

Parameters:
  • value – Value to serialize.
  • context – Context data.
Returns:

Serialized data.
Raises:

ValidationError
load(data, context=None)[source]

Deserialize data from primitive types. Raises ValidationError if data is invalid.

Parameters:
  • data – Data to deserialize.
  • context – Context data.
Returns:

Loaded data
Raises:

ValidationError
lollipop.types.validated_type(base_type, name=None, validate=None)[source]

Convenient way to create a new type by adding validation to existing type.

Example:

Ipv4Address = validated_type(
    String, 'Ipv4Address',
    # regexp simplified for demo purposes
    Regexp('^\d+\.\d+\.\d+\.\d+$', error='Invalid IP address')
)

Percentage = validated_type(Integer, validate=Range(0, 100))

# The above is the same as

class Ipv4Address(String):
    def __init__(self, *args, **kwargs):
        super(Ipv4Address, self).__init__(*args, **kwargs)
        self.validators.insert(0, Regexp('^\d+\.\d+\.\d+\.\d+$', error='Invalid IP address'))

class Percentage(Integer):
    def __init__(self, *args, **kwargs):
        super(Percentage, self).__init__(*args, **kwargs)
        self.validators.insert(0, Range(0, 100))
Parameters:
  • base_type (Type) – Base type for a new type.
  • str (name) – Optional class name for new type (will be shown in places like repr).
  • validate – A validator or list of validators for this data type. See Type.validate for details.

Validators

class lollipop.validators.Validator(error_messages=None, *args, **kwargs)[source]

Base class for all validators.

Validator is used by types to validate data during deserialization. Validator class should define __call__ method with either one or two arguments. In both cases, first argument is value being validated. In case of two arguments, the second one is the context. If given value fails validation, __call__ method should raise ValidationError. Return value is always ignored.

class lollipop.validators.Predicate(predicate, error=None, **kwargs)[source]

Validator that succeeds if given predicate returns True.

Parameters:
  • predicate (callable) – Predicate that takes value and returns True or False. One- and two-argument predicates are supported. First argument in both cases is value being validated. In case of two arguments, the second one is context.
  • error (str) – Error message in case of validation error. Can be interpolated with data.
class lollipop.validators.Range(min=None, max=None, error=None, **kwargs)[source]

Validator that checks value is in given range.

Parameters:
  • min (int) – Minimum length. If not provided, minimum won’t be checked.
  • max (int) – Maximum length. If not provided, maximum won’t be checked.
  • error (str) – Error message in case of validation error. Can be interpolated with data, min or max.
class lollipop.validators.Length(exact=None, min=None, max=None, error=None, **kwargs)[source]

Validator that checks value length (using len()) to be in given range.

Parameters:
  • exact (int) – Exact length. If provided, min and max are not checked. If not provided, min and max checks are performed.
  • min (int) – Minimum length. If not provided, minimum length won’t be checked.
  • max (int) – Maximum length. If not provided, maximum length won’t be checked.
  • error (str) – Error message in case of validation error. Can be interpolated with data, length, exact, min or max.
class lollipop.validators.NoneOf(values, error=None, **kwargs)[source]

Validator that succeeds if value is not a member of given values.

Parameters:
  • values (iterable) – A sequence of invalid values.
  • error (str) – Error message in case of validation error. Can be interpolated with data and values.
class lollipop.validators.AnyOf(choices, error=None, **kwargs)[source]

Validator that succeeds if value is a member of given choices.

Parameters:
  • choices (iterable) – A sequence of allowed values.
  • error (str) – Error message in case of validation error. Can be interpolated with data and choices.
class lollipop.validators.Regexp(regexp, flags=0, error=None, **kwargs)[source]

Validator that succeeds if value matches given regex.

Parameters:
  • regexp (str) – Regular expression string.
  • flags (int) – Regular expression flags, e.g. re.IGNORECASE. Not used if regexp is not a string.
  • error (str) – Error message in case of validation error. Can be interpolated with data and regexp.
class lollipop.validators.Unique(key=<function identity>, error=None, **kwargs)[source]

Validator that succeeds if items in collection are unqiue. By default items themselves should be unique, but you can specify a custom function to get uniqueness key from items.

Parameters:
  • key (callable) – Function to get uniqueness key from items.
  • error (str) – Erorr message in case item appear more than once. Can be interpolated with data (the item that is not unique) and key (uniquness key that is not unique).
class lollipop.validators.Each(validators, **kwargs)[source]

Validator that takes a list of validators and applies all of them to each item in collection.

Parameters:validators – Validator or list of validators to run against each element of collection.

Errors

lollipop.errors.SCHEMA = '_schema'

Name of an error key for cases when you have both errors for the object and for it’s fields:

{'field1': 'Field error', '_schema': 'Whole object error'}
exception lollipop.errors.ValidationError(messages)[source]

Exception to report validation errors.

Examples of valid error messages:

raise ValidationError('Error')
raise ValidationError(['Error 1', 'Error 2'])
raise ValidationError({
    'field1': 'Error 1',
    'field2': {'subfield1': ['Error 2', 'Error 3']}
})
Parameters:messages – Validation error messages. String, list of strings or dict where keys are nested fields and values are error messages.
class lollipop.errors.ValidationErrorBuilder[source]

Helper class to report multiple errors.

Example:

def validate_all(data):
    builder = ValidationErrorBuilder()
    if data['foo']['bar'] >= data['baz']['bam']:
        builder.add_error('foo.bar', 'Should be less than bam')
    if data['foo']['quux'] >= data['baz']['bam']:
        builder.add_fields('foo.quux', 'Should be less than bam')
    ...
    builder.raise_errors()
add_error(path, error)[source]

Add error message for given field path.

Example:

builder = ValidationErrorBuilder()
builder.add_error('foo.bar.baz', 'Some error')
print builder.errors
# => {'foo': {'bar': {'baz': 'Some error'}}}
Parameters:
  • path (str) – ‘.’-separated list of field names
  • error (str) – Error message
add_errors(errors)[source]

Add errors in dict format.

Example:

builder = ValidationErrorBuilder()
builder.add_errors({'foo': {'bar': 'Error 1'}})
builder.add_errors({'foo': {'baz': 'Error 2'}, 'bam': 'Error 3'})
print builder.errors
# => {'foo': {'bar': 'Error 1', 'baz': 'Error 2'}, 'bam': 'Error 3'}
Parameters:list or dict errors (str,) – Errors to merge
raise_errors()[source]

Raise ValidationError if errors are not empty; do nothing otherwise.

lollipop.errors.merge_errors(errors1, errors2)[source]

Deeply merges two error messages. Error messages can be string, list of strings or dict of error messages (recursively). Format is the same as accepted by ValidationError. Returns new error messages.

Type registry

class lollipop.type_registry.TypeRegistry[source]

Storage for type instances with ability to get type instance proxy with delayed type resolution for implementing mutual cross-references.

Example:

TYPES = TypeRegistry()

PersonType = TYPES.add('Person', lt.Object({
    'name': lt.String(),
    'books': lt.List(lt.Object(TYPES['Book'], exclude='author')),
}, constructor=Person))

BookType = TYPES.add('Book', lt.Object({
    'title': lt.String(),
    'author': lt.Object(TYPES['Person'], exclude='books'),
}, constructor=Book))