Подмножество полей¶

Если вы хотите, чтобы сериализовалось только подмножество полей, вы можете указать аргумент fields для сериализатора:

from django.core import serializers
data = serializers.serialize('xml', SomeModel.objects.all(), fields=('name','size'))

В этом примере будут сериализованы только атрибуты name и size каждой модели. Первичный ключ всегда сериализуется как элемент pk в результирующем выводе; он никогда не появляется в части «поля».

Унаследованные модели¶

Если у вас есть модель, определенная с использованием абстрактного базового класса, вам не нужно делать ничего особенного для сериализации этой модели. Вызовите сериализатор объекта (или объектов), который вы хотите сериализовать, и выходные данные будут полным представлением сериализованного объекта.

Однако если у вас есть модель, использующая многотабличное наследование, вам также необходимо сериализовать все базовые классы для модели. Это связано с тем, что сериализоваться будут только те поля, которые локально определены в модели. Например, рассмотрим следующие модели:

class Place(models.Model):
    name = models.CharField(max_length=50)

class Restaurant(Place):
    serves_hot_dogs = models.BooleanField(default=False)

Если вы сериализуете только модель ресторана:

data = serializers.serialize('xml', Restaurant.objects.all())

поля сериализованного вывода будут содержать только атрибутserves_hot_dogs. Атрибут name базового класса будет игнорироваться.

Чтобы полностью сериализовать экземпляры «Ресторан», вам также необходимо сериализовать модели «Место»:

all_objects = [*Restaurant.objects.all(), *Place.objects.all()]
data = serializers.serialize('xml', all_objects)

XML¶

The basic XML serialization format looks like this:

<?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>

Вся коллекция объектов, которые либо сериализованы, либо десериализованы, представлена ​​тегом <django-objects>, который содержит несколько элементов <object>. Каждый такой объект имеет два атрибута: «pk» и «model», причем последний представлен именем приложения («сеансы») и строчным именем модели («сеанс»), разделенными точкой.

Каждое поле объекта сериализуется как элемент <field>, имеющий поля «тип» и «имя». Текстовое содержимое элемента представляет значение, которое должно быть сохранено.

Foreign keys and other relational fields are treated a little bit differently:

<object pk="27" model="auth.permission">
    <!-- ... -->
    <field to="contenttypes.contenttype" name="content_type" rel="ManyToOneRel">9</field>
    <!-- ... -->
</object>

В этом примере мы указываем, что объект auth.Permission с PK 27 имеет внешний ключ для экземпляра contenttypes.ContentType с PK 9.

ManyToMany-relations are exported for the model that binds them. For instance, the auth.User model has such a relation to the auth.Permission model:

<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>

Этот пример связывает данного пользователя с моделями разрешений с ПК 46 и 47.

JSON¶

При использовании тех же данных примера, что и раньше, они будут сериализованы как JSON следующим образом:

[
    {
        "pk": "4b678b301dfd8a4e0dad910de3ae245b",
        "model": "sessions.session",
        "fields": {
            "expire_date": "2013-01-16T08:16:59.844Z",
            ...
        }
    }
]

Форматирование здесь немного проще, чем в XML. Вся коллекция просто представлена ​​в виде массива, а объекты представлены объектами JSON с тремя свойствами: «pk», «модель» и «поля». «Поля» снова являются объектом, содержащим имя и значение каждого поля в качестве свойства и значения свойства соответственно.

Внешние ключи имеют PK связанного объекта в качестве значения свойства. Отношения ManyToMany сериализуются для модели, которая их определяет, и представляются в виде списка ПК.

Имейте в виду, что не весь вывод Django может быть передан в неизмененном виде в json. Например, если у вас есть какой-то собственный тип в сериализуемом объекте, вам придется написать для него собственный кодировщик json. Что-то вроде этого будет работать:

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)

Затем вы можете передать cls=LazyEncoder в функциюserializers.serialize():

from django.core.serializers import serialize

serialize('json', SomeModel.objects.all(), cls=LazyEncoder)

Также обратите внимание, что GeoDjango предоставляет настраиваемый сериализатор GeoJSON.

ЯМЛ¶

YAML serialization looks quite similar to JSON. The object list is serialized as a sequence mappings with the keys «pk», «model» and «fields». Each field is again a mapping with the key being name of the field and the value the value:

-   fields: {expire_date: !!timestamp '2013-01-16 08:16:59.844560+00:00'}
    model: sessions.session
    pk: 4b678b301dfd8a4e0dad910de3ae245b

Ссылочные поля снова представлены ПК или последовательностью ПК.

Десериализация естественных ключей¶

Рассмотрим следующие две модели:

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)

Обычно сериализованные данные для Book используют целое число для ссылки на автора. Например, в формате JSON книга может быть сериализована как:

...
{
    "pk": 1,
    "model": "store.book",
    "fields": {
        "name": "Mostly Harmless",
        "author": 42
    }
}
...

Это не совсем естественный способ обращения к автору. Для этого требуется, чтобы вы знали значение первичного ключа автора; также требуется, чтобы значение первичного ключа было стабильным и предсказуемым.

