1
# -*- coding: utf-8 -*-
5
``django.core.serializers`` provides interfaces to converting Django querysets
6
to and from "flat" data (i.e. strings).
9
from django.db import models
11
class Category(models.Model):
12
name = models.CharField(max_length=20)
17
def __unicode__(self):
20
class Author(models.Model):
21
name = models.CharField(max_length=20)
26
def __unicode__(self):
29
class Article(models.Model):
30
author = models.ForeignKey(Author)
31
headline = models.CharField(max_length=50)
32
pub_date = models.DateTimeField()
33
categories = models.ManyToManyField(Category)
36
ordering = ('pub_date',)
38
def __unicode__(self):
41
class AuthorProfile(models.Model):
42
author = models.OneToOneField(Author, primary_key=True)
43
date_of_birth = models.DateField()
45
def __unicode__(self):
46
return u"Profile of %s" % self.author
48
class Actor(models.Model):
49
name = models.CharField(max_length=20, primary_key=True)
54
def __unicode__(self):
57
class Movie(models.Model):
58
actor = models.ForeignKey(Actor)
59
title = models.CharField(max_length=50)
64
def __unicode__(self):
67
class Score(models.Model):
68
score = models.FloatField()
70
__test__ = {'API_TESTS':"""
72
>>> from datetime import datetime
73
>>> sports = Category(name="Sports")
74
>>> music = Category(name="Music")
75
>>> op_ed = Category(name="Op-Ed")
76
>>> sports.save(); music.save(); op_ed.save()
78
>>> joe = Author(name="Joe")
79
>>> jane = Author(name="Jane")
80
>>> joe.save(); jane.save()
84
... headline = "Poker has no place on ESPN",
85
... pub_date = datetime(2006, 6, 16, 11, 00))
88
... headline = "Time to reform copyright",
89
... pub_date = datetime(2006, 6, 16, 13, 00, 11, 345))
90
>>> a1.save(); a2.save()
91
>>> a1.categories = [sports, op_ed]
92
>>> a2.categories = [music, op_ed]
94
# Serialize a queryset to XML
95
>>> from django.core import serializers
96
>>> xml = serializers.serialize("xml", Article.objects.all())
98
# The output is valid XML
99
>>> from xml.dom import minidom
100
>>> dom = minidom.parseString(xml)
102
# Deserializing has a similar interface, except that special DeserializedObject
103
# instances are returned. This is because data might have changed in the
104
# database since the data was serialized (we'll simulate that below).
105
>>> for obj in serializers.deserialize("xml", xml):
107
<DeserializedObject: Poker has no place on ESPN>
108
<DeserializedObject: Time to reform copyright>
110
# Deserializing data with different field values doesn't change anything in the
111
# database until we call save():
112
>>> xml = xml.replace("Poker has no place on ESPN", "Poker has no place on television")
113
>>> objs = list(serializers.deserialize("xml", xml))
115
# Even those I deserialized, the database hasn't been touched
116
>>> Article.objects.all()
117
[<Article: Poker has no place on ESPN>, <Article: Time to reform copyright>]
119
# But when I save, the data changes as you might except.
121
>>> Article.objects.all()
122
[<Article: Poker has no place on television>, <Article: Time to reform copyright>]
124
# Django also ships with a built-in JSON serializers
125
>>> json = serializers.serialize("json", Category.objects.filter(pk=2))
127
'[{"pk": 2, "model": "serializers.category", "fields": {"name": "Music"}}]'
129
# You can easily create new objects by deserializing data with an empty PK
130
# (It's easier to demo this with JSON...)
131
>>> new_author_json = '[{"pk": null, "model": "serializers.author", "fields": {"name": "Bill"}}]'
132
>>> for obj in serializers.deserialize("json", new_author_json):
134
>>> Author.objects.all()
135
[<Author: Bill>, <Author: Jane>, <Author: Joe>]
137
# All the serializers work the same
138
>>> json = serializers.serialize("json", Article.objects.all())
139
>>> for obj in serializers.deserialize("json", json):
141
<DeserializedObject: Poker has no place on television>
142
<DeserializedObject: Time to reform copyright>
144
>>> json = json.replace("Poker has no place on television", "Just kidding; I love TV poker")
145
>>> for obj in serializers.deserialize("json", json):
148
>>> Article.objects.all()
149
[<Article: Just kidding; I love TV poker>, <Article: Time to reform copyright>]
151
# If you use your own primary key field (such as a OneToOneField),
152
# it doesn't appear in the serialized field list - it replaces the
154
>>> profile = AuthorProfile(author=joe, date_of_birth=datetime(1970,1,1))
157
>>> json = serializers.serialize("json", AuthorProfile.objects.all())
159
'[{"pk": 1, "model": "serializers.authorprofile", "fields": {"date_of_birth": "1970-01-01"}}]'
161
>>> for obj in serializers.deserialize("json", json):
163
<DeserializedObject: Profile of Joe>
165
# Objects ids can be referenced before they are defined in the serialization data
166
# However, the deserialization process will need to be contained within a transaction
167
>>> json = '[{"pk": 3, "model": "serializers.article", "fields": {"headline": "Forward references pose no problem", "pub_date": "2006-06-16 15:00:00", "categories": [4, 1], "author": 4}}, {"pk": 4, "model": "serializers.category", "fields": {"name": "Reference"}}, {"pk": 4, "model": "serializers.author", "fields": {"name": "Agnes"}}]'
168
>>> from django.db import transaction
169
>>> transaction.enter_transaction_management()
170
>>> transaction.managed(True)
171
>>> for obj in serializers.deserialize("json", json):
174
>>> transaction.commit()
175
>>> transaction.leave_transaction_management()
177
>>> article = Article.objects.get(pk=3)
179
<Article: Forward references pose no problem>
180
>>> article.categories.all()
181
[<Category: Reference>, <Category: Sports>]
185
# Serializer output can be restricted to a subset of fields
186
>>> print serializers.serialize("json", Article.objects.all(), fields=('headline','pub_date'))
187
[{"pk": 1, "model": "serializers.article", "fields": {"headline": "Just kidding; I love TV poker", "pub_date": "2006-06-16 11:00:00"}}, {"pk": 2, "model": "serializers.article", "fields": {"headline": "Time to reform copyright", "pub_date": "2006-06-16 13:00:11"}}, {"pk": 3, "model": "serializers.article", "fields": {"headline": "Forward references pose no problem", "pub_date": "2006-06-16 15:00:00"}}]
189
# Every string is serialized as a unicode object, also primary key
191
>>> ac = Actor(name="Zażółć")
192
>>> mv = Movie(title="Gęślą jaźń", actor=ac)
193
>>> ac.save(); mv.save()
195
# Let's serialize our movie
196
>>> print serializers.serialize("json", [mv])
197
[{"pk": 1, "model": "serializers.movie", "fields": {"actor": "Za\u017c\u00f3\u0142\u0107", "title": "G\u0119\u015bl\u0105 ja\u017a\u0144"}}]
199
# Deserialization of movie
200
>>> list(serializers.deserialize('json', serializers.serialize('json', [mv])))[0].object.title
201
u'G\u0119\u015bl\u0105 ja\u017a\u0144'
203
# None is null after serialization to json
204
# Primary key is None in case of not saved model
205
>>> mv2 = Movie(title="Movie 2", actor=ac)
206
>>> print serializers.serialize("json", [mv2])
207
[{"pk": null, "model": "serializers.movie", "fields": {"actor": "Za\u017c\u00f3\u0142\u0107", "title": "Movie 2"}}]
209
# Deserialization of null returns None for pk
210
>>> print list(serializers.deserialize('json', serializers.serialize('json', [mv2])))[0].object.id
213
# Serialization and deserialization of floats:
214
>>> sc = Score(score=3.4)
215
>>> print serializers.serialize("json", [sc])
216
[{"pk": null, "model": "serializers.score", "fields": {"score": 3.4}}]
217
>>> print list(serializers.deserialize('json', serializers.serialize('json', [sc])))[0].object.score
224
__test__['YAML'] = """
227
>>> articles = Article.objects.all().order_by("id")[:2]
228
>>> from django.core import serializers
232
>>> serialized = serializers.serialize("yaml", articles)
237
headline: Just kidding; I love TV poker
238
pub_date: 2006-06-16 11:00:00
239
model: serializers.article
244
headline: Time to reform copyright
245
pub_date: 2006-06-16 13:00:11
246
model: serializers.article
250
>>> obs = list(serializers.deserialize("yaml", serialized))
253
<DeserializedObject: Just kidding; I love TV poker>
254
<DeserializedObject: Time to reform copyright>