API Reference¶
Serializer¶
-
class
serpy.
Serializer
(instance=None, many=False, data=None, context=None, **kwargs)[source]¶ Serializer
is used as a base for custom serializers.The
Serializer
class is also a subclass ofField
, and can be used as aField
to create nested schemas. A serializer is defined by subclassingSerializer
and adding eachField
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, setmany
toTrue
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)[source]¶ DictSerializer
serializes pythondicts
instead of objects.Instead of the serializer’s fields fetching data using
operator.attrgetter
,DictSerializer
usesoperator.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)[source]¶ 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, overridingField.to_value()
should give enough flexibility. If more control is needed, overrideField.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 isNone
.
-
as_getter
(serializer_field_name, serializer_cls)[source]¶ Returns a function that fetches an attribute from an object.
Return
None
to use the default getter for the serializer defined inSerializer.default_getter
.When a
Serializer
is defined, eachField
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 throughField.to_value()
.If a
Field
hasgetter_takes_serializer = True
, then the getter returned from this method will be called with theSerializer
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 fromField.as_getter()
requires the serializer to be passed in as the first argument. Otherwise, the object will be the only parameter.
- attr (str) – The attribute to get on the object, using the same format
as
-
class
serpy.
StrField
(attr=None, call=False, label=None, required=True)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ A
Field
that converts the value to a boolean.-
to_value
¶ alias of
bool
-
-
class
serpy.
MethodField
(method=None, **kwargs)[source]¶ A
Field
that calls a method on theSerializer
.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>'
.