Как создавать пользовательские поля модели

Объект для примера

Создание пользовательских полей требует внимания к деталям. Чтобы упростить изложение, на протяжении всего документа мы будем использовать один и тот же пример: класс-обёртку для объекта Python, представляющего раздачу карт в бридже. Не беспокойтесь: чтобы понять этот пример, не нужно уметь играть в бридж. Достаточно знать, что 52 карты поровну раздаются четырём игрокам, которых традиционно называют север, восток, юг и запад. Наш класс выглядит примерно так:

class Hand:
    """A hand of cards (bridge style)"""

    def __init__(self, north, east, south, west):
        # Input parameters are lists of cards ('Ah', '9s', etc.)
        self.north = north
        self.east = east
        self.south = south
        self.west = west

    # ... (other possibly useful methods omitted) ...

Это обычный класс Python, не связанный с Django. Мы хотим иметь возможность делать в моделях примерно следующее (предполагается, что атрибут hand модели является экземпляром Hand):

example = MyModel.objects.get(pk=1)
print(example.hand.north)

new_hand = Hand(north, east, south, west)
example.hand = new_hand
example.save()

Мы присваиваем значения атрибуту hand модели и получаем их из него так же, как у любого другого класса Python. Нужно лишь указать Django, как сохранять и загружать такой объект.

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

Хранение в базе данных

Начнём с полей модели. Если разобрать задачу на части, поле модели позволяет преобразовать обычный объект Python — строку, логическое значение, datetime или что-то более сложное, например Hand, — в формат, удобный для работы с базой данных, и обратно. (Такой формат также удобен для сериализации, но, как мы увидим далее, с ней проще работать, когда вы уже разобрались с взаимодействием с базой данных.)

Поля модели необходимо каким-либо образом преобразовать, чтобы они поместились в существующий тип столбца базы данных. В разных базах данных доступны разные наборы допустимых типов столбцов, но правило остаётся неизменным: работать можно только с этими типами. Всё, что вы хотите сохранить в базе данных, должно соответствовать одному из них.

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

В нашем примере с Hand данные карт можно преобразовать в строку из 104 символов, объединив все карты в заранее определённом порядке — например, сначала все карты севера, затем востока, юга и запада. Таким образом, объекты Hand можно сохранять в текстовые или символьные столбцы базы данных.

Что делает класс поля?

Все поля Django (и когда в этом документе мы говорим о полях, мы всегда имеем в виду поля моделей, а не поля форм) являются подклассами django.db.models.Field. Большая часть информации, которую Django хранит о поле, общая для всех полей: имя, справочный текст, уникальность и так далее. За хранение всей этой информации отвечает Field. Позже мы подробно рассмотрим возможности Field; пока достаточно сказать, что все поля наследуются от Field, а затем настраивают ключевые аспекты поведения класса.

Важно понимать, что класс поля Django — это не то, что хранится в атрибутах модели. Атрибуты модели содержат обычные объекты Python. Классы полей, определённые в модели, фактически хранятся в классе Meta при создании класса модели (точные подробности этого процесса здесь не важны). Это связано с тем, что классы полей не нужны для простого создания и изменения атрибутов. Вместо этого они предоставляют механизм преобразования значения атрибута в значение, хранящееся в базе данных или передаваемое сериализатору, и обратно.

Помните об этом, создавая собственные пользовательские поля. Создаваемый вами подкласс Django Field предоставляет механизм преобразования экземпляров Python в значения базы данных или сериализатора и обратно разными способами (например, сохранение значения и использование значения для поиска — это разные операции). Если это кажется сложным, не беспокойтесь: в примерах ниже всё станет понятнее. Просто помните, что для создания пользовательского поля вам часто понадобится два класса:

• Первый класс — это объект Python, с которым будут работать пользователи. Они будут присваивать его атрибуту модели, считывать его для отображения и выполнять подобные действия. В нашем примере это класс Hand.
• Второй класс — это подкласс Field. Он умеет преобразовывать экземпляры первого класса из формы постоянного хранения в форму Python и обратно.

Декомпозиция поля

Созданию метода __init__() соответствует создание метода deconstruct(). Он используется при миграциях моделей, чтобы сообщить Django, как преобразовать экземпляр нового поля в сериализованную форму — в частности, какие аргументы передать в __init__(), чтобы восстановить его.

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

