API Reference

Serializer

class serpy.Serializer(instance=None, many=False, data=None, context=None, **kwargs)

Serializer is used as a base for custom serializers.

The Serializer class is also a subclass of Field, and can be used as a Field to create nested schemas. A serializer is defined by subclassing Serializer and adding each Field as a class variable:

Example:

class FooSerializer(Serializer):
    foo = Field()
    bar = Field()

foo = Foo(foo='hello', bar=5)
FooSerializer(foo).data
# {'foo': 'hello', 'bar': 5}

Parameters:

• instance – The object or objects to serialize.
• many (bool) – If instance is a collection of objects, set many to True to serialize to a list.
• context – Currently unused parameter for compatability with Django REST Framework serializers.

data

Get the serialized data from the Serializer.

The data will be cached for future accesses.

default_getter

The default getter used if Field.as_getter() returns None.

alias of attrgetter

class serpy.DictSerializer(instance=None, many=False, data=None, context=None, **kwargs)

DictSerializer serializes python dicts instead of objects.

Instead of the serializer’s fields fetching data using operator.attrgetter, DictSerializer uses operator.itemgetter.

Example:

class FooSerializer(DictSerializer):
    foo = IntField()
    bar = FloatField()

foo = {'foo': '5', 'bar': '2.2'}
FooSerializer(foo).data
# {'foo': 5, 'bar': 2.2}

default_getter

alias of itemgetter

Fields

If none of these fields fit your needs, serpy makes it simple to create custom fields. See the Custom Fields documentation.

class serpy.Field(attr=None, call=False, label=None, required=True)

Field is used to define what attributes will be serialized.

A Field maps a property or function on an object to a value in the serialized result. Subclass this to make custom fields. For most simple cases, overriding Field.to_value() should give enough flexibility. If more control is needed, override Field.as_getter().

Parameters:

• attr (str) – The attribute to get on the object, using the same format as operator.attrgetter. If this is not supplied, the name this field was assigned to on the serializer will be used.
• call (bool) – Whether the value should be called after it is retrieved from the object. Useful if an object has a method to be serialized.
• label (str) – A label to use as the name of the serialized field instead of using the attribute name of the field.
• required (bool) – Whether the field is required. If set to False, Field.to_value() will not be called if the value is None.

as_getter(serializer_field_name, serializer_cls)

Returns a function that fetches an attribute from an object.

Return None to use the default getter for the serializer defined in Serializer.default_getter.

When a Serializer is defined, each Field will be converted into a getter function using this method. During serialization, each getter will be called with the object being serialized, and the return value will be passed through Field.to_value().

If a Field has getter_takes_serializer = True, then the getter returned from this method will be called with the Serializer instance as the first argument, and the object being serialized as the second.

Parameters:

• serializer_field_name (str) – The name this field was assigned to on the serializer.
• serializer_cls – The Serializer this field is a part of.

getter_takes_serializer = False

Set to True if the value function returned from Field.as_getter() requires the serializer to be passed in as the first argument. Otherwise, the object will be the only parameter.

to_value(value)

Transform the serialized value.

Override this method to clean and validate values serialized by this field. For example to implement an int field:

def to_value(self, value):
    return int(value)

Parameters:value – The value fetched from the object being serialized.

class serpy.StrField(attr=None, call=False, label=None, required=True)

A Field that converts the value to a string.

to_value

alias of unicode

class serpy.IntField(attr=None, call=False, label=None, required=True)

A Field that converts the value to an integer.

to_value

alias of int

class serpy.FloatField(attr=None, call=False, label=None, required=True)

A Field that converts the value to a float.

to_value

alias of float

class serpy.BoolField(attr=None, call=False, label=None, required=True)

A Field that converts the value to a boolean.

to_value

alias of bool

class serpy.MethodField(method=None, **kwargs)

A Field that calls a method on the Serializer.

This is useful if a Field needs to serialize a value that may come from multiple attributes on an object. For example:

class FooSerializer(Serializer):
    plus = MethodField()
    minus = MethodField('do_minus')

    def get_plus(self, foo_obj):
        return foo_obj.bar + foo_obj.baz

    def do_minus(self, foo_obj):
        return foo_obj.bar - foo_obj.baz

foo = Foo(bar=5, baz=10)
FooSerializer(foo).data
# {'plus': 15, 'minus': -5}

Parameters:method (str) – The method on the serializer to call. Defaults to 'get_<field name>'.