Поля сериализатора

Поля сериализатора

Каждое поле в классе Form отвечает не только за проверку данных, но и за их «очистку» - приведение к согласованному формату.

Django documentation

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

Примечание: Поля сериализатора объявлены в fields.py, но по соглашению вы должны импортировать их с помощью from rest_framework import serializers и ссылаться на поля как serializers.<FieldName>.

Основные аргументы

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

read_only

Поля только для чтения включаются в выходные данные API, но не должны включаться во входные данные во время операций создания или обновления. Любые поля read_only, которые неправильно включены во ввод сериализатора, будут проигнорированы.

Установите значение True, чтобы поле использовалось при сериализации представления, но не использовалось при создании или обновлении экземпляра во время десериализации.

По умолчанию False

write_only

Установите значение True, чтобы гарантировать, что поле может использоваться при обновлении или создании экземпляра, но не будет включено при сериализации представления.

По умолчанию False

required

Обычно возникает ошибка, если поле не указано во время десериализации. Установите значение False, если это поле не требуется во время десериализации.

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

По умолчанию True.

default

Если установлено, это дает значение по умолчанию, которое будет использоваться для поля, если входное значение не предоставлено. Если не задано, по умолчанию атрибут не заполняется.

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

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

Например:

class CurrentUserDefault:
"""
May be applied as a `default=...` value on a serializer field.
Returns the current user.
"""
requires_context = True
def __call__(self, serializer_field):
return serializer_field.context['request'].user

При сериализации экземпляра будет использоваться значение по умолчанию, если атрибут объекта или ключ словаря отсутствуют в экземпляре.

Обратите внимание, что установка default подразумевает, что это поле не является обязательным. Включение аргументов ключевого слова default и required недопустимо и вызовет ошибку.

allow_null

Обычно возникает ошибка, если в поле сериализатора передается None. Установите для этого аргумента ключевого слова значение True, если значение None следует считать допустимым.

Обратите внимание, что без явного default установка этого аргумента в True будет подразумевать значение default равное null для вывода сериализации, но не подразумевает значение по умолчанию для десериализации ввода.

По умолчанию False

source

Имя атрибута, который будет использоваться для заполнения поля. Может быть методом, который принимает только аргумент self, например URLField (source='get_absolute_url'), или может использовать точечную нотацию для обхода атрибутов, например EmailField(source='user.email'). При сериализации полей с точечной нотацией может потребоваться предоставить значение по умолчанию, если какой-либо объект отсутствует или пуст во время обхода атрибута.

Значение source='*' имеет особое значение и используется для обозначения того, что весь объект должен быть передан в поле. Это может быть полезно для создания вложенных представлений или для полей, которым требуется доступ ко всему объекту для определения выходного представления.

По умолчанию используется имя поля.

validators

Список функций валидатора, которые должны применяться к входящему полю ввода и которые либо вызывают ошибку валидации, либо просто возвращают. Функции валидатора обычно должны вызывать serializers.ValidationError, но встроенный Django ValidationError также поддерживается для совместимости с валидаторами, определенными в кодовой базе Django или сторонних пакетах Django.

error_messages

Словарь кодов ошибок к сообщениям об ошибках.

label

Короткая текстовая строка, которая может использоваться как имя поля в полях HTML-формы или других описательных элементах.

help_text

Текстовая строка, которая может использоваться как описание поля в полях HTML-формы или других описательных элементах.

initial

Значение, которое следует использовать для предварительного заполнения значений полей HTML-формы. Вы можете передать ему вызываемый объект, как и любой обычный Django Field:

import datetime
from rest_framework import serializers
class ExampleSerializer(serializers.Serializer):
day = serializers.DateField(initial=datetime.date.today)

style

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

Вот два примера: 'input_type' и 'base_template':

# Use <input type="password"> for the input.
password = serializers.CharField(
style={'input_type': 'password'}
)
# Use a radio input instead of a select input.
color_channel = serializers.ChoiceField(
choices=['red', 'green', 'blue'],
style={'base_template': 'radio.html'}
)

Дополнительные сведения см. В документации HTML и формы.

Логические поля

BooleanField

Логическое представление.

При использовании ввода формы в кодировке HTML имейте в виду, что пропуск значения всегда будет рассматриваться как установка поля на False, даже если для него указана опция default=True. Это связано с тем, что входы флажков HTML представляют непроверенное состояние, опуская значение, поэтому структура REST рассматривает пропуск, как если бы это был пустой ввод флажка.

