Djangos serialiseringsramverk tillhandahåller en mekanism för att ”översätta” Django-modeller till andra format. Vanligtvis kommer dessa andra format att vara textbaserade och användas för att skicka Django-data över en tråd, men det är möjligt för en serializer att hantera vilket format som helst (textbaserat eller inte).
\n\nPå den högsta nivån kan du serialisera data så här:
\nfrom django.core import serializers\n\ndata = serializers.serialize("json", SomeModel.objects.all())\nArgumenten till funktionen serialize är formatet att serialisera data till (se Serialiseringsformat) och en QuerySet att serialisera. (Egentligen kan det andra argumentet vara vilken iterator som helst som ger Django-modellinstanser, men det kommer nästan alltid att vara en QuerySet).
Du kan också använda ett serializer-objekt direkt:
\nJSONSerializer = serializers.get_serializer("json")\njson_serializer = JSONSerializer()\njson_serializer.serialize(queryset)\ndata = json_serializer.getvalue()\nDetta är användbart om du vill serialisera data direkt till ett filliknande objekt (som innehåller en HttpResponse):
with open("file.json", "w") as out:\n json_serializer.serialize(SomeModel.objects.all(), stream=out)\nOm du bara vill att en delmängd av fälten ska serialiseras kan du ange ett fields-argument till serializer:
from django.core import serializers\n\ndata = serializers.serialize("json", SomeModel.objects.all(), fields=["name", "size"])\nI det här exemplet serialiseras endast attributen name och size för varje modell. Primärnyckeln serialiseras alltid som elementet pk i resultatet; den visas aldrig i delen fields.
Om du har en modell som definieras med hjälp av en abstrakt basklass behöver du inte göra något särskilt för att serialisera den modellen. Anropa serialiseraren på det objekt (eller de objekt) som du vill serialisera, så kommer utdata att vara en fullständig representation av det serialiserade objektet.
\nMen om du har en modell som använder multi-table inheritance, måste du också serialisera alla basklasser för modellen. Detta beror på att endast de fält som är lokalt definierade i modellen kommer att serialiseras. Tänk till exempel på följande modeller:
\nclass Place(models.Model):\n name = models.CharField(max_length=50)\n\n\nclass Restaurant(Place):\n serves_hot_dogs = models.BooleanField(default=False)\nOm du bara serialiserar restaurangmodellen:
\ndata = serializers.serialize("json", Restaurant.objects.all())\nfälten på den serialiserade utdata kommer endast att innehålla attributet serves_hot_dogs. Attributet name för basklassen kommer att ignoreras.
För att fullt ut kunna serialisera dina Restaurant-instanser måste du också serialisera Place-modellerna:
all_objects = [*Restaurant.objects.all(), *Place.objects.all()]\ndata = serializers.serialize("json", all_objects)\nDeserialisering av data är mycket likt serialisering av dem:
\nfor obj in serializers.deserialize("json", data):\n do_something_with(obj)\nSom du kan se tar funktionen deserialize samma formatargument som serialize, en sträng eller dataström, och returnerar en iterator.
Här blir det dock något komplicerat. De objekt som returneras av deserialize iterator är inte vanliga Django-objekt. Istället är de speciella DeserializedObject-instanser som omsluter ett skapat - men osparat - objekt och alla associerade relationsdata.
Genom att anropa DeserializedObject.save() sparas objektet i databasen.
Detta säkerställer att deserialisering är en icke-destruktiv operation även om data i din serialiserade representation inte matchar vad som för närvarande finns i databasen. Vanligtvis ser arbetet med dessa DeserializedObject-instanser ut ungefär som:
for deserialized_object in serializers.deserialize("json", data):\n if object_should_be_saved(deserialized_object):\n deserialized_object.save()\nMed andra ord är den vanliga användningen att undersöka de deserialiserade objekten för att se till att de är ”lämpliga” att spara innan man gör det. Om du litar på din datakälla kan du istället spara objektet direkt och gå vidare.
\nDjango-objektet i sig kan inspekteras som deserialized_object.object. Om fält i de serialiserade data inte finns på en modell, kommer ett DeserializationError att uppstå om inte ignorenonexistent argumentet skickas in som True:
serializers.deserialize("json", data, ignorenonexistent=True)\nDjango stöder ett antal serialiseringsformat, varav vissa kräver att du installerar Python-moduler från tredje part:
\nIdentifierare | \nInformation | \n
|---|---|
| \nSerialiserar till och från en enkel XML-dialekt. | \n
| \nSerialiserar till och från JSON. | \n
| \nSerialiserar till och från JSONL. | \n
| \nSerialiserar till YAML (YAML är inte ett märkspråk). Denna serialiserare är endast tillgänglig om PyYAML är installerat. | \n
Det grundläggande XML-serialiseringsformatet ser ut så här:
\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>\nHela samlingen av objekt som antingen serialiseras eller deserialiseras representeras av en <django-objects>-tagg som innehåller flera <object>-element. Varje sådant objekt har två attribut: ”pk” och ”model”, där det senare representeras av appens namn (”sessions”) och modellens namn (”session”) med gemener, åtskilda av en punkt.
Varje fält i objektet serialiseras som ett <field>-element med fälten ”type” och ”name”. Elementets textinnehåll representerar det värde som ska lagras.
Utländska nycklar och andra relationsfält behandlas på ett lite annorlunda sätt:
\n<object pk="27" model="auth.permission">\n <!-- ... -->\n <field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>\n <!-- ... -->\n</object>\nI det här exemplet anger vi att objektet auth.Permission med PK 27 har en främmande nyckel till instansen contenttypes.ContentType med PK 9.
ManyToMany-relationer exporteras för den modell som binder dem. Till exempel har modellen auth.User en sådan relation till modellen 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>\nI det här exemplet kopplas den angivna användaren till behörighetsmodellerna med PK 46 och 47.
\n\nOm vi fortsätter med samma exempel på data som tidigare skulle de serialiseras som JSON på följande sätt:
\n[\n {\n "pk": "4b678b301dfd8a4e0dad910de3ae245b",\n "model": "sessions.session",\n "fields": {\n "expire_date": "2013-01-16T08:16:59.844Z",\n # ...\n },\n }\n]\nFormateringen här är lite enklare än med XML. Hela samlingen representeras bara som en array och objekten representeras av JSON-objekt med tre egenskaper: ”pk”, ”model” och ”fields”. ”fields” är återigen ett objekt som innehåller varje fälts namn och värde som property respektive property-value.
\nForeign keys har PK för det länkade objektet som egenskapsvärde. ManyToMany-relationer serialiseras för den modell som definierar dem och representeras som en lista med PK:er.
\nVar medveten om att inte alla Django-utdata kan skickas oförändrade till json. Om du till exempel har någon anpassad typ i ett objekt som ska serialiseras, måste du skriva en anpassad json-kodare för det. Något liknande detta kommer att fungera:
from django.core.serializers.json import DjangoJSONEncoder\n\n\nclass LazyEncoder(DjangoJSONEncoder):\n def default(self, obj):\n if isinstance(obj, YourCustomType):\n return str(obj)\n return super().default(obj)\nDu kan sedan skicka cls=LazyEncoder till funktionen serializers.serialize():
from django.core.serializers import serialize\n\nserialize("json", SomeModel.objects.all(), cls=LazyEncoder)\nObservera också att GeoDjango tillhandahåller en customized GeoJSON serializer.
\nDjangoJSONEncoderLink to this heading#JSON-serialisatorn använder DjangoJSONEncoder för kodning. Den är en underklass till JSONEncoder och hanterar dessa ytterligare typer:
datetimeEn sträng av formen YYYY-MM-DDTHH:mm:ss.sssZ eller YYY-MM-DDTHH:mm:ss.sss+HH:MM enligt definitionen i ECMA-262.
dateEn sträng av formen YYYY-MM-DD enligt definitionen i ECMA-262.
timeEn sträng av formen HH:MM:ss.sss enligt definitionen i ECMA-262.
timedeltaEn sträng som representerar en varaktighet enligt definitionen i ISO-8601. Till exempel representeras timedelta(days=1, hours=2, seconds=3.4) som 'P1DT02H00M03.400000S'.
Decimal, Promise (django.utils.functional.lazy() objekt), UUIDEn strängrepresentation av objektet.
\nJSONL står för JSON Lines. I det här formatet separeras objekt med nya rader och varje rad innehåller ett giltigt JSON-objekt. JSONL-serialiserade data ser ut så här:
\n{"pk": "4b678b301dfd8a4e0dad910de3ae245b", "model": "sessions.session", "fields": {...}}\n{"pk": "88bea72c02274f3c9bf1cb2bb8cee4fc", "model": "sessions.session", "fields": {...}}\n{"pk": "9cf0e26691b64147a67e2a9f06ad7a53", "model": "sessions.session", "fields": {...}}\nJSONL kan vara användbart för att fylla på stora databaser, eftersom data kan bearbetas rad för rad i stället för att laddas in i minnet på en gång.
\nYAML-serialisering ser ganska lik ut som JSON. Objektlistan serialiseras som en sekvens mappningar med nycklarna ”pk”, ”model” och ”fields”. Varje fält är återigen en mappning där nyckeln är namnet på fältet och värdet är värdet:
\n- model: sessions.session\n pk: 4b678b301dfd8a4e0dad910de3ae245b\n fields:\n expire_date: 2013-01-16 08:16:59.844560+00:00\nReferensfält representeras återigen av PK eller en sekvens av PK.
\nFörutom standardformaten kan du skapa ett anpassat serialiseringsformat.
\nLåt oss till exempel titta på en serializer och deserializer för csv. Definiera först en klass för Serializer och en för Deserializer. Dessa kan åsidosätta befintliga serialiseringsformatklasser:
väg/till/custom_csv_serializer.py import csv\n\n from django.apps import apps\n from django.core import serializers\n from django.core.serializers.base import DeserializationError\n\n\n class Serializer(serializers.python.Serializer):\n def get_dump_object(self, obj):\n dumped_object = super().get_dump_object(obj)\n row = [dumped_object["model"], str(dumped_object["pk"])]\n row += [str(value) for value in dumped_object["fields"].values()]\n return ",".join(row), dumped_object["model"]\n\n def end_object(self, obj):\n dumped_object_str, model = self.get_dump_object(obj)\n if self.first:\n fields = [field.name for field in apps.get_model(model)._meta.fields]\n header = ",".join(fields)\n self.stream.write(f"model,{header}\\n")\n self.stream.write(f"{dumped_object_str}\\n")\n\n def getvalue(self):\n return super(serializers.python.Serializer, self).getvalue()\n\n\n class Deserializer(serializers.python.Deserializer):\n def __init__(self, stream_or_string, **options):\n if isinstance(stream_or_string, bytes):\n stream_or_string = stream_or_string.decode()\n if isinstance(stream_or_string, str):\n stream_or_string = stream_or_string.splitlines()\n try:\n objects = csv.DictReader(stream_or_string)\n except Exception as exc:\n raise DeserializationError() from exc\n super().__init__(objects, **options)\n\n def _handle_object(self, obj):\n try:\n model_fields = apps.get_model(obj["model"])._meta.fields\n obj["fields"] = {\n field.name: obj[field.name]\n for field in model_fields\n if field.name in obj\n }\n yield from super()._handle_object(obj)\n except (GeneratorExit, DeserializationError):\n raise\n except Exception as exc:\n raise DeserializationError(f"Error deserializing object: {exc}") from exc\nLägg sedan till modulen som innehåller serializer-definitionerna i din SERIALIZATION_MODULES setting:
SERIALIZATION_MODULES = {\n "csv": "path.to.custom_csv_serializer",\n "json": "django.core.serializers.json",\n}\nStandardstrategin för serialisering av främmande nycklar och många-till-många-relationer är att serialisera värdet på primärnyckeln för objekten i relationen. Denna strategi fungerar bra för de flesta objekt, men den kan orsaka problem under vissa omständigheter.
\nTänk på fallet med en lista över objekt som har en främmande nyckel som refererar till ContentType. Om du ska serialisera ett objekt som hänvisar till en innehållstyp måste du ha ett sätt att hänvisa till den innehållstypen till att börja med. Eftersom ContentType-objekt automatiskt skapas av Django under databassynkroniseringsprocessen är primärnyckeln för en viss innehållstyp inte lätt att förutsäga; det beror på hur och när migrate kördes. Detta gäller för alla modeller som automatiskt genererar objekt, särskilt inklusive Permission, Group och User.
Det är också en fråga om bekvämlighet. Ett heltals-id är inte alltid det mest praktiska sättet att referera till ett objekt; ibland skulle en mer naturlig referens vara till hjälp.
\nDet är av dessa skäl som Django tillhandahåller naturliga nycklar. En naturlig nyckel är en tupel av värden som kan användas för att unikt identifiera en objektinstans utan att använda det primära nyckelvärdet.
\nTänk på följande två modeller:
\nfrom django.db import models\n\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 constraints = [\n models.UniqueConstraint(\n fields=["first_name", "last_name"],\n name="unique_first_last_name",\n ),\n ]\n\n\nclass Book(models.Model):\n name = models.CharField(max_length=100)\n author = models.ForeignKey(Person, on_delete=models.CASCADE)\nNormalt skulle serialiserade data för Book använda ett heltal för att hänvisa till författaren. I JSON kan en bok t.ex. serialiseras som:
...\n{"pk": 1, "model": "store.book", "fields": {"name": "Mostly Harmless", "author": 42}}\n...\nDet här är inte ett särskilt naturligt sätt att hänvisa till en författare. Det kräver att du känner till det primära nyckelvärdet för författaren; det kräver också att detta primära nyckelvärde är stabilt och förutsägbart.
\nMen om vi lägger till naturlig nyckelhantering i Person blir fixturen mycket mer human. För att lägga till hantering av naturliga nycklar definierar du en standardhanterare för Person med en get_by_natural_key()-metod. I fallet med en Person kan en bra naturlig nyckel vara paret av för- och efternamn:
from django.db import models\n\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\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=100)\n last_name = models.CharField(max_length=100)\n birthdate = models.DateField()\n\n objects = PersonManager()\n\n class Meta:\n constraints = [\n models.UniqueConstraint(\n fields=["first_name", "last_name"],\n name="unique_first_last_name",\n ),\n ]\nNu kan böcker använda den naturliga nyckeln för att hänvisa till Person-objekt:
...\n{\n "pk": 1,\n "model": "store.book",\n "fields": {"name": "Mostly Harmless", "author": ["Douglas", "Adams"]},\n}\n...\nNär du försöker ladda dessa serialiserade data kommer Django att använda metoden get_by_natural_key() för att lösa ["Douglas", "Adams"] till primärnyckeln för ett faktiskt Person-objekt.
Deserialisering av objekt utan primärnyckel kontrollerar alltid om modellens manager har en get_by_natural_key()-metod och om så är fallet används den för att fylla i det deserialiserade objektets primärnyckel.
Så hur får man Django att ge ut en naturlig nyckel när man serialiserar ett objekt? För det första måste du lägga till en annan metod - den här gången till själva modellen:
\nclass Person(models.Model):\n first_name = models.CharField(max_length=100)\n last_name = models.CharField(max_length=100)\n birthdate = models.DateField()\n\n objects = PersonManager()\n\n class Meta:\n constraints = [\n models.UniqueConstraint(\n fields=["first_name", "last_name"],\n name="unique_first_last_name",\n ),\n ]\n\n def natural_key(self):\n return (self.first_name, self.last_name)\nDen metoden ska alltid returnera en tupel med naturliga nycklar - i det här exemplet (förnamn, efternamn). När du sedan anropar serializers.serialize() ger du argumenten use_natural_foreign_keys=True eller use_natural_primary_keys=True:
>>> serializers.serialize(\n... "json",\n... [book1, book2],\n... indent=2,\n... use_natural_foreign_keys=True,\n... use_natural_primary_keys=True,\n... )\nNär use_natural_foreign_keys=True anges kommer Django att använda metoden natural_key() för att serialisera alla främmande nyckelreferenser till objekt av den typ som definierar metoden.
När use_natural_primary_keys=True anges kommer Django inte att tillhandahålla den primära nyckeln i de serialiserade data för detta objekt eftersom den kan beräknas under deserialisering:
...\n{\n "model": "store.person",\n "fields": {\n "first_name": "Douglas",\n "last_name": "Adams",\n "birth_date": "1952-03-11",\n },\n}\n...\nDetta kan vara användbart när du behöver ladda serialiserade data i en befintlig databas och du inte kan garantera att det serialiserade primärnyckelvärdet inte redan används, och inte behöver säkerställa att deserialiserade objekt behåller samma primärnycklar.
\nOm du använder dumpdata för att generera serialiserade data kan du använda kommandoradsflaggorna dumpdata --natural-foreign och dumpdata --natural-primary för att generera naturliga nycklar.
Ibland när du använder natural foreign keys behöver du deserialisera data där ett objekt har en främmande nyckel som refererar till ett annat objekt som ännu inte har deserialiserats. Detta kallas för en ”framåtriktad referens”.
\nAnta t.ex. att du har följande objekt i din fixtur:
\n...\n{\n "model": "store.book",\n "fields": {"name": "Mostly Harmless", "author": ["Douglas", "Adams"]},\n},\n...\n{"model": "store.person", "fields": {"first_name": "Douglas", "last_name": "Adams"}},\n...\nFör att hantera denna situation måste du skicka handle_forward_references=True till serializers.deserialize(). Detta kommer att ställa in attributet deferred_fields på DeserializedObject-instanser. Du kommer att behöva hålla reda på DeserializedObject instanser där detta attribut inte är None och senare anropa save_deferred_fields() på dem.
Typisk användning ser ut så här:
\nobjs_with_deferred_fields = []\n\nfor obj in serializers.deserialize("json", data, handle_forward_references=True):\n obj.save()\n if obj.deferred_fields is not None:\n objs_with_deferred_fields.append(obj)\n\nfor obj in objs_with_deferred_fields:\n obj.save_deferred_fields()\nFör att detta ska fungera måste ForeignKey på referensmodellen ha null=True.
Det är ofta möjligt att undvika att uttryckligen behöva hantera framåtriktade referenser genom att vara försiktig med ordningsföljden för objekt inom en fixtur.
\nFör att hjälpa till med detta kommer anrop till dumpdata som använder alternativet dumpdata --natural-foreign att serialisera alla modeller med en natural_key()-metod före serialisering av vanliga primärnyckelobjekt.
Detta kanske dock inte alltid är tillräckligt. Om din naturliga nyckel hänvisar till ett annat objekt (genom att använda en främmande nyckel eller en naturlig nyckel till ett annat objekt som en del av en naturlig nyckel), måste du kunna säkerställa att de objekt som en naturlig nyckel är beroende av förekommer i de serialiserade data innan den naturliga nyckeln kräver dem.
\nFör att kontrollera denna ordning kan du definiera beroenden på dina natural_key()-metoder. Detta gör du genom att ställa in ett dependencies attribut på själva natural_key() metoden.
Låt oss till exempel lägga till en naturlig nyckel i modellen Book från exemplet ovan:
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()\nDen naturliga nyckeln för en Book är en kombination av dess namn och dess författare. Detta innebär att Person måste serialiseras före Book. För att definiera detta beroende lägger vi till en extra rad:
def natural_key(self):\n return (self.name,) + self.author.natural_key()\n\n\nnatural_key.dependencies = ["example_app.person"]\nDenna definition säkerställer att alla Person-objekt serialiseras före alla Book-objekt. I sin tur kommer alla objekt som refererar till Book att serialiseras efter att både Person och Book har serialiserats.