Sérialisation d’objets Django¶
L’infrastructure de sérialisation de Django fournit un mécanisme pour « traduire » les modèles Django en d’autres formats. En général, ces autres formats sont basés sur du texte et utilisés pour envoyer des données de Django à travers le réseau, mais il est possible qu’un sérialiseur prenne en charge n’importe quel format (basé sur du texte ou non).
Voir aussi
Si vous voulez simplement extraire certaines données de vos tables pour les sérialiser, il est possible d’utiliser la commande de gestion dumpdata.
Sérialisation de données¶
Au plus haut niveau, les données peuvent être sérialisées comme ceci :
from django.core import serializers
data = serializers.serialize("xml", SomeModel.objects.all())
Les paramètres de la fonction serialize sont constitués du format dans lequel la sérialisation des données doit se faire (voir Formats de sérialisation) et d’un objet QuerySet contenant les données (en fait, le second paramètre peut être n’importe quel itérateur produisant des instances de modèles Django, mais il s’agit presque toujours d’un QuerySet).
-
django.core.serializers.get_serializer(format)¶
Il est aussi possible d’utiliser directement un objet de sérialiseur :
XMLSerializer = serializers.get_serializer("xml")
xml_serializer = XMLSerializer()
xml_serializer.serialize(queryset)
data = xml_serializer.getvalue()
C’est utile lorsque l’on veut sérialiser des données directement dans un objet de type fichier (ce qui inclut aussi HttpResponse) :
with open("file.xml", "w") as out:
xml_serializer.serialize(SomeModel.objects.all(), stream=out)
Note
Si vous appelez get_serializer() avec un format de sérialisation inconnu, une exception django.core.serializers.SerializerDoesNotExist est générée.
Sous-ensemble de champs¶
Lorsqu’on ne veut sérialiser qu’un sous-ensemble de champs, il est possible de renseigner le paramètre fields du sérialiseur :
from django.core import serializers
data = serializers.serialize('xml', SomeModel.objects.all(), fields=('name','size'))
Dans cet exemple, seuls les attributs name et size de chaque modèle seront sérialisés. La clé primaire est toujours sérialisée comme élément pk dans le résultat ; elle n’apparaît jamais dans la partie fields.
Note
Selon votre modèle, il n’est parfois pas possible de désérialiser un modèle qui n’a été sérialisé qu’avec un sous-ensemble de ses champs. Si un objet sérialisé ne comporte pas tous les champs obligatoires d’un modèle, la désérialisation ne sera pas capable d’enregistrer les instances désérialisées.
Modèles hérités¶
Si un modèle est défini par une classe de base abstraite, il n’y a rien de particulier à faire pour pouvoir sérialiser ce modèle. Appelez le sérialiseur sur l’objet (ou les objets) que vous voulez sérialiser et le résultat sera une représentation complète de l’objet sérialisé.
Cependant, si un modèle utilise de l’héritage multi-table, il sera alors aussi nécessaire de sérialiser toutes les classes de base du modèle. C’est parce que seuls les champs définis localement dans le modèle seront sérialisés. Par exemple, considérons les modèles suivants :
class Place(models.Model):
name = models.CharField(max_length=50)
class Restaurant(Place):
serves_hot_dogs = models.BooleanField(default=False)
Si vous ne sérialisez que le modèle Restaurant:
data = serializers.serialize('xml', Restaurant.objects.all())
les champs de la sortie sérialisée ne contiendront que l’attribut serves_hot_dogs. L’attribut name de la classe de base sera ignoré.
Afin de sérialiser complètement les instances de Restaurant, il sera aussi nécessaire de sérialiser les modèles Place:
all_objects = [*Restaurant.objects.all(), *Place.objects.all()]
data = serializers.serialize('xml', all_objects)
Désérialisation de données¶
La désérialisation de données est très semblable à la sérialisation :
for obj in serializers.deserialize("xml", data):
do_something_with(obj)
Comme vous pouvez le voir, la fonction deserialize accepte le même paramètre format que serialize, une chaîne ou un flux de données, et renvoie un itérateur.
Cependant, ça se complique un peu à cet endroit. Les objets renvoyés par l’itérateur deserialize ne sont pas des objets Django normaux. Il s’agit d’instances DeserializedObject spéciales qui englobent un objet crée mais non enregistré ainsi que les données de liaison associées.
L’appel à DeserializedObject.save() enregistre l’objet dans la base de données.
Note
Si l’attribut pk n’existe pas dans les données sérialisées ou vaut null, une nouvelle instance est enregistrée dans la base de données.
Cela garantit que la désérialisation est une opération non destructive, même si les données de la représentation sérialisée ne correspondent pas à ce qui se trouve actuellement dans le base de données. Généralement, voici comment l’on traite ces instances de DeserializedObject:
for deserialized_object in serializers.deserialize("xml", data):
if object_should_be_saved(deserialized_object):
deserialized_object.save()
En d’autres termes, l’utilisation habituelle est d’examiner les objets désérialisés pour s’assurer qu’ils sont « cohérents » avant de les enregistrer. Si vous avez confiance dans votre source de données, vous pouvez aussi enregistrer directement l’objet et passer à la suite.
L’objet Django lui-même peut être inspecté avec deserialized_object.object. Si des champs dans les données sérialisées n’existent pas dans un modèle, une exception DeserializationError est générée, sauf si le paramètre ignorenonexistent a été transmis avec la valeur True:
serializers.deserialize("xml", data, ignorenonexistent=True)
Formats de sérialisation¶
Django prend en charge quelques formats de sérialisation, certains dépendant de l’installation de modules Python supplémentaires :
| Identifiant | Information |
|---|---|
xml |
Sérialise vers et à partir d’un dialecte XML simple. |
json |
Sérialise vers et à partir du format JSON. |
yaml |
Sérialise en YAML (YAML Ain’t a Markup Language). Ce sérialiseur n’est disponible que si PyYAML est installé. |
XML¶
Le format basique de sérialisation XML ressemble à ceci :
<?xml version="1.0" encoding="utf-8"?>
<django-objects version="1.0">
<object pk="123" model="sessions.session">
<field type="DateTimeField" name="expire_date">2013-01-16T08:16:59.844560+00:00</field>
<!-- ... -->
</object>
</django-objects>
La collection complète des objets sérialisés ou désérialisés est représentée par une balise <django-objects> contenant plusieurs éléments <object>. Chacun de ces objets contient deux attributs : « pk » et « model », ce dernier étant constitué du nom de l’application (« sessions ») et du nom du modèle en minuscules (« session »), séparés par un point.
Chaque champ de l’objet est sérialisé comme élément <field> contenant les attributs « type » et « name » du champ. Le contenu textuel de l’élément représente la valeur à stocker pour le champ.
Les clés étrangères et les autres champs relationnels sont traités légèrement différemment :
<object pk="27" model="auth.permission">
<!-- ... -->
<field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>
<!-- ... -->
</object>
Dans cet exemple, l’objet auth.Permission ayant la clé primaire 27 possède une clé étrangère vers l’instance contenttypes.ContentType ayant la clé primaire 9.
Les relations plusieurs-à-plusieurs sont exportées pour le modèle qui fait office de lien. Par exemple, le modèle auth.User possède une telle relation vers le modèle auth.Permission:
<object pk="1" model="auth.user">
<!-- ... -->
<field to="auth.permission" name="user_permissions" rel="ManyToManyRel">
<object pk="46"></object>
<object pk="47"></object>
</field>
</object>
Cet exemple lie l’utilisateur donné avec les modèles de permission ayant les clés primaires 46 et 47.
Caractères de contrôle
Si le contenu à sérialiser contient des caractères de contrôle qui ne sont pas acceptés par le standard XML 1.0, la sérialisation échoue avec une exception ValueError. Lisez également l’explication du W3C dans le document HTML, XHTML, XML and Control Codes.
JSON¶
Tout en conservant les mêmes données d’exemple que précédemment, voici ce que donnerait leur sérialisation au format JSON :
[
{
"pk": "4b678b301dfd8a4e0dad910de3ae245b",
"model": "sessions.session",
"fields": {
"expire_date": "2013-01-16T08:16:59.844Z",
...
}
}
]
La mise en forme est ici un peu plus simple qu’en XML. L’ensemble de la collection est représentée par un seul tableau et les objets sont représentés par des objets JSON ayant trois propriétés : « pk », « model » et « fields ». « fields » est lui-même un objet contenant les noms et valeurs de chaque champ respectivement comme propriété et propriété-valeur.
Les clés étrangères ont la clé primaire de l’objet lié comme valeur de propriété. Les objets des relations plusieurs-à-plusieurs sont sérialisés avec le modèle qui les définit et sont représentés sous forme de liste de clés primaires.
Il faut savoir que certains contenus Django ne peuvent pas être transmis tels quels à json. Par exemple, si l’un de vos objets à sérialiser contient un type personnalisé, vous devrez écrire un codeur json dédié. Quelque chose comme ceci devrait fonctionner :
from django.core.serializers.json import DjangoJSONEncoder
class LazyEncoder(DjangoJSONEncoder):
def default(self, obj):
if isinstance(obj, YourCustomType):
return str(obj)
return super().default(obj)
Vous pouvez alors passer cls=LazyEncoder à la fonction serializers.serialize():
from django.core.serializers import serialize
serialize('json', SomeModel.objects.all(), cls=LazyEncoder)
Notez également que GeoDjango met à disposition un sérialiseur adapté à GeoJSON.
Toutes les données sont dorénavant codées en Unicode. Si vous avez besoin du comportement précédent, passez ensure_ascii=True à la fonction serializers.serialize().
DjangoJSONEncoder¶
-
class
django.core.serializers.json.DjangoJSONEncoder¶
Le sérialiseur JSON utilise DjangoJSONEncoder pour le codage. C’est une sous-classe de JSONEncoder, qui ajoute le codage de types supplémentaires :
datetime- Une chaîne sous la forme
AAAA-MM-JJTHH:mm:ss.sssZouAAAA-MM-JJTHH:mm:ss.sss+HH:MMtelle que définie dans ECMA-262. date- Une chaîne sous la forme
AAAA-MM-JJtelle que définie dans ECMA-262. time- Une chaîne sous la forme
HH:MM:ss.ssstelle que définie dans ECMA-262. timedelta- Une chaîne représentant une durée telle que définie par ISO-8601. Par exemple,
timedelta(days=1, hours=2, seconds=3.4)est représenté par'P1DT02H00M03.400000S'. Decimal,Promise(objetsdjango.utils.functional.lazy()),UUID- Une représentation textuelle de l’objet.
YAML¶
La sérialisation YAML ressemble beaucoup à celle de JSON. La liste d’objets est sérialisée comme une suite de correspondances avec les clés « pk », « model » et « fields ». Chaque champ est lui-même une correspondance entre la clé contenant le nom du champ et la valeur contenant la valeur du champ :
- fields: {expire_date: !!timestamp '2013-01-16 08:16:59.844560+00:00'}
model: sessions.session
pk: 4b678b301dfd8a4e0dad910de3ae245b
Les champs de référence sont également représentés par la clé primaire ou une suite de clés primaires.
Toutes les données sont dorénavant codées en Unicode. Si vous avez besoin du comportement précédent, passez allow_unicode=False à la fonction serializers.serialize().
Clés naturelles¶
La stratégie de sérialisation par défaut pour les clés étrangères et les relations plusieurs-à-plusieurs est de sérialiser la valeur des clés primaires des objets de la relation. Cette stratégie fonctionne bien pour la plupart des objets, mais elle peut provoquer des difficultés en certaines circonstances.
Considérons le cas d’une liste d’objets ayant une clé étrangère référençant ContentType. Si vous sérialisez un objet qui se réfère à un type de contenu, il faut d’abord pouvoir trouver un moyen de faire référence à ce type de contenu. Comme les objets ContentType sont créés automatiquement par Django durant le processus de synchronisation de la base de données, la clé primaire d’un type de contenu n’est pas facile à prédire ; cela dépend de la manière et du moment où migrate a été exécuté. C’est pareil pour tous les modèles qui génèrent automatiquement des objets, comme par exemple Permission, Group et User.
Avertissement
Vous ne devriez jamais inclure des objets générés automatiquement dans des instantanés ou d’autres données sérialisées. Il est possible qu’avec un peu de chance, les clés primaires de l’instantané correspondent à celles de la base de données et que le chargement de l’instantané passe sans autre. Mais dans le cas plus probable où elles ne correspondent pas, le chargement de l’instantané échouera avec une exception IntegrityError.
Il y a aussi des raisons plus pratiques. Un identifiant nombre entier n’est pas toujours la manière la plus intuitive de se référer à un objet ; parfois, il est bien utile de disposer d’une référence plus naturelle.
C’est pour ces raisons que Django fournit les clés naturelles. Une clé naturelle est un tuple de valeurs servant à identifier de manière unique une instance d’objet sans avoir besoin de la valeur de clé primaire.
Désérialisation des clés naturelles¶
Considérons les deux modèles suivants :
from django.db import models
class Person(models.Model):
first_name = models.CharField(max_length=100)
last_name = models.CharField(max_length=100)
birthdate = models.DateField()
class Meta:
unique_together = [['first_name', 'last_name']]
class Book(models.Model):
name = models.CharField(max_length=100)
author = models.ForeignKey(Person, on_delete=models.CASCADE)
En principe, les données sérialisées de Book utilisent un nombre entier pour se référer à l’auteur. Par exemple, en JSON, un objet Book pourrait être sérialisé comme :
...
{
"pk": 1,
"model": "store.book",
"fields": {
"name": "Mostly Harmless",
"author": 42
}
}
...
Cette manière de se référer à un auteur n’est pas particulièrement intuitive. Il est nécessaire de connaître la valeur de clé primaire de l’auteur concerné ; il faut aussi que la clé primaire soit stable et prédictible.
Cependant, si nous ajoutons la capacité de clé naturelle à Person, l’instantané prend tout de suite un air plus humain. Pour ajouter la capacité de clé naturelle, il s’agit de définir un gestionnaire par défaut pour Person avec une méthode get_by_natural_key(). Dans le cas de Person, on pourrait utiliser le prénom et le nom comme bonne clé naturelle :
from django.db import models
class PersonManager(models.Manager):
def get_by_natural_key(self, first_name, last_name):
return self.get(first_name=first_name, last_name=last_name)
class Person(models.Model):
first_name = models.CharField(max_length=100)
last_name = models.CharField(max_length=100)
birthdate = models.DateField()
objects = PersonManager()
class Meta:
unique_together = [['first_name', 'last_name']]
Les livres peuvent maintenant utiliser la clé naturelle pour faire référence aux objets Person:
...
{
"pk": 1,
"model": "store.book",
"fields": {
"name": "Mostly Harmless",
"author": ["Douglas", "Adams"]
}
}
...
Au moment de charger ces données sérialisées, Django utilise la méthode get_by_natural_key() pour obtenir la clé primaire d’un objet Person existant à partir des informations ["Douglas", "Adams"].
Note
Quels que soient les champs utilisés pour définir une clé primaire, ils doivent pouvoir identifier un objet de manière unique. Cela signifie généralement que le modèle possède une clause d’unicité (soit unique=True pour un seul champ ou unique_together pour plusieurs champs) pour le ou les champs composant la clé naturelle. Cependant, l’unicité ne doit pas nécessairement être garantie au niveau de la base de données. Si vous êtes sûr qu’un certain ensemble de champs sera effectivement unique, vous pouvez très bien utiliser ces champs comme clé naturelle.
La désérialisation d’objets sans clé primaire vérifie toujours si le gestionnaire du modèle possède une méthode get_by_natural_key() et l’utilise le cas échéant pour compléter la clé primaire des objets désérialisés.
Sérialisation des clés naturelles¶
Comment donc pousser Django à émettre une clé naturelle lorsqu’il sérialise un objet ? Premièrement, vous devez ajouter une autre méthode, cette fois dans le modèle lui-même :
class Person(models.Model):
first_name = models.CharField(max_length=100)
last_name = models.CharField(max_length=100)
birthdate = models.DateField()
objects = PersonManager()
class Meta:
unique_together = [['first_name', 'last_name']]
def natural_key(self):
return (self.first_name, self.last_name)
Cette méthode doit toujours renvoyer un tuple de clés naturelles ; dans cet exemple, il s’agit de (first name, last name). Puis, lors de l’appel à serializers.serialize(), il faut indiquer les paramètres use_natural_foreign_keys=True ou use_natural_primary_keys=True:
>>> serializers.serialize('json', [book1, book2], indent=2,
... use_natural_foreign_keys=True, use_natural_primary_keys=True)
Lorsque use_natural_foreign_keys=True est indiqué, Django utilise la méthode natural_key() pour sérialiser toute référence de clé étrangère à des objets d’un type définissant cette méthode.
Lorsque use_natural_primary_keys=True est indiqué, Django ne produit pas de clé primaire dans les données sérialisées de cet objet dans la mesure où elle peut être calculée durant la désérialisation :
...
{
"model": "store.person",
"fields": {
"first_name": "Douglas",
"last_name": "Adams",
"birth_date": "1952-03-11",
}
}
...
Cela peut être utile lorsqu’il y a besoin de charger des données sérialisées dans une base de données existante et qu’il n’est pas possible de garantir que les valeurs de clés primaires sérialisées ne sont pas déjà utilisées, et qu’il n’est pas nécessaire de conserver les clés primaires exactes des objets désérialisés.
Si vous utilisez dumpdata pour générer des données sérialisées, utilisez les options de ligne de commande dumpdata --natural-foreign et dumpdata --natural-primary pour générer des clés naturelles.
Note
Il n’est pas obligatoire de définir à la fois natural_key() et get_by_natural_key(). Si vous ne souhaitez pas que Django produise des clés naturelles pendant la sérialisation mais que vous voulez conserver la possibilité de charger des clés naturelles, vous pouvez choisir de n’implémenter que la méthode natural_key().
Inversement, si (pour une raison étrange) vous voulez que Django produise des clés naturelles pendant la sérialisation, mais qu’il ne puisse pas charger ces valeurs, il suffit d’implémenter la méthode get_by_natural_key().
Clés naturelles et références en aval¶
Parfois, lors de l’utilisation de clés étrangères naturelles, il est nécessaire de désérialiser des données d’un objet possédant une clé étrangère se référant à un autre objet pas encore sérialisé. On appelle cela une « référence en aval ».
Par exemple, supposons que votre instantané contiennent les objets suivants
...
{
"model": "store.book",
"fields": {
"name": "Mostly Harmless",
"author": ["Douglas", "Adams"]
}
},
...
{
"model": "store.person",
"fields": {
"first_name": "Douglas",
"last_name": "Adams"
}
},
...
Afin de pouvoir gérer cette situation, il faut passer handle_forward_references=True à serializers.deserialize(). Cela marquera l’attribut deferred_fields sur les instances DeserializedObject. Vous devez ensuite garder la trace des instances DeserializedObject où cet attribute n’est pas None et appeler plus tard save_deferred_fields() sur ces instances.
Voici à quoi peut ressembler une utilisation typique :
objs_with_deferred_fields = []
for obj in serializers.deserialize('xml', data, handle_forward_references=True):
obj.save()
if obj.deferred_fields is not None:
objs_with_deferred_fields.append(obj)
for obj in objs_with_deferred_fields:
obj.save_deferred_fields()
Pour que ça fonctionne, la clé ForeignKey du modèle qui y fait référence doit avoir null=True.
Dépendances durant la sérialisation¶
Il est souvent possible d’éviter de devoir gérer explicitement les références en aval en prenant soin de placer les objets d’un instantané dans le bon ordre.
Pour aider à faire cela, les appels à dumpdata utilisant l’option dumpdata --natural-foreign sérialisent en premier les modèles possédant une méthode natural_key(), avant de sérialiser les objets à l’aide de leur clé primaire standard.
Cependant, ce n’est pas toujours suffisant. Si une clé naturelle se réfère à un autre objet (en utilisant une clé étrangère ou une clé naturelle vers un autre objet faisant partie d’une clé naturelle), il faut être capable de garantir que les objets dont dépend une clé naturelle apparaissent dans les données sérialisées avant la clé naturelle qui en a besoin.
Pour contrôler cet ordre d’apparition, il est possible de définir des dépendances dans les méthodes natural_key(). Cela se fait en définissant un attribut dependencies sur la méthode natural_key() elle-même.
Par exemple, ajoutons une clé naturelle au modèle Book à partir de l’exemple ci-dessus :
class Book(models.Model):
name = models.CharField(max_length=100)
author = models.ForeignKey(Person, on_delete=models.CASCADE)
def natural_key(self):
return (self.name,) + self.author.natural_key()
La clé naturelle d’un objet Book est une combinaison de son nom et de son auteur. Cela signifie que Person doit être sérialisé avant Book. Pour définir cette dépendance, nous ajoutons une ligne supplémentaire :
def natural_key(self):
return (self.name,) + self.author.natural_key()
natural_key.dependencies = ['example_app.person']
Cette définition garantit que tous les objets Person sont sérialisés avant les objets Book. Sur le même principe, tout objet référençant Book sera sérialisé après les objets Person et Book.
