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

Фреймворк сериализации Django предоставляет механизм для «перевода» моделей Django в другие форматы. Обычно эти другие форматы будут текстовыми и используются для отправки данных Django по сети, но сериализатор может обрабатывать любой формат (текстовый или нет).

Сериализация данных

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

from django.core import serializers

data = serializers.serialize("xml", SomeModel.objects.all())

Аргументы функции serialize — это формат, в который следует сериализовать данные (см. Форматы сериализации), и QuerySet для сериализации. (На самом деле, второй аргумент может быть любым итератором, который возвращает экземпляры моделей Django, но это почти всегда будет QuerySet).

django.core.serializers.get_serializer(format)

Вы также можете использовать объект сериализатора напрямую:

XMLSerializer = serializers.get_serializer("xml")
xml_serializer = XMLSerializer()
xml_serializer.serialize(queryset)
data = xml_serializer.getvalue()

Это полезно, если вы хотите сериализовать данные непосредственно в объект, похожий на файл (включая HttpResponse):

with open("file.xml", "w") as out:
    xml_serializer.serialize(SomeModel.objects.all(), stream=out)

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

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

from django.core import serializers

data = serializers.serialize("xml", SomeModel.objects.all(), fields=["name", "size"])

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

Наследованные модели

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

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

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)

Десериализация данных

Десериализация данных очень похожа на сериализацию:

for obj in serializers.deserialize("xml", data):
    do_something_with(obj)

Как вы можете видеть, функция deserialize принимает тот же аргумент формата, что и serialize, строку или поток данных и возвращает итератор.

Однако здесь становится немного сложнее. Объекты, возвращаемые итератором deserialize, не являются обычными объектами Django. Вместо этого они являются специальными экземплярами DeserializedObject, которые оборачивают созданный, но не сохраненный объект и связанные с ним данные о взаимосвязях.

Вызов DeserializedObject.save() сохраняет объект в базе данных.

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

for deserialized_object in serializers.deserialize("xml", data):
    if object_should_be_saved(deserialized_object):
        deserialized_object.save()

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

Сам объект Django можно проверить как deserialized_object.object. Если поля в сериализованных данных отсутствуют в модели, будет поднято исключение DeserializationError, если аргумент ignorenonexistent не передан как True:

serializers.deserialize("xml", data, ignorenonexistent=True)

Форматы сериализации

Django поддерживает ряд форматов сериализации, некоторые из которых требуют установки сторонних модулей Python:

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>, содержащий атрибуты «type» и «name». Текстовое содержимое элемента представляет собой значение, которое должно быть сохранено.

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

<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». «fields» снова является объектом, содержащим имя и значение каждого поля в качестве свойства и значения свойства соответственно.

Внешние ключи имеют PK связанного объекта в качестве значения свойства. Многозначные связи сериализуются для модели, которая их определяет, и представляются в виде списка 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 предоставляет настраиваемый GeoJSON-сериализатор.

DjangoJSONEncoder

class django.core.serializers.json.DjangoJSONEncoder

JSON-сериализатор использует DjangoJSONEncoder для кодирования. Подкласс JSONEncoder, он обрабатывает эти дополнительные типы:

datetime

Строка формата YYYY-MM-DDTHH:mm:ss.sssZ или YYYY-MM-DDTHH:mm:ss.sss+HH:MM, определённого в ECMA-262.

date

Строка формата YYYY-MM-DD, определённого в ECMA-262.

time

Строка формата HH: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

Строковое представление объекта.

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”. Каждый field снова является словарем с ключом, являющимся именем поля, а значением — значением поля:

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

Ссылочные поля снова представлены первичным ключом или последовательностью первичных ключей.

Естественные ключи

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

Рассмотрим случай списка объектов, имеющих внешний ключ, ссылающийся на ContentType. Если вы собираетесь сериализовать объект, ссылающийся на тип содержимого, то вам нужен способ сослаться на этот тип содержимого в первую очередь. Поскольку объекты ContentType автоматически создаются Django во время синхронизации базы данных, первичный ключ данного типа содержимого трудно предсказать; он будет зависеть от того, как и когда выполнялась команда migrate. Это верно для всех моделей, которые автоматически генерируют объекты, в том числе Permission, Group и User.

Также есть вопрос удобства. Целочисленный идентификатор не всегда является наиболее удобным способом ссылки на объект; иногда более естественная ссылка была бы полезна.

По этим причинам Django предоставляет естественные ключи. Естественный ключ — это кортеж значений, которые могут использоваться для уникальной идентификации экземпляра объекта без использования значения первичного ключа.

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

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

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:
        constraints = [
            models.UniqueConstraint(
                fields=["first_name", "last_name"],
                name="unique_first_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:
        constraints = [
            models.UniqueConstraint(
                fields=["first_name", "last_name"],
                name="unique_first_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:
        constraints = [
            models.UniqueConstraint(
                fields=["first_name", "last_name"],
                name="unique_first_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 для генерации естественных ключей.

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

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

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

...
{
    "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 были сериализованы.