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

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

Создание пользовательских полей требует некоторого внимания к деталям. Чтобы было проще разобраться, мы будем использовать последовательный пример в этом документе: обернуть объект 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 (и когда мы говорим поля в этом документе, мы всегда имеем в виду поля модели, а не form fields) являются подклассами django.db.models.Field. Большая часть информации, которую Django записывает о поле, является общей для всех полей - имя, текст справки, уникальность и так далее. Хранением всей этой информации занимается Field. Позже мы подробнее рассмотрим, что может делать Field; сейчас достаточно сказать, что все происходит от Field и затем настраивает ключевые части поведения класса.

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

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

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

Деконструкция поля¶

Противоположностью написания метода __init__() является написание метода deconstruct(). Он используется во время model migrations, чтобы указать Django, как взять экземпляр вашего нового поля и уменьшить его до сериализованной формы - в частности, какие аргументы передать в __init__(), чтобы воссоздать его.

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

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

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

Как обсуждалось в removing fields, вы должны сохранять исходный класс 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):
        # This is a fairly standard way to 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/db/models/fields/files.py) Django является отличным примером того, как можно подклассифицировать FileField для поддержки определенного типа файлов, поскольку в нем реализованы все описанные выше приемы.
2. По возможности кэшируйте атрибуты файлов. Поскольку файлы могут храниться в удаленных системах хранения, их извлечение может потребовать дополнительного времени или даже денег, которые не всегда необходимы. После извлечения файла для получения некоторых данных о его содержимом, кэшируйте как можно больше этих данных, чтобы уменьшить количество последующих обращений к файлу за этой информацией.