deconstruct() возвращает кортеж из четырёх элементов: имя атрибута поля, полный путь импорта класса поля, позиционные аргументы (в виде списка) и именованные аргументы (в виде словаря). Обратите внимание: это отличается от метода deconstruct() для пользовательских классов, который возвращает кортеж из трёх элементов.

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

Например, в нашем классе HandField мы всегда принудительно задаём max_length в __init__(). Метод deconstruct() базового класса Field заметит это и попытается вернуть значение в именованных аргументах; поэтому мы можем убрать его из именованных аргументов для большей наглядности:

from django.db import models


class HandField(models.Field):
    def __init__(self, *args, **kwargs):
        kwargs["max_length"] = 104
        super().__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super().deconstruct()
        del kwargs["max_length"]
        return name, path, args, kwargs

Если вы добавите новый именованный аргумент, необходимо написать код в deconstruct(), который самостоятельно поместит его значение в kwargs. Также следует опускать значение из kwargs, если оно не требуется для восстановления состояния поля, например когда используется значение по умолчанию:

from django.db import models


class CommaSepField(models.Field):
    "Implements comma-separated storage of lists"

    def __init__(self, separator=",", *args, **kwargs):
        self.separator = separator
        super().__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super().deconstruct()
        # Only include kwarg if it's not the default
        if self.separator != ",":
            kwargs["separator"] = self.separator
        return name, path, args, kwargs

Более сложные примеры выходят за рамки этого документа, но помните: для любой конфигурации экземпляра Field метод deconstruct() должен возвращать аргументы, которые можно передать в __init__, чтобы восстановить это состояние.

Будьте особенно внимательны, если задаёте новые значения по умолчанию для аргументов суперкласса Field: убедитесь, что они всегда включаются в результат, а не исчезают при совпадении со старым значением по умолчанию.

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

Результаты декомпозиции можно увидеть в миграциях, использующих это поле. Проверить декомпозицию можно в модульных тестах, декомпозировав поле и восстановив его:

name, path, args, kwargs = my_field_instance.deconstruct()
new_instance = MyField(*args, **kwargs)
self.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)

Атрибуты поля, не влияющие на определение столбца базы данных

Можно переопределить Field.non_db_attrs, чтобы настроить атрибуты поля, не влияющие на определение столбца. Этот метод используется при миграциях моделей для обнаружения операций AlterField, не вносящих изменений.

Например:

class CommaSepField(models.Field):
    @property
    def non_db_attrs(self):
        return super().non_db_attrs + ("separator",)

Изменение базового класса пользовательского поля

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

class CustomCharField(models.CharField): ...

а затем решили использовать TextField, изменить подкласс следующим образом нельзя:

class CustomCharField(models.TextField): ...

Вместо этого необходимо создать новый класс пользовательского поля и обновить модели, чтобы они ссылались на него:

class CustomCharField(models.CharField): ...


class CustomTextField(models.TextField): ...

Как сказано в разделе удаление полей, исходный класс CustomCharField необходимо сохранять, пока существуют миграции, в которых на него есть ссылки.

Документирование пользовательского поля

Как и всегда, следует документировать тип поля, чтобы пользователи понимали, что это такое. Помимо строки документации, полезной разработчикам, можно также позволить пользователям приложения администрирования видеть краткое описание типа поля с помощью приложения django.contrib.admindocs. Для этого укажите описательный текст в атрибуте класса description пользовательского поля. В приведённом выше примере приложение admindocs покажет для поля HandField описание «Рука карт (в стиле бриджа)».

В представлении django.contrib.admindocs описание поля форматируется с помощью field.__dict__, что позволяет включать в него аргументы поля. Например, описание для CharField выглядит так:

description = _("String (up to %(max_length)s)")

Полезные методы

Создав подкласс Field, вы можете переопределить несколько стандартных методов в зависимости от поведения поля. Методы ниже перечислены примерно в порядке убывания важности, поэтому начните с верхних.

from django.db import models


class MytypeField(models.Field):
    def db_type(self, connection):
        return "mytype"

class Person(models.Model):
    name = models.CharField(max_length=80)
    something_else = MytypeField()

