Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Merge pull request #815 from zerok/tickets/11971

Fixed #11971 -- Documented the serialization formats
  • Loading branch information...
commit b6aede326803bfdf18f932ec2fa8b9304467d29f 2 parents f56ca3f + 5612f54
Aymeric Augustin authored February 24, 2013

Showing 1 changed file with 91 additions and 5 deletions. Show diff stats Hide diff stats

  1. 96  docs/topics/serialization.txt
96  docs/topics/serialization.txt
@@ -162,11 +162,82 @@ Identifier  Information
162 162
 .. _json: http://json.org/
163 163
 .. _PyYAML: http://www.pyyaml.org/
164 164
 
165  
-Notes for specific serialization formats
166  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  165
+XML
  166
+~~~
  167
+
  168
+The basic XML serialization format is quite simple::
  169
+    
  170
+    <?xml version="1.0" encoding="utf-8"?>
  171
+    <django-objects version="1.0">
  172
+        <object pk="123" model="sessions.session">
  173
+            <field type="DateTimeField" name="expire_date">2013-01-16T08:16:59.844560+00:00</field>
  174
+            <!-- ... -->
  175
+        </object>
  176
+    </django-objects>
  177
+
  178
+The whole collection of objects that is either serialized or de-serialized is
  179
+represented by a ``<django-objects>``-tag which contains multiple
  180
+``<object>``-elements. Each such object has two attributes: "pk" and "model",
  181
+the latter being represented by the name of the app ("sessions") and the
  182
+lowercase name of the model ("session") separated by a dot.
  183
+
  184
+Each field of the object is serialized as a ``<field>``-element sporting the
  185
+fields "type" and "name". The text content of the element represents the value
  186
+that should be stored.
  187
+
  188
+Foreign keys and other relational fields are treated a little bit differently::
  189
+    
  190
+    <object pk="27" model="auth.permission">
  191
+        <!-- ... -->
  192
+        <field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>
  193
+        <!-- ... -->
  194
+    </object>
  195
+
  196
+In this example we specify that the auth.Permission object with the PK 24 has
  197
+a foreign key to the contenttypes.ContentType instance with the PK 9.
  198
+
  199
+ManyToMany-relations are exported for the model that binds them. For instance,
  200
+the auth.User model has such a relation to the auth.Permission model::
  201
+    
  202
+    <object pk="1" model="auth.user">
  203
+        <!-- ... -->
  204
+        <field to="auth.permission" name="user_permissions" rel="ManyToManyRel">
  205
+            <object pk="46"></object>
  206
+            <object pk="47"></object>
  207
+        </field>
  208
+    </object>
  209
+
  210
+This example links the given user with the permission models with PKs 46 and 47.
  211
+
  212
+JSON
  213
+~~~~
  214
+
  215
+When staying with the same example data as before it would be serialized as
  216
+JSON in the following way::
  217
+    
  218
+    [
  219
+        {
  220
+            "pk": "4b678b301dfd8a4e0dad910de3ae245b",
  221
+            "model": "sessions.session",
  222
+            "fields": {
  223
+                "expire_date": "2013-01-16T08:16:59.844Z",
  224
+                ...
  225
+            }
  226
+        }
  227
+    ]
  228
+
  229
+The formatting here is a bit simpler than with XML. The whole collection
  230
+is just represented as an array and the objects are represented by JSON objects
  231
+with three properties: "pk", "model" and "fields". "fields" is again an object
  232
+containing each field's name and value as property and property-value
  233
+respectively.
  234
+
  235
+Foreign keys just have the PK of the linked object as property value. 
  236
+ManyToMany-relations are serialized for the model that defines them and are
  237
+represented as a list of PKs.
167 238
 
168  
-json
169  
-^^^^
  239
+Date and datetime related types are treated in a special way by the JSON
  240
+serializer to make the format compatible with `ECMA-262`_.
170 241
 
171 242
 Be aware that not all Django output can be passed unmodified to :mod:`json`.
172 243
 In particular, :ref:`lazy translation objects <lazy-translations>` need a
@@ -175,14 +246,29 @@ In particular, :ref:`lazy translation objects <lazy-translations>` need a
175 246
     import json
176 247
     from django.utils.functional import Promise
177 248
     from django.utils.encoding import force_text
  249
+    from django.core.serializers.json import DjangoJSONEncoder
178 250
 
179  
-    class LazyEncoder(json.JSONEncoder):
  251
+    class LazyEncoder(DjangoJSONEncoder):
180 252
         def default(self, obj):
181 253
             if isinstance(obj, Promise):
182 254
                 return force_text(obj)
183 255
             return super(LazyEncoder, self).default(obj)
184 256
 
185 257
 .. _special encoder: http://docs.python.org/library/json.html#encoders-and-decoders
  258
+.. _ecma-262: http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.1.15
  259
+
  260
+YAML
  261
+~~~~
  262
+
  263
+YAML serialization looks quite similar to JSON. The object list is serialized
  264
+as a sequence mappings with the keys "pk", "model" and "fields". Each field is
  265
+again a mapping with the key being name of the field and the value the value::
  266
+    
  267
+    -   fields: {expire_date: !!timestamp '2013-01-16 08:16:59.844560+00:00'}
  268
+        model: sessions.session
  269
+        pk: 4b678b301dfd8a4e0dad910de3ae245b
  270
+
  271
+Referential fields are again just represented by the PK or sequence of PKs.
186 272
 
187 273
 .. _topics-serialization-natural-keys:
188 274
 

0 notes on commit b6aede3

Please sign in to comment.
Something went wrong with that request. Please try again.