Обратите внимание, что Django 2.1 удалил пустой kwarg из models.BooleanField. До Django 2.1 поля models.BooleanField всегда были blank=True. Таким образом, поскольку в Django 2.1 по умолчанию экземпляры serializers.BooleanField будут сгенерированы без именного аргумента required (т.е. эквивалентно required=True), тогда как в предыдущих версиях Django экземпляры BooleanField по умолчанию будут сгенерированы с required=False. Если вы хотите управлять этим поведением вручную, явно объявите BooleanField в классе сериализатора или используйте параметр extra_kwargs, чтобы установить флаг required.

Соответствует django.db.models.fields.BooleanField.

Сигнатура: BooleanField ()

NullBooleanField

Булево представление, которое также принимает None как допустимое значение.

Соответствует django.db.models.fields.NullBooleanField.

Сигнатура: NullBooleanField ()

Строковые поля

CharField

Текстовое представление. Необязательно проверяет, чтобы текст был короче, чем max_length, и длиннее, чем min_length.

Соответствует django.db.models.fields.CharField или django.db.models.fields.TextField.

Сигнатура: CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)

  • max_length - Проверяет, что ввод содержит не более указанного количества символов.

  • min_length - Проверяет, что ввод содержит не меньше, чем это количество символов.

  • allow_blank - Если установлено значение True, пустая строка должна считаться допустимым значением. Если установлено значение False, то пустая строка считается недопустимой и вызовет ошибку проверки. По умолчанию False.

  • trim_whitespace - Если установлено значение True, то начальные и конечные пробелы обрезаются. По умолчанию True.

Параметр allow_null также доступен для строковых полей, хотя его использование не рекомендуется в пользу allow_blank. Допустимо установить как allow_blank=True, так и allow_null=True, но это означает, что будут два разных типа пустых значений, допустимых для строковых представлений, что может привести к несогласованности данных и незаметным ошибкам приложения.

EmailField

Текстовое представление подтверждает, что текст является действительным адресом электронной почты.

Соответствует django.db.models.fields.EmailField

Сигнатура: EmailField (max_length = None, min_length = None, allow_blank = False)

RegexField

Текстовое представление, которое проверяет соответствие данного значения определенному регулярному выражению.

Соответствует django.forms.fields.RegexField.

Сигнатура: RegexField(regex, max_length=None, min_length=None, allow_blank=False)

Обязательный аргумент regex может быть строкой или скомпилированным объектом регулярного выражения Python.

Использует класс Django django.core.validators.RegexValidator для валидации.

SlugField

RegexField, который проверяет ввод по шаблону [a-zA-Z0-9_-]+.

Соответствует django.db.models.fields.SlugField.

Сигнатура: SlugField(max_length=50, min_length=None, allow_blank=False)

URLField

RegexField, который проверяет ввод на соответствие шаблону URL. Ожидает полностью квалифицированных URL-адресов в виде http://<host>/<path>.

Соответствует django.db.models.fields.URLField.

Использует класс Django django.core.validators.URLValidator для валидации.

Сигнатура: URLField(max_length=200, min_length=None, allow_blank=False)

UUIDField

Поле, которое гарантирует, что ввод является допустимой строкой UUID. Метод to_internal_value вернет экземпляр uuid.UUID. На выходе поле вернет строку в каноническом формате с дефисами, например:

"de305d54-75b4-431b-adb2-eb6b9e546013"

Сигнатура: UUIDField(format='hex_verbose')

  • format: определяет формат представления значения uuid

    • 'hex_verbose' - каноническое шестнадцатеричное представление, включая дефисы: "5ce0e9a5-5ffa-654b-cee0-1238041fb31a"

    • 'hex' - компактное шестнадцатеричное представление UUID без дефисов: "5ce0e9a55ffa654bcee01238041fb31a"

    • 'int' - 128-битное целочисленное представление UUID: "123456789012312313134124512351145145114"

    • 'urn' - RFC 4122 представление URN UUID: " urn: uuid: 5ce0e9a5-5ffa-654b-cee0-1238041fb31a "

      Изменение параметров format влияет только на значения представления. Все форматы принимаются to_internal_value

FilePathField

Поле, выбор которого ограничен именами файлов в определенном каталоге файловой системы.

Соответствует django.forms.fields.FilePathField.

