|
1 ========================== |
|
2 Serializing Django objects |
|
3 ========================== |
|
4 |
|
5 .. note:: |
|
6 |
|
7 This API is currently under heavy development and may change -- |
|
8 perhaps drastically -- in the future. |
|
9 |
|
10 You have been warned. |
|
11 |
|
12 Django's serialization framework provides a mechanism for "translating" Django |
|
13 objects into other formats. Usually these other formats will be text-based and |
|
14 used for sending Django objects over a wire, but it's possible for a |
|
15 serializer to handle any format (text-based or not). |
|
16 |
|
17 Serializing data |
|
18 ---------------- |
|
19 |
|
20 At the highest level, serializing data is a very simple operation:: |
|
21 |
|
22 from django.core import serializers |
|
23 data = serializers.serialize("xml", SomeModel.objects.all()) |
|
24 |
|
25 The arguments to the ``serialize`` function are the format to serialize the |
|
26 data to (see `Serialization formats`_) and a QuerySet_ to serialize. |
|
27 (Actually, the second argument can be any iterator that yields Django objects, |
|
28 but it'll almost always be a QuerySet). |
|
29 |
|
30 .. _QuerySet: ../db_api/#retrieving-objects |
|
31 |
|
32 You can also use a serializer object directly:: |
|
33 |
|
34 XMLSerializer = serializers.get_serializer("xml") |
|
35 xml_serializer = XMLSerializer() |
|
36 xml_serializer.serialize(queryset) |
|
37 data = xml_serializer.getvalue() |
|
38 |
|
39 This is useful if you want to serialize data directly to a file-like object |
|
40 (which includes a HTTPResponse_):: |
|
41 |
|
42 out = open("file.xml", "w") |
|
43 xml_serializer.serialize(SomeModel.objects.all(), stream=out) |
|
44 |
|
45 .. _HTTPResponse: ../request_response/#httpresponse-objects |
|
46 |
|
47 Deserializing data |
|
48 ------------------ |
|
49 |
|
50 Deserializing data is also a fairly simple operation:: |
|
51 |
|
52 for obj in serializers.deserialize("xml", data): |
|
53 do_something_with(obj) |
|
54 |
|
55 As you can see, the ``deserialize`` function takes the same format argument as |
|
56 ``serialize``, a string or stream of data, and returns an iterator. |
|
57 |
|
58 However, here it gets slightly complicated. The objects returned by the |
|
59 ``deserialize`` iterator *aren't* simple Django objects. Instead, they are |
|
60 special ``DeserializedObject`` instances that wrap a created -- but unsaved -- |
|
61 object and any associated relationship data. |
|
62 |
|
63 Calling ``DeserializedObject.save()`` saves the object to the database. |
|
64 |
|
65 This ensures that deserializing is a non-destructive operation even if the |
|
66 data in your serialized representation doesn't match what's currently in the |
|
67 database. Usually, working with these ``DeserializedObject`` instances looks |
|
68 something like:: |
|
69 |
|
70 for deserialized_object in serializers.deserialize("xml", data): |
|
71 if object_should_be_saved(deserialized_object): |
|
72 obj.save() |
|
73 |
|
74 In other words, the usual use is to examine the deserialized objects to make |
|
75 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. |
|
76 |
|
77 The Django object itself can be inspected as ``deserialized_object.object``. |
|
78 |
|
79 Serialization formats |
|
80 --------------------- |
|
81 |
|
82 Django "ships" with a few included serializers: |
|
83 |
|
84 ========== ============================================================== |
|
85 Identifier Information |
|
86 ========== ============================================================== |
|
87 ``xml`` Serializes to and from a simple XML dialect. |
|
88 |
|
89 ``json`` Serializes to and from JSON_ (using a version of simplejson_ |
|
90 bundled with Django). |
|
91 |
|
92 ``python`` Translates to and from "simple" Python objects (lists, dicts, |
|
93 strings, etc.). Not really all that useful on its own, but |
|
94 used as a base for other serializers. |
|
95 ========== ============================================================== |
|
96 |
|
97 .. _json: http://json.org/ |
|
98 .. _simplejson: http://undefined.org/python/#simplejson |
|
99 |
|
100 Notes for specific serialization formats |
|
101 ---------------------------------------- |
|
102 |
|
103 json |
|
104 ~~~~ |
|
105 |
|
106 If you're using UTF-8 (or any other non-ASCII encoding) data with the JSON |
|
107 serializer, you must pass ``ensure_ascii=False`` as a parameter to the |
|
108 ``serialize()`` call. Otherwise, the output won't be encoded correctly. |
|
109 |
|
110 For example:: |
|
111 |
|
112 json_serializer = serializers.get_serializer("json") |
|
113 json_serializer.serialize(queryset, ensure_ascii=False, stream=response) |
|
114 |
|
115 Writing custom serializers |
|
116 `````````````````````````` |
|
117 |
|
118 XXX ... |