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

Наш пример объекта

Создание пользовательских полей требует некоторого внимания к деталям. Чтобы упростить понимание, мы будем использовать один и тот же пример на протяжении всего этого документа: обертывание объекта 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 при создании класса модели (точные детали того, как это делается, здесь не важны). Это потому, что классы полей не нужны, когда вы просто создаете и изменяете атрибуты. Вместо этого они предоставляют механизм для преобразования значения атрибута и того, что хранится в базе данных или отправляется в сериализатор.

Помните об этом при создании собственных пользовательских полей. Подкласс Field Django, который вы пишете, предоставляет механизм для преобразования ваших экземпляров 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

Более сложные примеры выходят за рамки этого документа, но помните - для любой конфигурации вашего экземпляра поля, 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 до тех пор, пока у вас есть миграции, которые на него ссылаются.

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

Как всегда, вы должны задокументировать свой тип поля, чтобы пользователи знали, что это такое. В дополнение к предоставлению для него docstring, который полезен для разработчиков, вы также можете позволить пользователям приложения администрирования видеть краткое описание типа поля через приложение 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 hard-coded 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)

Некоторые общие советы

Написание пользовательского поля может быть сложным процессом, особенно если вы выполняете сложные преобразования между вашими типами 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. Кэшируйте атрибуты файлов везде, где это возможно. Поскольку файлы могут храниться в удаленных системах хранения, их извлечение может занимать дополнительное время или даже деньги, которые не всегда необходимы. После извлечения файла для получения некоторых данных о его содержимом кэшируйте как можно больше этих данных, чтобы уменьшить количество обращений к файлу при последующих вызовах этой информации.