Сигнатура: FilePathField(path, match=None, recursive=False, allow_files=True, allow_folders=False, required=None, **kwargs)

  • path - Абсолютный путь файловой системы к каталогу, из которого этот FilePathField должен получить свой выбор.

  • match - Регулярное выражение в виде строки, которое FilePathField будет использовать для фильтрации имен файлов.

  • recursive- указывает, должны ли быть включены все подкаталоги пути. По умолчанию - False.

  • allow_files - указывает, должны ли быть включены файлы в указанном месте. По умолчанию - True. Либо это, либо allow_folders должно иметь значение True.

  • allow_folders - указывает, должны ли быть включены папки в указанном месте. По умолчанию - False. Либо это, либо allow_files должно иметь значение True.

IPAddressField

Поле, которое гарантирует, что ввод является допустимой строкой IPv4 или IPv6.

Соответствует django.forms.fields.IPAddressField and django.forms.fields.GenericIPAddressField.

Сигнатура: IPAddressField(protocol='both', unpack_ipv4=False, **options)

  • protocol Ограничивает допустимые входные данные указанным протоколом. Допустимые значения: 'both' (по умолчанию), 'IPv4' или 'IPv6'. При сопоставлении регистр не учитывается.

  • unpack_ipv4 Распаковывает сопоставленные адреса IPv4, например ::ffff:192.0.2.1. Если эта опция включена, этот адрес будет распакован в 192.0.2.1. По умолчанию отключено. Может использоваться, только если для протокола установлено значение 'both'.

Числовые поля

IntegerField

Целочисленное представление.

Соответствует django.db.models.fields.IntegerField, django.db.models.fields.SmallIntegerField, django.db.models.fields.PositiveIntegerField и django.db.models.fields.PositiveSmallIntegerField.

Сигнатура: IntegerField(max_value=None, min_value=None)

  • max_value Проверяет, что указанное число не больше этого значения.

  • min_value Проверяет, что предоставленное число не меньше этого значения.

FloatField

Представление с плавающей запятой.

Соответствует django.db.models.fields.FloatField.

Сигнатура: FloatField(max_value=None, min_value=None)

  • max_value Проверяет, что указанное число не больше этого значения.

  • min_value Проверяет, что предоставленное число не меньше этого значения.

DecimalField

Десятичное представление, представленное в Python экземпляром Decimal.

Соответствует django.db.models.fields.DecimalField.

Сигнатура: DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None)

  • max_digits Максимальное количество цифр, разрешенное в числе. Оно должно быть либо None, либо целым числом больше или равным decimal_places.

  • decimal_places Количество десятичных разрядов, сохраняемых вместе с числом.

  • coerce_to_string Установите значение True, если строковые значения должны возвращаться для представления, или False, если должны возвращаться объекты Decimal. По умолчанию используется то же значение, что и для ключа настроек COERCE_DECIMAL_TO_STRING, которое будет иметь значение True, если не будет переопределено. Если сериализатор возвращает объекты Decimal, то окончательный выходной формат будет определяться средством визуализации. Обратите внимание, что установка localize приведет к значению True.

  • max_value Проверяет, что указанное число не больше этого значения.

  • min_value Проверяет, что предоставленное число не меньше этого значения.

  • localize Установите значение True, чтобы разрешить локализацию ввода и вывода на основе текущей локали. Это также заставит coerce_to_string установить значение True. По умолчанию False. Обратите внимание, что форматирование данных включено, если вы установили USE_L10N=True в вашем файле настроек.

  • rounding Устанавливает режим округления, используемый при квантовании с заданной точностью. Допустимые значения: режимы округления модуля decimal. По умолчанию None.

Пример использования

To validate numbers up to 999 with a resolution of 2 decimal places, you would use:

Чтобы проверить числа до 999 с разрешением 2 десятичных разряда, вы должны использовать:

serializers.DecimalField(max_digits=5, decimal_places=2)

И для проверки чисел до менее одного миллиарда с разрешением 10 десятичных знаков:

serializers.DecimalField(max_digits=19, decimal_places=10)

Это поле также принимает необязательный аргумент coerce_to_string. Если установлено значение True, представление будет выводиться в виде строки. Если установлено значение False, представление останется как экземпляр Decimal, а окончательное представление будет определяться средством визуализации.

Если не задано, по умолчанию будет установлено то же значение, что и для параметра COERCE_DECIMAL_TO_STRING, то есть True, если не установлено иное.

Поля даты и времени

DateTimeField

Представление даты и времени.

Соответствует django.db.models.fields.DateTimeField.

