Сериализация объектов Django¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

XML¶

Основной формат сериализации XML выглядит следующим образом:

<?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», причем последний представлен именем приложения («sessions») и строчным именем модели («session»), разделенными точкой.

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

Внешние ключи и другие реляционные поля обрабатываются немного по-другому:

<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 экспортируются для модели, которая их связывает. Например, модель auth.User имеет такое отношение к модели 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>

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

JSON¶

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

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

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

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

Имейте в виду, что не все выходные данные 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 предоставляет customized GeoJSON serializer.

JSONL¶

JSONL расшифровывается как JSON Lines. В этом формате объекты разделяются новыми строками, и каждая строка содержит правильный объект JSON. Сериализованные данные JSONL выглядят следующим образом:

{"pk": "4b678b301dfd8a4e0dad910de3ae245b", "model": "sessions.session", "fields": {...}}
{"pk": "88bea72c02274f3c9bf1cb2bb8cee4fc", "model": "sessions.session", "fields": {...}}
{"pk": "9cf0e26691b64147a67e2a9f06ad7a53", "model": "sessions.session", "fields": {...}}

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

YAML¶

Сериализация YAML выглядит довольно похоже на JSON. Список объектов сериализуется как последовательность отображений с ключами «pk», «model» и «fields». Каждое поле - это снова отображение, ключ которого является именем поля, а значение - значением:

- model: sessions.session
  pk: 4b678b301dfd8a4e0dad910de3ae245b
  fields:
    expire_date: 2013-01-16 08:16:59.844560+00:00

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

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

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

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)

Этот метод всегда должен возвращать кортеж натуральных ключей - в данном примере (first name, last name). Затем, когда вы вызываете serializers.serialize(), вы предоставляете use_natural_foreign_keys=True или use_natural_primary_keys=True аргументы:

>>> 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 для генерации натуральных ключей.

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

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

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

...
{
    "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(). Для этого нужно установить атрибут dependencies на самом методе natural_key().

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

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

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

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

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