Однако если мы добавим в Person естественную обработку ключей, приспособление станет гораздо более гуманным. Чтобы добавить обработку естественных ключей, вы определяете менеджера по умолчанию для Person с помощью метода get_by_natural_key(). В случае с Person хорошим естественным ключом может быть пара имени и фамилии:

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']]

Теперь книги могут использовать этот естественный ключ для ссылки на объекты Person:

...
{
    "pk": 1,
    "model": "store.book",
    "fields": {
        "name": "Mostly Harmless",
        "author": ["Douglas", "Adams"]
    }
}
...

Когда вы попытаетесь загрузить эти сериализованные данные, Django будет использовать метод get_by_natural_key() для разрешения ["Douglas", "Adams"] в первичный ключ фактического объекта Person.

Десериализация объектов без первичного ключа всегда будет проверять, есть ли у менеджера модели метод get_by_natural_key(), и если да, то использовать его для заполнения первичного ключа десериализованного объекта.

Сериализация естественных ключей¶

Так как же заставить Django выдавать естественный ключ при сериализации объекта? Во-первых, вам нужно добавить еще один метод — на этот раз к самой модели:

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)

That method should always return a natural key tuple – in this example, (first name, last name). Then, when you call serializers.serialize(), you provide use_natural_foreign_keys=True or use_natural_primary_keys=True arguments:

>>> serializers.serialize('json', [book1, book2], indent=2,
...      use_natural_foreign_keys=True, use_natural_primary_keys=True)

Когда указано use_natural_foreign_keys=True, Django будет использовать метод natural_key() для сериализации любой ссылки на внешний ключ к объектам типа, который определяет этот метод.

Если указано use_natural_primary_keys=True, Django не будет предоставлять первичный ключ в сериализованных данных этого объекта, поскольку он может быть вычислен во время десериализации:

...
{
    "model": "store.person",
    "fields": {
        "first_name": "Douglas",
        "last_name": "Adams",
        "birth_date": "1952-03-11",
    }
}
...

Это может быть полезно, когда вам нужно загрузить сериализованные данные в существующую базу данных, и вы не можете гарантировать, что значение сериализованного первичного ключа еще не используется, и вам не нужно гарантировать, что десериализованные объекты сохраняют одни и те же первичные ключи.

Если вы используете dumpdata для генерации сериализованных данных, используйте флаги командной строки dumpdata --natural-foreign и dumpdata --natural-primary для генерации естественных ключей.

Естественные ключи и прямые ссылки¶

Иногда, когда вы используете естественные внешние ключи, вам необходимо десериализовать данные, где объект имеет внешний ключ, ссылающийся на другой объект, который еще не был десериализован. Это называется «прямой ссылкой».

Например, предположим, что в вашем приборе есть следующие объекты:

...
{
    "model": "store.book",
    "fields": {
        "name": "Mostly Harmless",
        "author": ["Douglas", "Adams"]
    }
},
...
{
    "model": "store.person",
    "fields": {
        "first_name": "Douglas",
        "last_name": "Adams"
    }
},
...

Чтобы справиться с этой ситуацией, вам необходимо передать handle_forward_references=True в serializers.deserialize(). Это установит атрибут deferred_fields для экземпляров DeserializedObject. Вам нужно будет отслеживать экземпляры DeserializedObject, где этот атрибут не имеет значения None, а затем вызывать для них save_deferred_fields().

Типичное использование выглядит так:

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()

Чтобы это работало, параметр ForeignKey ссылочной модели должен иметь значение null=True.

Зависимости во время сериализации¶

Часто можно избежать явной обработки прямых ссылок, позаботившись об упорядочивании объектов внутри фикстуры.

Чтобы помочь в этом, вызовы dumpdata, использующие опцию dumpdata --natural-foreign, будут сериализовать любую модель с помощью метода natural_key() перед сериализацией стандартных объектов первичного ключа.

Однако этого не всегда может быть достаточно. Если ваш естественный ключ ссылается на другой объект (путем использования внешнего ключа или естественного ключа к другому объекту как части естественного ключа), то вам необходимо иметь возможность гарантировать, что объекты, от которых зависит естественный ключ, встречаются в сериализованных данных до того, как естественный ключ потребует их.

Чтобы контролировать этот порядок, вы можете определить зависимости от ваших методов natural_key(). Вы делаете это, устанавливая атрибут «зависимости» в самом методе «natural_key()».

Например, давайте добавим естественный ключ к модели «Книга» из примера выше:

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()

Естественный ключ к «Книге» — это комбинация ее имени и автора. Это означает, что Person должен быть сериализован до Book. Чтобы определить эту зависимость, мы добавляем одну дополнительную строку:

def natural_key(self):
    return (self.name,) + self.author.natural_key()
natural_key.dependencies = ['example_app.person']

Это определение гарантирует, что все объекты Person сериализуются раньше любых объектов Book. В свою очередь, любой объект, ссылающийся на «Книгу», будет сериализован после сериализации «Человека» и «Книги».