Django のシリアライズフレームワークは、Django のモデルを他のフォーマットに「翻訳」する仕組みを提供します。通常、このような他のフォーマットはテキストベースや Django データをネットワーク越しに送信するために使われるフォーマットになりますが、シリアライザーはどんなフォーマットも (テキストベースと非テキストベースのいずれも) 処理可能です。
\n\n最も高いレベルでは、次のようにデータをシリアライズできます。
\nfrom django.core import serializers\n\ndata = serializers.serialize("xml", SomeModel.objects.all())\nserialize 関数の引数は、データをシリアライズするフォーマット (シリアライズフォーマット) とシリアライズする QuerySet です。(実際、第2引数は Django モデルのインスタンスを yield するどんなイテレータでも渡せますが、ほとんど場合は QuerySet になります。)
シリアライザーオブジェクトを次のように直接使用することもできます。
\nXMLSerializer = serializers.get_serializer("xml")\nxml_serializer = XMLSerializer()\nxml_serializer.serialize(queryset)\ndata = xml_serializer.getvalue()\nこれは次のようにデータをファイルライクなオブジェクト (HttpResponse を含む) に直接シリアライズしたい場合に便利です。
with open("file.xml", "w") as out:\n xml_serializer.serialize(SomeModel.objects.all(), stream=out)\nフィールドのサブセットのみをシリアライズしたい場合は、次のようにシリアライザーに fields 引数を指定できます。
from django.core import serializers\n\ndata = serializers.serialize("xml", SomeModel.objects.all(), fields=["name", "size"])\nこの例では、各モデルの name と size 属性だけがシリアライズされます。プライマリキーは常に出力結果内の pk 要素としてシリアライズされ、fields 部分には決して現れません。
抽象ベースクラス を使用して定義したモデルの場合、そのモデルをシリアライズするために特別なことは何もする必要がありません。シリアライズしたいオブジェクト (または複数のオブジェクト) 上でシリアライザーを呼べば、出力はシリアライズされたオブジェクトの完全な表現になります。
\nしかし、マルチテーブル継承 を利用したモデルの場合、そのモデルのすべてのベースクラスもシリアライズする必要があります。なぜなら、モデル上でローカルに定義されたフィールドだけがシリアライズされるためです。たとえば、次のようなモデルを考えてみてください。
\nclass Place(models.Model):\n name = models.CharField(max_length=50)\n\n\nclass Restaurant(Place):\n serves_hot_dogs = models.BooleanField(default=False)\nもし次のように Reastaurant モデルだけをシリアライズした場合、
\ndata = serializers.serialize("xml", Restaurant.objects.all())\nシリアライズされた出力のフィールドには、serves_hot_dogs 属性だけが含まれます。ベースクラスの name 属性は無視されます。
Restaurant インスタンスを完全にシリアライズするためには、Place モデルも同様にシリアライズする必要があります。
all_objects = [*Restaurant.objects.all(), *Place.objects.all()]\ndata = serializers.serialize("xml", all_objects)\nデータのデシリアライズも、シリアライズと非常によく似ています。
\nfor obj in serializers.deserialize("xml", data):\n do_something_with(obj)\n見ての通り、deserialize 関数は、serialize と同じ形式の引数であるデータの文字列またはストリームを取り、イテレータを返します。
しかし、ここで処理は少し複雑になります。deserialize イテレータによって返されるオブジェクトは、通常の Django オブジェクト ではありません。代わりに、作成された (ただし、保存されていない) オブジェクトと関連するリレーションデータをラップした、特別な DeserializedObject インスタンスです。
DeserializedObject.save() を呼ぶと、オブジェクトはデータベースに保存されます。
これにより、もしシリアライズされた表現内のデータが現在データベース内にあるデータと一致しなかったとしても、デシリアライズ処理は非破壊的な操作であることが保証されます。通常、DeserializedObject インスタンスを用いた操作は、次のようになります。
for deserialized_object in serializers.deserialize("xml", data):\n if object_should_be_saved(deserialized_object):\n deserialized_object.save()\n言い換えれば、通常の使用では、デシリアライズされたオブジェクトが保存する前に保存するのに「適している」ことを確認します。もしデータソースを信頼しているなら、代わりにオブジェクトを直接保存してそのまま先に進めます。
\nDjango オブジェクト自体は、deserialized_object.object として検査できます。シリアライズされたデータ内のフィールドがモデル上に存在しない場合は、ignorenonexistent 引数に True が渡されていない限り、DeserializationError が発生します。
serializers.deserialize("xml", data, ignorenonexistent=True)\nDjango は多数のシリアライズフォーマットをサポートしてします。一部のフォーマットはサードパーティの Python モジュールが必要です。
\n識別子 | \n情報 | \n
|---|---|
| \nシンプルな XML 方言のシリアライズ・デシリアライズを行います。 | \n
| \nJSON のシリアライズ・デシリアライズを行います。 | \n
| \nJSONL のシリアライズ・デシリアライズを行います。 | \n
| \nYAML (YAML Ain't a Markup Language) のシリアライズ・デシリアライズを行います。このシリアライザーは PyYAML がインストールされている場合のみ利用できます。 | \n
基本的なXMLのシリアライズフォーマットは以下のようなものです:
\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>\nシリアライズまたはデシリアライズされたオブジェクトのコレクション全体は、複数の <object> 要素を含む <djangoobjects> タグで表現されます。このようなオブジェクトはそれぞれ2つの属性を持ちます。"pk" と "model" です。後者はアプリの名前 ("sessions") とモデルの小文字の名前 ("session") をドットで区切って表します。
オブジェクトの各フィールドは "type "と "name "のフィールドを持つ <field> 要素としてシリアライズされます。要素のテキストコンテンツは格納されるべき値を表します。
外部キーとその他のリレーション先フィールドは、少し違う扱いになります:
\n<object pk="27" model="auth.permission">\n <!-- ... -->\n <field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>\n <!-- ... -->\n</object>\nこの例では、PK 27の auth.Permission オブジェクトが、PK 9の contenttypes.ContentType インスタンスに対する外部キーを持つように指定しています。
多対多のリレーションはそれらを結びつけるモデルに対してエクスポートされます。例えば、auth.User モデルは 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>\nこの例では、与えられたユーザーをPK46と47を持つパーミッションモデルにリンクしています。
\n\n以前と同じ例のデータを使うと、データは 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]\nこのフォーマットは、XML よりも少しシンプルです。コレクション全体は array として表現され、オブジェクトは3つのプロパティ "pk"、"model"、"fields" を持つ JSON オブジェクトとして表現されています。"fields" もオブジェクトであり、各フィールド名と値がそれぞれプロパティとプロパティ値として含まれています。
\n外部キーは、プロパティ値としてリンクされたオブジェクトの PK を持ちます。ManyToMany リレーションは、それを定義したモデルに対してシリアライズされ、PK のリストとして表現されます。
\nすべての Django 出力が未修正のまま json に渡せるとは限らないことに注意してください。たとえば、シリアライズするオブジェクトにカスタム型がある場合、そのためのカスタム json エンコーダを書く必要があります。以下のようなものが機能します。
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)\nそして、cls=LazyEncoder を serializers.serialize() 関数に渡します。
from django.core.serializers import serialize\n\nserialize("json", SomeModel.objects.all(), cls=LazyEncoder)\nGeoDjango は カスタマイズされた GeoJSON シリアライザー を提供していることにも注意してください。
\nDjangoJSONEncoderLink to this heading#JSON シリアライザーは DjangoJSONEncoder をエンコーディングに使用します。JSONEncoder のサブクラスであり、以下の追加の型を処理します。
datetimeECMA-262 で定義されている YYYY-MM-DDTHH:mm:ss.sssZ または YYYY-MM-DDTHH:mm:ss.sss+HH:MM という形式の文字列。
dateYYYY-MM-DD という形式の文字列は、ECMA-262 で定義されています。
timeHH:MM:ss.sss という形式の文字列は、ECMA-262 で定義されています。
timedelta期間を表現する文字列は ISO-8601 で定義されています。たとえば、timedelta(days=1, hours=2, seconds=3.4) は 'P1DT02H00M03.400000S' と表現されます。
Decimal, Promise (django.utils.functional.lazy() objects), UUIDオブジェクトの文字列表現です。
\nJSONL は JSON Lines の略です。このフォーマットでは、オブジェクトは改行で区切られ、各行には有効なJSONオブジェクトが含まれます。JSONLでシリアライズされたデータは次のようになります:
\n{"pk": "4b678b301dfd8a4e0dad910de3ae245b", "model": "sessions.session", "fields": {...}}\n{"pk": "88bea72c02274f3c9bf1cb2bb8cee4fc", "model": "sessions.session", "fields": {...}}\n{"pk": "9cf0e26691b64147a67e2a9f06ad7a53", "model": "sessions.session", "fields": {...}}\nJSONLは、データを一度にメモリに読み込むのではなく、一行ずつ処理できるため、大規模なデータベースにデータを入力するのに便利です。
\nYAML シリアライズは JSON にとてもよく似ています。オブジェクトリストは "pk"、"model"、"fields" を持つマッピングのシーケンスとしてシリアライズされます。各フィールドもマッピングで、キーがフィールド名、値が値になります。
\n- model: sessions.session\n pk: 4b678b301dfd8a4e0dad910de3ae245b\n fields:\n expire_date: 2013-01-16 08:16:59.844560+00:00\n参照フィールドは、同様に PK または PK のシーケンスとして表現されます。
\nデフォルトの外部キーと多対多リレーションのシリアライズ戦略は、オブジェクトのプライマリーキーの値をリレーション内にシリアライズするというものです。この戦略はほとんどのオブジェクトに対してうまく機能しますが、いくつかの状況で困難を引き起こします。
\nContentType を参照する外部キーを持つオブジェクトのリストの場合を考えてみてください。もしcontent type を参照するオブジェクトをシリアライズしようとした場合、最初に content type を参照する手段が必要になります。ContentType オブジェクトは Django がデータベースの同期処理の間に自動的に作成するため、与えられた content type のプライマリーキーは簡単には予測できず、migrate が実行される方法とタイミングに依存することになってしまいます。同じことは、特に Permission、Group、User を含む、オブジェクトを自動生成するすべてのモデルにも当てはまります。
利便性の問題もあります。integer id というのは、必ずしもオブジェクトを参照するための最も便利な方法というわけではありません。ときには、より自然な (ナチュラルな) 参照が助けになることがあります。
\nこのような理由のために Django が提供しているのが、ナチュラルキー (natural key) です。ナチュラルキーは、オブジェクトのインスタンスをプライマリーキーの値を使用せずに一意に識別するために使える値のタプルです。
\n次の2つのモデルを考えてみてください。
\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)\n通常は、Book のシリアライズされたデータは、著者 (author) を参照するために整数を使うことになります。たとえば、JSON では、Book は次のようにシリアライズされるでしょう。
...\n{"pk": 1, "model": "store.book", "fields": {"name": "Mostly Harmless", "author": 42}}\n...\nこれは、著者を参照するのに特に自然な方法とは言えません。著者のプライマリーキーの値を知っていなければなりませんし、しかも、プライマリーキーの値は安定していて予測可能でなければなりません。
\nしかし、Person にナチュラルキーの処理を追加した場合、フィクスチャはもっとずっと人間によってわかりやすくなります。ナチュラルキーの処理を追加するには、Person のデフォルトの Manager を get_by_natural_key() を使用して定義します。Person の場合、よいナチュラルキーは、first name と last name のペアになるでしょう。
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 ]\n新しい本では、Person オブジェクトを参照するためにナチュラルキーが使えます。
...\n{\n "pk": 1,\n "model": "store.book",\n "fields": {"name": "Mostly Harmless", "author": ["Douglas", "Adams"]},\n}\n...\nシリアライズされたデータをロードしようとするとき、Django は get_by_natural_key() メソッドを使って ["Douglas", "Adams"] を実際の Person オブジェクトのプライマリーキーに解決します。
プライマリーキーがないオブジェクトのデシリアライズには、モデルのマネージャに get_by_natural_key() メソッドがあるかどうかを常にチェックします。ある場合は、これを使用して、デシリアライズされるオブジェクトのプライマリーキーを設定します。
それでは、オブジェクトをシリアライズするときに、Django にナチュラルキーを発行させるにはどうすればいいのでしょうか？ はじめに、もう1つのメソッドを追加する必要があります。今回は、次のようにモデル自体に追加します。
\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)\nメソッドは、常にナチュラルキーの他ルプを返す必要があります。この例では、(first name, last name) です。そして、serializers.serialize() を呼ぶときに、use_natural_foreign_keys=True または 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... )\nuse_natural_foreign_keys=True が指定されたときは、Django は natural_key() メソッドを使用して、メソッドを定義している型のオブジェクトへの外部キーの参照をシリアライズします。
use_natural_primary_keys=True が指定されたときは、Django はこのオブジェクトのシリアライズされたデータ内に、プライマリーキーを提供しません。プライマリーキーは、デシリアライズ時に計算可能であるためです。
...\n{\n "model": "store.person",\n "fields": {\n "first_name": "Douglas",\n "last_name": "Adams",\n "birth_date": "1952-03-11",\n },\n}\n...\nこれは、シリアライズされたデータを既存のデータベースに読み込む必要があり、シリアライズされたプライマリキーの値がすでに使用されていないことを保証できず、デシリアライズされたオブジェクトが同じプライマリキーを保持していることを保証する必要がない場合に便利です。
\ndumpdata を使用してシリアライズデータを生成する場合は、 dumpdata --natural-foreign と dumpdata --natural-primary コマンドラインフラグを使用してナチュラルキーを生成します。
ナチュラル外部キー を使用するとき、データをシリアライズする必要があるけれども、オブジェクトの外部キーが参照している他のオブジェクトが、まだシリアライズされていないような場合があります。このことを「前方参照 (forward reference)」と呼びます。
\nたとえば、フィクスチャに次のようなオブジェクトがあると想定してください。
\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...\nこの状況を処理するには、serializers.deserialize() に handle_forward_references=True を渡す必要があります。これにより、DeserializedObject インスタンスに deferred_fields 属性が設定されます。この属性が None ではない DeserializedObject インスタンスを追跡して、後でそれらに対して save_deferred_fields() を呼び出す必要があります。
典型的な使用方法は次のようになります。
\nobjs_with_deferred_fields = []\n\nfor obj in serializers.deserialize("xml", 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()\nこれが機能するには、参照しているモデル上の ForeignKey に null=True が設定されている必要があります。
フィクスチャ内のオブジェクトの順番に注意することで、明示的に前方参照を扱わずに済むことがよくあります。
\nこれを支援するために、 dumpdata --natural-foreign オプションを使用して dumpdata を呼び出すと、標準のプライマリキーオブジェクトをシリアライズする前に、natural_key() メソッドを持つ任意のモデルがシリアライズされます。
しかし、これは必ずしも十分とは限りません。ナチュラルキーが別のオブジェクトを参照する場合 (ナチュラルキーの一部として外部キーまたは別のオブジェクトへのナチュラルキーを使用する場合)、ナチュラルキーが依存するオブジェクトが、ナチュラルキーが要求する前にシリアライズされたデータ内に存在することを保証できる必要があります。
\nこの順序を制御するには、 natural_key() メソッドに依存関係を定義します。これは natural_key() メソッド自体に dependencies 属性を設定することで行います。
たとえば、上の例の Book モデルにナチュラルキーを追加してみましょう:
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()\nBook のナチュラルキーは名前と著者の組み合わせです。つまり、 Person は Book の前にシリアライズされなければなりません。この依存関係を定義するために、1行追加します:
def natural_key(self):\n return (self.name,) + self.author.natural_key()\n\n\nnatural_key.dependencies = ["example_app.person"]\nこの定義により、すべての Person オブジェクトは Book オブジェクトよりも先にシリアライズされます。また、Book を参照するオブジェクトは Person と Book の両方がシリアライズされた後にシリアライズされます。