Сигнатура: DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None, default_timezone=None)

  • format - строка, представляющая выходной формат. Если не указано, по умолчанию используется то же значение, что и для ключа настроек DATETIME_FORMAT, которое будет 'iso-8601', если не установлено. Установка в строку формата указывает, что возвращаемые значения to_presentation должны приводиться к строковому выводу. Строки формата описаны ниже. Установка этого значения в None указывает, что объекты Python datetime должны возвращаться to_presentation. В этом случае кодировка даты и времени будет определяться средством визуализации.

  • input_formats - список строк, представляющих входные форматы, которые могут использоваться для анализа даты. Если не указано, будет использоваться параметр DATETIME_INPUT_FORMATS, который по умолчанию равен ['iso-8601'].

  • default_timezone - pytz.timezone, представляющий часовой пояс. Если не указан и параметр USE_TZ включен, по умолчанию используется [текущий часовой пояс][django-current-timezone]. Если USE_TZ отключен, то объекты datetime будут без указания часового пояса.

DateTimeField format strings.

Строки формата могут быть либо форматами Python strftime, которые явно определяют формат, либо специальной строкой «iso-8601», которая указывает, что следует использовать дату и время в стиле ISO 8601. (например, '2013-01-29T12: 34: 56.000000Z')

Когда значение None используется для формата, объекты datetime будут возвращены to_presentation, и окончательное выходное представление будет определяться классом средства визуализации.

поля модели auto_now и auto_now_add.

При использовании ModelSerializer или HyperlinkedModelSerializer обратите внимание, что любые поля модели с auto_now=True или auto_now_add=True будут использовать поля сериализатора, которые по умолчанию имеют значение read_only=True.

Если вы хотите переопределить это поведение, вам нужно явно объявить DateTimeField в сериализаторе. Например:

class CommentSerializer(serializers.ModelSerializer):
created = serializers.DateTimeField()
class Meta:
model = Comment

DateField

Представление даты.

Соответствует django.db.models.fields.DateField

Сигнатура: DateField(format=api_settings.DATE_FORMAT, input_formats=None)

  • format - строка, представляющая выходной формат. Если не указано, по умолчанию это то же значение, что и ключ настроек DATE_FORMAT, который будет 'iso-8601', если не установлен. Установка в строку формата указывает, что возвращаемые значения to_presentation должны приводиться к строковому выводу. Строки формата описаны ниже. Установка этого значения на None указывает, что объекты Python date должны возвращаться to_presentation. В этом случае кодировку даты будет определять средство визуализации.

  • Input_formats - список строк, представляющих входные форматы, которые могут использоваться для анализа даты. Если не указан, будет использоваться параметр DATE_INPUT_FORMATS, который По умолчанию ['iso-8601'].

DateField format strings

Строки формата могут быть либо форматами Python strftime, которые явно определяют формат, либо специальной строкой «iso-8601», которая указывает, что следует использовать даты стиля ISO 8601. (например, '2013-01-29')

TimeField

Представление времени.

Соответствует django.db.models.fields.TimeField

Сигнатура: TimeField(format=api_settings.TIME_FORMAT, input_formats=None)

  • format - строка, представляющая выходной формат. Если не указано, по умолчанию это то же значение, что и ключ настроек TIME_FORMAT, который будет iso-8601, если не установлен. Установка в строку формата указывает, что возвращаемые значения to_presentation должны приводиться к строковому выводу. Строки формата описаны ниже. Установка этого значения в None указывает, что объекты Python time должны возвращаться to_presentation. В этом случае кодировка времени будет определяться средством визуализации.

  • Input_formats - список строк, представляющих входные форматы, которые могут использоваться для анализа даты. Если не указан, будет использоваться параметр TIME_INPUT_FORMATS, который По умолчанию ['iso-8601'].

Строки формата TimeField

Строки формата могут быть либо форматами Python strftime, которые явно определяют формат, либо специальной строкой 'iso-8601', которая указывает, что следует использовать время стиля ISO 8601. (например, '12:34:56.000000')

DurationField

Представление продолжительности. Соответствует django.db.models.fields.DurationField

The validated_data for these fields will contain a datetime.timedelta instance. The representation is a string following this format '[DD] [HH:[MM:]]ss[.uuuuuu]'.

Validated_data для этих полей будет содержать экземпляр datetime.timedelta. Представление представляет собой строку в следующем формате: '[DD] [HH:[MM:]]ss[.uuuuuu]'.

Сигнатура: DurationField(max_value=None, min_value=None)

  • max_value Проверяет, что предоставленная продолжительность не превышает этого значения.

  • min_value Проверяет, что предоставленная продолжительность не меньше этого значения.

