Serializing Django objects

This document describes Django version 0.95. For current documentation, go here.

Note

This API is currently under heavy development and may change — perhaps drastically — in the future.

You have been warned.

Django’s serialization framework provides a mechanism for “translating” Django objects into other formats. Usually these other formats will be text-based and used for sending Django objects over a wire, but it’s possible for a serializer to handle any format (text-based or not).

Serializing data

At the highest level, serializing data is a very simple operation:

from django.core import serializers
data = serializers.serialize("xml", SomeModel.objects.all())

The arguments to the serialize function are the format to serialize the data to (see Serialization formats) and a QuerySet to serialize. (Actually, the second argument can be any iterator that yields Django objects, but it’ll almost always be a QuerySet).

You can also use a serializer object directly:

xml_serializer = serializers.get_serializer("xml")
xml_serializer.serialize(queryset)
data = xml_serializer.getvalue()

This is useful if you want to serialize data directly to a file-like object (which includes a HTTPResponse):

out = open("file.xml", "w")
xml_serializer.serialize(SomeModel.objects.all(), stream=out)

Deserializing data

Deserializing data is also a fairly simple operation:

for obj in serializers.deserialize("xml", data):
    do_something_with(obj)

As you can see, the deserialize function takes the same format argument as serialize, a string or stream of data, and returns an iterator.

However, here it gets slightly complicated. The objects returned by the deserialize iterator aren’t simple Django objects. Instead, they are special DeserializedObject instances that wrap a created — but unsaved — object and any associated relationship data.

Calling DeserializedObject.save() saves the object to the database.

This ensures that deserializing is a non-destructive operation even if the data in your serialized representation doesn’t match what’s currently in the database. Usually, working with these DeserializedObject instances looks something like:

for deserialized_object in serializers.deserialize("xml", data):
    if object_should_be_saved(deserialized_object):
        obj.save()

In other words, the usual use is to examine the deserialized objects to make sure that they are “appropriate” for saving before doing so. Of course, if you trust your data source you could just save the object and move on.

The Django object itself can be inspected as deserialized_object.object.

Serialization formats

Django “ships” with a few included serializers:

Identifier	Information
`xml`	Serializes to and from a simple XML dialect.
`json`	Serializes to and from JSON (using a version of simplejson bundled with Django).
`python`	Translates to and from “simple” Python objects (lists, dicts, strings, etc.). Not really all that useful on its own, but used as a base for other serializers.

Writing custom serializers

XXX …

Questions/Feedback

If you notice errors with this documentation, please open a ticket and let us know!

Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list.

Django documentation