+
−==========================
+
−Serializing Django objects
+
−==========================
+
−
+
−.. 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).
+
−
+
−.. _QuerySet: ../db_api/#retrieving-objects
+
−
+
−You can also use a serializer object directly::
+
−
+
−    XMLSerializer = serializers.get_serializer("xml")
+
−    xml_serializer = XMLSerializer()
+
−    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)
+
−
+
−.. _HTTPResponse: ../request_response/#httpresponse-objects
+
−
+
−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.
+
−    ==========  ==============================================================
+
−
+
−.. _json: http://json.org/
+
−.. _simplejson: http://undefined.org/python/#simplejson
+
−
+
−Notes for specific serialization formats
+
−----------------------------------------
+
−
+
−json
+
−~~~~
+
−
+
−If you're using UTF-8 (or any other non-ASCII encoding) data with the JSON
+
−serializer, you must pass ``ensure_ascii=False`` as a parameter to the
+
−``serialize()`` call. Otherwise, the output won't be encoded correctly.
+
−
+
−For example::
+
−
+
−    json_serializer = serializers.get_serializer("json")
+
−    json_serializer.serialize(queryset, ensure_ascii=False, stream=response)
+
−
+
−Writing custom serializers
+
−``````````````````````````
+
−
+
−XXX ...