Поля выбора

ChoiceField

Поле, которое может принимать значение из ограниченного набора вариантов.

ModelSerializer использует поле для автоматической генерации полей, если соответствующее поле модели включает аргумент choices=....

Сигнатура: ChoiceField(choices)

  • choices - список допустимых значений или список кортежей (key, display_name).

  • allow_blank - Если установлено значение True, пустая строка должна считаться допустимым значением. Если установлено значение False, то пустая строка считается недопустимой и вызовет ошибку проверки. По умолчанию False.

  • html_cutoff - если установлено, это будет максимальное количество вариантов, которое будет отображаться в раскрывающемся списке выбора HTML. Может использоваться, чтобы гарантировать, что автоматически сгенерированные поля выбора с очень большими возможными вариантами выбора не препятствуют отрисовке шаблона. По умолчанию None.

  • html_cutoff_text - Если установлено, это будет отображать текстовый индикатор, если максимальное количество элементов было обрезано в раскрывающемся списке выбора HTML. По умолчанию: "Более {count} элементов..."

Оба параметра allow_blank и allow_null являются допустимыми параметрами для ChoiceField, хотя настоятельно рекомендуется использовать только один, а не оба. Для текстовых вариантов предпочтительнее использовать allow_blank, а для числовых или других нетекстовых вариантов - allow_null.

MultipleChoiceField

Поле, которое может принимать набор из нуля, одного или нескольких значений, выбранных из ограниченного набора вариантов. Принимает единственный обязательный аргумент. to_internal_value возвращает set, содержащий выбранные значения.

Сигнатура: MultipleChoiceField(choices)

  • choices - список допустимых значений или список кортежей (key, display_name).

  • allow_blank - Если установлено значение True, пустая строка должна считаться допустимым значением. Если установлено значение False, то пустая строка считается недопустимой и вызовет ошибку проверки. По умолчанию False.

  • html_cutoff - если установлено, это будет максимальное количество вариантов, которое будет отображаться в раскрывающемся списке выбора HTML. Может использоваться, чтобы гарантировать, что автоматически сгенерированные поля выбора с очень большими возможными вариантами выбора не препятствуют отрисовке шаблона. По умолчанию None.

  • html_cutoff_text - Если установлено, это будет отображать текстовый индикатор, если максимальное количество элементов было обрезано в раскрывающемся списке выбора HTML. По умолчанию: "Более {count} элементов..."

Как и в случае с ChoiceField, допустимы оба параметра allow_blank и allow_null, хотя настоятельно рекомендуется использовать только один, а не оба. Для текстовых вариантов предпочтительнее использовать allow_blank, а для числовых или других нетекстовых вариантов - allow_null.

Поля для загрузки файлов

Парсеры и загрузки файлов.

The FileField and ImageField classes are only suitable for use with MultiPartParser or FileUploadParser. Most parsers, such as e.g. JSON don't support file uploads. Django's regular FILE_UPLOAD_HANDLERS are used for handling uploaded files.

Классы FileField и ImageField подходят только для использования с MultiPartParser или FileUploadParser. Большинство парсеров, например, JSON не поддерживает загрузку файлов. Обычные FILE_UPLOAD_HANDLERS Django используются для обработки загруженных файлов.

FileField

Представление файла. Выполняет стандартную проверку FileField Django.

Соответствует django.forms.fields.FileField.

Сигнатура: FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)

  • max_length - указывает максимальную длину имени файла.

  • allow_empty_file - указывает, разрешены ли пустые файлы.

  • use_url - Если установлено значение True, тогда для выходного представления будут использоваться строковые значения URL. Если установлено значение False, то для выходного представления будут использоваться строковые значения имени файла. По умолчанию используется значение ключа настроек UPLOADED_FILES_USE_URL, которое равно True, если не установлено иное.

ImageField

Представление изображения. Проверяет, соответствует ли содержимое загруженного файла известному формату изображения.

Соответствует django.forms.fields.ImageField.

Сигнатура: ImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)

  • max_length - указывает максимальную длину имени файла.

  • allow_empty_file - указывает, разрешены ли пустые файлы.

  • use_url - Если установлено значение True, тогда для выходного представления будут использоваться строковые значения URL. Если установлено значение False, то для выходного представления будут использоваться строковые значения имени файла. По умолчанию используется значение ключа настроек UPLOADED_FILES_USE_URL, которое равно True, если не установлено иное.

