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).
\n\nAu plus haut niveau, la sérialisation de données est une opération très simple :
\nfrom django.core import serializers\ndata = serializers.serialize("xml", SomeModel.objects.all())\nLes 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).
Il est aussi possible d’utiliser directement un objet de sérialiseur :
\nXMLSerializer = serializers.get_serializer("xml")\nxml_serializer = XMLSerializer()\nxml_serializer.serialize(queryset)\ndata = xml_serializer.getvalue()\nC’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:\n xml_serializer.serialize(SomeModel.objects.all(), stream=out)\nLorsqu’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\ndata = serializers.serialize('xml', SomeModel.objects.all(), fields=('name','size'))\nDans 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.
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. Il suffit d’appeler 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é.
\nCependant, 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 :
\nclass Place(models.Model):\n name = models.CharField(max_length=50)\n\nclass Restaurant(Place):\n serves_hot_dogs = models.BooleanField(default=False)\nSi vous ne sérialisez que le modèle Restaurant:
data = serializers.serialize('xml', Restaurant.objects.all())\nles 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 = list(Restaurant.objects.all()) + list(Place.objects.all())\ndata = serializers.serialize('xml', all_objects)\nLa désérialisation de données est également une opération relativement simple :
\nfor obj in serializers.deserialize("xml", data):\n do_something_with(obj)\nComme 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 de simples objets Django. 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.
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):\n if object_should_be_saved(deserialized_object):\n deserialized_object.save()\nEn 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. Naturellement, si vous avez confiance dans votre source de données, vous pouvez simplement enregistrer l’objet et passer à la suite.
\nL’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)\nDjango prend en charge quelques formats de sérialisation, certains dépendant de l’installation de modules Python supplémentaires :
\nIdentifiant | \nInformation | \n
|---|---|
| \nSérialise vers et à partir d’un dialecte XML simple. | \n
| \nSérialise vers et à partir du format JSON. | \n
| \nSérialise en YAML (YAML Ain’t a Markup Language). Ce sérialiseur n’est disponible que si PyYAML est installé. | \n
Le format basique de sérialisation XML est très simple :
\n<?xml version="1.0" encoding="utf-8"?>\n<django-objects version="1.0">\n <object pk="123" model="sessions.session">\n <field type="DateTimeField" name="expire_date">2013-01-16T08:16:59.844560+00:00</field>\n <!-- ... -->\n </object>\n</django-objects>\nLa collection complète des objets 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 :
\n<object pk="27" model="auth.permission">\n <!-- ... -->\n <field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>\n <!-- ... -->\n</object>\nDans 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">\n <!-- ... -->\n <field to="auth.permission" name="user_permissions" rel="ManyToManyRel">\n <object pk="46"></object>\n <object pk="47"></object>\n </field>\n</object>\nCet exemple lie l’utilisateur donné avec les modèles de permission ayant les clés primaires 46 et 47.
\n\nTout en conservant les mêmes données d’exemple que précédemment, voici ce que donnerait leur sérialisation au format JSON :
\n[\n {\n "pk": "4b678b301dfd8a4e0dad910de3ae245b",\n "model": "sessions.session",\n "fields": {\n "expire_date": "2013-01-16T08:16:59.844Z",\n ...\n }\n }\n]\nLa 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.
\nLes clés étrangères ont simplement 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.
\nIl 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\n\nclass LazyEncoder(DjangoJSONEncoder):\n def default(self, obj):\n if isinstance(obj, YourCustomType):\n return str(obj)\n return super().default(obj)\nVous pouvez alors passer cls=LazyEncoder à la fonction serializers.serialize():
from django.core.serializers import serialize\n\nserialize('json', SomeModel.objects.all(), cls=LazyEncoder)\nNotez également que GeoDjango met à disposition un sérialiseur adapté à GeoJSON.
\nDjangoJSONEncoderLien vers cette rubrique#Le sérialiseur JSON utilise DjangoJSONEncoder pour le codage. C’est une sous-classe de JSONEncoder, qui ajoute le codage de types supplémentaires :
datetimeUne chaîne sous la forme AAAA-MM-JJTHH:mm:ss.sssZ ou AAAA-MM-JJTHH:mm:ss.sss+HH:MM telle que définie dans ECMA-262.
dateUne chaîne sous la forme AAAA-MM-JJ telle que définie dans ECMA-262.
timeUne chaîne sous la forme HH:MM:ss.sss telle que définie dans ECMA-262.
timedeltaUne 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 (objets django.utils.functional.lazy()), UUIDUne représentation textuelle de l’objet.
\nLa 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 :
\n- fields: {expire_date: !!timestamp '2013-01-16 08:16:59.844560+00:00'}\n model: sessions.session\n pk: 4b678b301dfd8a4e0dad910de3ae245b\nLes champs de référence ne sont également représentés que par la clé primaire ou une suite de clés primaires.
\nLa 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.
\nConsidé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.
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.
\nC’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.
\nConsidérons les deux modèles suivants :
\nfrom django.db import models\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=100)\n last_name = models.CharField(max_length=100)\n\n birthdate = models.DateField()\n\n class Meta:\n unique_together = (('first_name', 'last_name'),)\n\nclass Book(models.Model):\n name = models.CharField(max_length=100)\n author = models.ForeignKey(Person, on_delete=models.CASCADE)\nEn 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 :
...\n{\n "pk": 1,\n "model": "store.book",\n "fields": {\n "name": "Mostly Harmless",\n "author": 42\n }\n}\n...\nCette 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.
\nCependant, 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\n\nclass PersonManager(models.Manager):\n def get_by_natural_key(self, first_name, last_name):\n return self.get(first_name=first_name, last_name=last_name)\n\nclass Person(models.Model):\n objects = PersonManager()\n\n first_name = models.CharField(max_length=100)\n last_name = models.CharField(max_length=100)\n\n birthdate = models.DateField()\n\n class Meta:\n unique_together = (('first_name', 'last_name'),)\nLes livres peuvent maintenant utiliser la clé naturelle pour faire référence aux objets Person:
...\n{\n "pk": 1,\n "model": "store.book",\n "fields": {\n "name": "Mostly Harmless",\n "author": ["Douglas", "Adams"]\n }\n}\n...\nAu 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"].
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.
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 :
\nclass Person(models.Model):\n objects = PersonManager()\n\n first_name = models.CharField(max_length=100)\n last_name = models.CharField(max_length=100)\n\n birthdate = models.DateField()\n\n def natural_key(self):\n return (self.first_name, self.last_name)\n\n class Meta:\n unique_together = (('first_name', 'last_name'),)\nCette 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,\n... use_natural_foreign_keys=True, use_natural_primary_keys=True)\nLorsque 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 :
...\n{\n "model": "store.person",\n "fields": {\n "first_name": "Douglas",\n "last_name": "Adams",\n "birth_date": "1952-03-11",\n }\n}\n...\nCela 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.
\nSi 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.
Comme les clés naturelles dépendent de requêtes dans la base de données pour résoudre les références, il est important que les données existent avant qu’elles puissent être référencées. Il n’est pas possible de produire des « références en aval » avec les clés naturelles, les données référencées doivent exister avant de pouvoir inclure une référence de clé naturelle vers ces données.
\nPour respecter cette contrainte, 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.
\nPour 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):\n name = models.CharField(max_length=100)\n author = models.ForeignKey(Person, on_delete=models.CASCADE)\n\n def natural_key(self):\n return (self.name,) + self.author.natural_key()\nLa 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):\n return (self.name,) + self.author.natural_key()\nnatural_key.dependencies = ['example_app.person']\nCette 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.