class MyDateField(models.Field):
    def db_type(self, connection):
        if connection.vendor == "mysql":
            return "datetime"
        else:
            return "timestamp"

# This is a silly example of hardcoded parameters.
class CharMaxlength25Field(models.Field):
    def db_type(self, connection):
        return "char(25)"


# In the model:
class MyModel(models.Model):
    # ...
    my_field = CharMaxlength25Field()

# This is a much more flexible example.
class BetterCharField(models.Field):
    def __init__(self, max_length, *args, **kwargs):
        self.max_length = max_length
        super().__init__(*args, **kwargs)

    def db_type(self, connection):
        return "char(%s)" % self.max_length


# In the model:
class MyModel(models.Model):
    # ...
    my_field = BetterCharField(25)

# MySQL unsigned integer (range 0 to 4294967295).
class UnsignedAutoField(models.AutoField):
    def db_type(self, connection):
        return "integer UNSIGNED AUTO_INCREMENT"

    def rel_db_type(self, connection):
        return "integer UNSIGNED"

import re

from django.core.exceptions import ValidationError
from django.db import models
from django.utils.translation import gettext_lazy as _


def parse_hand(hand_string):
    """Takes a string of cards and splits into a full hand."""
    p1 = re.compile(".{26}")
    p2 = re.compile("..")
    args = [p2.findall(x) for x in p1.findall(hand_string)]
    if len(args) != 4:
        raise ValidationError(_("Invalid input for a Hand instance"))
    return Hand(*args)


class HandField(models.Field):
    # ...

    def from_db_value(self, value, expression, connection):
        if value is None:
            return value
        return parse_hand(value)

    def to_python(self, value):
        if isinstance(value, Hand):
            return value

        if value is None:
            return value

        return parse_hand(value)

class HandField(models.Field):
    # ...

    def get_prep_value(self, value):
        return "".join(
            ["".join(l) for l in (value.north, value.east, value.south, value.west)]
        )

def get_db_prep_value(self, value, connection, prepared=False):
    value = super().get_db_prep_value(value, connection, prepared)
    if value is not None:
        return connection.Database.Binary(value)
    return value

class HandField(models.Field):
    # ...

    def formfield(self, **kwargs):
        # Exclude the field from the ModelForm when some condition is met.
        some_condition = kwargs.get("some_condition", False)
        if some_condition:
            return None

        # Set up some defaults while letting the caller override them.
        defaults = {"form_class": MyFormField}
        defaults.update(kwargs)
        return super().formfield(**defaults)

class HandField(models.Field):
    # ...

    def get_internal_type(self):
        return "CharField"

class HandField(models.Field):
    # ...

    def value_to_string(self, obj):
        value = self.value_from_object(obj)
        return self.get_prep_value(value)

Общие рекомендации

Создание пользовательского поля может быть непростой задачей, особенно если требуется сложное преобразование между типами Python и форматами базы данных и сериализации. Вот несколько советов, которые помогут упростить процесс:

1. Изучите существующие поля Django (в django/db/models/fields/__init__.py) для вдохновения. Попробуйте найти похожее на нужное вам поле и немного расширить его, вместо того чтобы создавать совершенно новое поле с нуля.
2. Добавьте метод __str__() в класс, который вы оборачиваете в поле. Во многих случаях код поля по умолчанию вызывает для значения str(). (В наших примерах value был бы экземпляром Hand, а не HandField.) Поэтому, если ваш метод __str__() автоматически преобразует объект Python в строковое представление, это может избавить вас от множества лишней работы.

Несколько советов

Помимо описанных выше деталей, есть несколько рекомендаций, которые могут значительно повысить эффективность и читаемость кода поля.

1. Исходный код собственного класса ImageField Django (в файле django/db/models/fields/files.py) — отличный пример того, как создать подкласс FileField для поддержки определённого типа файла: в нём применены все описанные выше методы.
2. По возможности кэшируйте атрибуты файла. Поскольку файлы могут храниться в удалённых системах хранения, их извлечение может требовать дополнительного времени и даже денег, хотя это не всегда необходимо. Получив файл, чтобы узнать какие-либо данные о его содержимом, кэшируйте как можно больше этих данных, чтобы сократить число повторных извлечений файла при последующих запросах этой информации.