Требуется либо пакет Pillow, либо пакет PIL. Пакет Pillow рекомендуется, так как PIL больше не поддерживается активно.

Составные поля

ListField

Класс поля, проверяющий список объектов.

Сигнатура: ListField(child=<A_FIELD_INSTANCE>, allow_empty=True, min_length=None, max_length=None)

  • child - экземпляр поля, который следует использовать для проверки объектов в списке. Если этот аргумент не указан, объекты в списке не будут проверяться.

  • allow_empty - указывает, разрешены ли пустые списки.

  • min_length - Проверяет, что список содержит не меньше, чем это количество элементов.

  • max_length - Проверяет, что список содержит не более указанного количества элементов.

Например, чтобы проверить список целых чисел, вы можете использовать что-то вроде следующего:

scores = serializers.ListField(
child=serializers.IntegerField(min_value=0, max_value=100)
)

Класс ListField также поддерживает декларативный стиль, который позволяет вам писать многоразовые классы полей списка.

class StringListField(serializers.ListField):
child = serializers.CharField()

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

DictField

Класс поля, проверяющий словарь объектов. Ключи в DictField всегда считаются строковыми значениями.

Сигнатура: DictField(child=<A_FIELD_INSTANCE>, allow_empty=True)

  • child - экземпляр поля, который следует использовать для проверки значений в словаре. Если этот аргумент не указан, значения в сопоставлении не будут проверяться.

  • allow_empty - указывает, разрешены ли пустые словари.

Например, чтобы создать поле, которое проверяет сопоставление строк со строками, вы должны написать что-то вроде этого:

document = DictField(child=CharField())

Вы также можете использовать декларативный стиль, например ListField. Например:

class DocumentField(DictField):
child = CharField()

HStoreField

Предварительно сконфигурированный DictField, совместимый с postgres Django HStoreField.

Сигнатура: HStoreField(child=<A_FIELD_INSTANCE>, allow_empty=True)

  • child - экземпляр поля, который используется для проверки значений в словаре. Дочернее поле по умолчанию принимает как пустые строки, так и нулевые значения.

  • allow_empty - указывает, разрешены ли пустые словари.

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

JSONField

Класс поля, который проверяет, что структура входящих данных состоит из допустимых примитивов JSON. В альтернативном двоичном режиме он будет представлять и проверять двоичные строки в кодировке JSON.

Сигнатура: JSONField(binary, encoder)

  • binary - Если установлено значение True, то поле будет выводить и проверять закодированную строку JSON, а не примитивную структуру данных. По умолчанию False.

  • encoder - используйте этот кодировщик JSON для сериализации входного объекта. По умолчанию None.

Miscellaneous fields

ReadOnlyField

Класс поля, который просто возвращает значение поля без изменений.

Это поле используется по умолчанию с ModelSerializer при включении имен полей, которые относятся к атрибуту, а не к полю модели.

Сигнатура: ReadOnlyField()

Например, если has_expired был свойством в модели Account, то следующий сериализатор автоматически сгенерировал бы его как ReadOnlyField:

class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
fields = ['id', 'account_name', 'has_expired']

HiddenField

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

Сигнатура: HiddenField()

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

modified = serializers.HiddenField(default=timezone.now)

Класс HiddenField обычно требуется только в том случае, если у вас есть некоторая проверка, которая должна выполняться на основе некоторых предварительно заданных значений полей, но вы не хотите, чтобы все эти поля были доступны конечному пользователю.

Дополнительные примеры по HiddenField см. В документации validators.

ModelField

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

Это поле используется ModelSerializer для соответствия классам полей пользовательской модели.

Сигнатура: ModelField(model_field=<Django ModelField instance>)

Класс ModelField обычно предназначен для внутреннего использования, но при необходимости может использоваться вашим API. Для того, чтобы правильно создать экземпляр ModelField, ему необходимо передать поле, которое присоединено к созданной модели. Например: ModelField(model_field=MyModel()._meta.get_field('custom_field'))

SerializerMethodField

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

Сигнатура: SerializerMethodField(method_name=None)

  • method_name - Имя вызываемого метода сериализатора. Если не включен, по умолчанию используется get_<field_name>.

Метод сериализатора, на который указывает аргумент method_name, должен принимать единственный аргумент (в дополнение к self), который является сериализуемым объектом. Он должен возвращать все, что вы хотите включить в сериализованное представление объекта. Например:

from django.contrib.auth.models import User
from django.utils.timezone import now
from rest_framework import serializers
class UserSerializer(serializers.ModelSerializer):
days_since_joined = serializers.SerializerMethodField()
class Meta:
model = User
def get_days_since_joined(self, obj):
return (now() - obj.date_joined).days

Настраиваемые поля

Если вы хотите создать настраиваемое поле, вам нужно создать подкласс Field, а затем переопределить один или оба метода .to_presentation()и .to_internal_value(). Эти два метода используются для преобразования между исходным типом данных и примитивным сериализуемым типом данных. Примитивные типы данных обычно будут любыми из числа, строки, логического значения, date/time/datetime или None. Они также могут быть любым объектом, подобным списку или словарю, который содержит только другие примитивные объекты. Другие типы могут поддерживаться в зависимости от используемого средства визуализации.

Метод .to_presentation () вызывается для преобразования исходного типа данных в примитивный сериализуемый тип данных.

Метод .to_internal_value() вызывается для восстановления примитивного типа данных во внутреннем представлении Python. Этот метод должен вызвать ошибку serializers.ValidationError, если данные недействительны.

Примеры

Базовое настраиваемое поле

Давайте посмотрим на пример сериализации класса, представляющего значение цвета RGB:

class Color:
"""
A color represented in the RGB colorspace.
"""
def __init__(self, red, green, blue):
assert(red >= 0 and green >= 0 and blue >= 0)
assert(red < 256 and green < 256 and blue < 256)
self.red, self.green, self.blue = red, green, blue
class ColorField(serializers.Field):
"""
Color objects are serialized into 'rgb(#, #, #)' notation.
"""
def to_representation(self, value):
return "rgb(%d, %d, %d)" % (value.red, value.green, value.blue)
def to_internal_value(self, data):
data = data.strip('rgb(').rstrip(')')
red, green, blue = [int(col) for col in data.split(',')]
return Color(red, green, blue)

По умолчанию значения полей обрабатываются как сопоставление с атрибутом объекта. Если вам нужно настроить способ доступа и установки значения поля, вам необходимо переопределить .get_attribute() и/или .get_value().

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

class ClassNameField(serializers.Field):
def get_attribute(self, instance):
# We pass the object instance onto `to_representation`,
# not just the field attribute.
return instance
def to_representation(self, value):
"""
Serialize the value's class name.
"""
return value.__class__.__name__

Вызов ошибок валидации

Наш класс ColorField в настоящее время не выполняет никакой проверки данных. Чтобы указать недопустимые данные, мы должны вызвать serializers.ValidationError, например:

def to_internal_value(self, data):
if not isinstance(data, str):
msg = 'Incorrect type. Expected a string, but got %s'
raise ValidationError(msg % type(data).__name__)
if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):
raise ValidationError('Incorrect format. Expected `rgb(#,#,#)`.')
data = data.strip('rgb(').rstrip(')')
red, green, blue = [int(col) for col in data.split(',')]
if any([col > 255 or col < 0 for col in (red, green, blue)]):
raise ValidationError('Value out of range. Must be between 0 and 255.')
return Color(red, green, blue)

Метод .fail() - это шорткат для вызова ValidationError, который берет строку сообщения из словаря error_messages. Например:

default_error_messages = {
'incorrect_type': 'Incorrect type. Expected a string, but got {input_type}',
'incorrect_format': 'Incorrect format. Expected `rgb(#,#,#)`.',
'out_of_range': 'Value out of range. Must be between 0 and 255.'
}
def to_internal_value(self, data):
if not isinstance(data, str):
self.fail('incorrect_type', input_type=type(data).__name__)
if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):
self.fail('incorrect_format')
data = data.strip('rgb(').rstrip(')')
red, green, blue = [int(col) for col in data.split(',')]
if any([col > 255 or col < 0 for col in (red, green, blue)]):
self.fail('out_of_range')
return Color(red, green, blue)

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

Использование source = '*'

Здесь мы возьмем пример плоской модели DataPoint с атрибутами x_coordinate и y_coordinate.

class DataPoint(models.Model):
label = models.CharField(max_length=50)
x_coordinate = models.SmallIntegerField()
y_coordinate = models.SmallIntegerField()

Используя настраиваемое поле и source='*', мы можем предоставить вложенное представление пары координат:

class CoordinateField(serializers.Field):
def to_representation(self, value):
ret = {
"x": value.x_coordinate,
"y": value.y_coordinate
}
return ret
def to_internal_value(self, data):
ret = {
"x_coordinate": data["x"],
"y_coordinate": data["y"],
}
return ret
class DataPointSerializer(serializers.ModelSerializer):
coordinates = CoordinateField(source='*')
class Meta:
model = DataPoint
fields = ['label', 'coordinates']

Обратите внимание, что этот пример не обрабатывает проверку. Частично по этой причине в реальном проекте вложение координат лучше обрабатывать с помощью вложенного сериализатора, использующего source='*', с двумя экземплярами IntegerField, каждый со своим собственным source, указывающим на соответствующее поле.

Однако ключевыми моментами этого примера являются:

  • to_representation передается весь объектDataPoint и должен отображать его в желаемый результат.

>>> instance = DataPoint(label='Example', x_coordinate=1, y_coordinate=2)
>>> out_serializer = DataPointSerializer(instance)
>>> out_serializer.data
ReturnDict([('label', 'Example'), ('coordinates', {'x': 1, 'y': 2})])
  • Если наше поле не предназначено только для чтения, to_internal_value должно отображаться обратно в dict, подходящий для обновления нашего целевого объекта. С source='*' возврат из to_internal_value обновит корневой проверенный словарь данных, а не единственный ключ.

>>> data = {
... "label": "Second Example",
... "coordinates": {
... "x": 3,
... "y": 4,
... }
... }
>>> in_serializer = DataPointSerializer(data=data)
>>> in_serializer.is_valid()
True
>>> in_serializer.validated_data
OrderedDict([('label', 'Second Example'),
('y_coordinate', 4),
('x_coordinate', 3)])

Для полноты картины давайте сделаем то же самое снова, но с подходом вложенного сериализатора, предложенным выше:

class NestedCoordinateSerializer(serializers.Serializer):
x = serializers.IntegerField(source='x_coordinate')
y = serializers.IntegerField(source='y_coordinate')
class DataPointSerializer(serializers.ModelSerializer):
coordinates = NestedCoordinateSerializer(source='*')
class Meta:
model = DataPoint
fields = ['label', 'coordinates']

Здесь сопоставление между парами атрибутов цели и источника (x и x_coordinate, y и y_coordinate) обрабатывается в объявлениях IntegerField. Это наш NestedCoordinateSerializer, который принимает source='*'.

Наш новый DataPointSerializer демонстрирует то же поведение, что и подход с настраиваемым полем.

Сериализация:

>>> out_serializer = DataPointSerializer(instance)
>>> out_serializer.data
ReturnDict([('label', 'testing'),
('coordinates', OrderedDict([('x', 1), ('y', 2)]))])

Десериализация:

>>> in_serializer = DataPointSerializer(data=data)
>>> in_serializer.is_valid()
True
>>> in_serializer.validated_data
OrderedDict([('label', 'still testing'),
('x_coordinate', 3),
('y_coordinate', 4)])

Но мы также бесплатно получаем встроенную проверку:

>>> invalid_data = {
... "label": "still testing",
... "coordinates": {
... "x": 'a',
... "y": 'b',
... }
... }
>>> invalid_serializer = DataPointSerializer(data=invalid_data)
>>> invalid_serializer.is_valid()
False
>>> invalid_serializer.errors
ReturnDict([('coordinates',
{'x': ['A valid integer is required.'],
'y': ['A valid integer is required.']})])

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

Сторонние пакеты

Также доступны следующие сторонние пакеты.

DRF Compound Fields

Пакет [drf-compound-fields][drf-составные-поля] предоставляет "составные" поля сериализатора, такие как списки простых значений, которые могут быть описаны другими полями, а не сериализаторами с параметром many=True. Также предусмотрены поля для типизированных словарей и значений, которые могут быть либо определенного типа, либо списком элементов этого типа.

DRF Extra Fields

Пакет drf-extra-fields предоставляет дополнительные поля сериализатора для REST framework, включая классы Base64ImageField и PointField.

djangorestframework-recursive

Пакет djangorestframework-recursive предоставляет RecursiveField для сериализации и десериализации рекурсивных структур

django-rest-framework-gis

Пакет django-rest-framework-gis предоставляет географические дополнения для django rest framework, такие как поле GeometryField и сериализатор GeoJSON.

django-rest-framework-hstore

Пакет django-rest-framework-hstore предоставляет HStoreField для поддержки поля модели django-hstore DictionaryField.

[django-current-timezone]: https://docs.djangoproject.com/en/stable/topics/i18n/timezones/#default-time-zone-and-current-time-zone