Поля сериализатора¶
Каждое поле в классе Form отвечает не только за проверку данных, но и за их «очистку» ‒ нормализацию до согласованного формата.
‒ Django documentation
Поля сериализатора выполняют преобразование между примитивными значениями и внутренними типами данных. Они также занимаются проверкой входных значений, а также получением и установкой значений из своих родительских объектов.
Примечание: Поля сериализатора объявлены в fields.py
, но по соглашению вы должны импортировать их, используя from rest_framework import serializers
и ссылаться на поля как serializers.<FieldName>
.
Основные аргументы¶
Каждый конструктор класса поля сериализатора принимает как минимум эти аргументы. Некоторые классы Field принимают дополнительные, специфические для данного поля аргументы, но следующие должны приниматься всегда:
read_only
¶
Поля только для чтения включаются в вывод API, но не должны включаться во ввод при операциях создания или обновления. Любые поля «только для чтения», которые неправильно включены во входные данные сериализатора, будут проигнорированы.
Установите значение 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')
. При сериализации полей с точечной нотацией может потребоваться значение default
, если какой-либо объект отсутствует или пуст во время обхода атрибутов.
Значение 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 & Forms.
Булевы поля¶
BooleanField¶
Булево представление.
При использовании HTML-кодированных форм ввода следует помнить, что пропуск значения всегда будет рассматриваться как установка поля в значение False
, даже если для него задана опция default=True
. Это связано с тем, что входы с флажками HTML представляют состояние без флажка, когда значение отсутствует, поэтому фреймворк REST рассматривает отсутствие значения как пустой вход с флажком.
Обратите внимание, что в Django 2.1 из blank
убран карг 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.core.validators.RegexValidator
от Django для валидации.
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.core.validators.URLValidator
Django для валидации.
Подпись: 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
и 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:doc:` module rounding modes <https://docs.python.org/3/library/decimal.html#rounding-modes>`. По умолчаниюNone
.
Для проверки чисел до 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_representation
должны быть принудительно выведены в строку. Форматные строки описаны ниже. Установка этого значения вNone
указывает, что объекты Pythondatetime
должны быть возвращеныto_representation
. В этом случае кодировка времени суток будет определяться рендерером.input_formats
- Список строк, представляющих входные форматы, которые могут быть использованы для разбора даты. Если не указано, то будет использоваться параметрDATETIME_INPUT_FORMATS
, который по умолчанию равен['iso-8601']
.default_timezone
-pytz.timezone
, представляющий часовой пояс. Если не указано и включен параметрUSE_TZ
, то по умолчанию используется current timezone. Если параметрUSE_TZ
отключен, то объекты datetime будут наивными.
Строки формата могут быть либо Python strftime formats, которые явно указывают формат, либо специальная строка 'iso-8601'
, которая указывает на то, что следует использовать время даты в стиле ISO 8601. (например, '2013-01-29T12:34:56.000000Z'
)
При использовании значения None
для формата datetime
объекты будут возвращены to_representation
, а окончательное представление вывода будет определяться классом рендерера.
При использовании 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_representation
должны быть принудительно выведены в строку. Форматные строки описаны ниже. Установка этого значения вNone
указывает, что объекты Pythondate
должны быть возвращеныto_representation
. В этом случае кодировка даты будет определяться рендерером.input_formats
- Список строк, представляющих входные форматы, которые могут быть использованы для разбора даты. Если не указано, то будет использоваться параметрDATE_INPUT_FORMATS
, который по умолчанию равен['iso-8601']
.
Строки формата могут быть либо Python strftime formats, которые явно указывают формат, либо специальная строка '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_representation
должны быть принудительно выведены в строку. Форматные строки описаны ниже. Установка этого значения вNone
указывает, что объекты Pythontime
должны быть возвращеныto_representation
. В этом случае кодировка времени будет определяться рендерером.input_formats
- Список строк, представляющих входные форматы, которые могут быть использованы для разбора даты. Если не указано, то будет использоваться параметрTIME_INPUT_FORMATS
, который по умолчанию равен['iso-8601']
.
Строки формата могут быть либо Python strftime formats, которые явно указывают формат, либо специальная строка 'iso-8601'
, которая указывает, что следует использовать время в стиле ISO 8601. (например, ``“12:34:56.000000“``** )
DurationField¶
Представление длительности. Соответствует django.db.models.fields.DurationField
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 select. Может использоваться для того, чтобы автоматически генерируемые поля выбора с очень большим количеством возможных вариантов выбора не препятствовали отрисовке шаблона. По умолчанию установлено значениеNone
.html_cutoff_text
- Если установлено, то будет отображаться текстовый индикатор, если максимальное количество элементов было отсечено в выпадающем списке HTML select. По умолчанию"More than {count} items…"
И 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 select. Может использоваться для того, чтобы автоматически генерируемые поля выбора с очень большим количеством возможных вариантов выбора не препятствовали отрисовке шаблона. По умолчанию установлено значениеNone
.html_cutoff_text
- Если установлено, то будет отображаться текстовый индикатор, если максимальное количество элементов было отсечено в выпадающем списке HTML select. По умолчанию"More than {count} items…"
Как и в случае с ChoiceField
, оба варианта allow_blank
и allow_null
являются допустимыми, хотя настоятельно рекомендуется использовать только один из них, а не оба. allow_blank
следует предпочесть для текстовых вариантов, а allow_null
- для числовых или других нетекстовых вариантов.
Поля загрузки файлов¶
Классы FileField
и ImageField
подходят только для использования с MultiPartParser
или FileUploadParser
. Большинство парсеров, таких как, например, JSON, не поддерживают загрузку файлов. Для работы с загруженными файлами в Django используются регулярные FILE_UPLOAD_HANDLERS.
FileField¶
Представление файла. Выполняет стандартную для Django валидацию FileField.
Соответствует 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
, который совместим с постгрес 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
.
Разные поля¶
ReadOnlyField¶
Класс поля, который просто возвращает значение поля без модификации.
Это поле используется по умолчанию с ModelSerializer
при включении имен полей, относящихся к атрибуту, а не к полю модели.
Подпись : ReadOnlyField()
Например, если has_expired
было свойством модели Account
, то следующий сериализатор автоматически сгенерирует его как ``ReadOnlyField``** :
class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
fields = ['id', 'account_name', 'has_expired']
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
fields = '__all__'
def get_days_since_joined(self, obj):
return (now() - obj.date_joined).days
Пользовательские поля¶
Если вы хотите создать пользовательское поле, вам необходимо создать подкласс Field
и переопределить один или оба метода .to_representation()
и .to_internal_value()
. Эти два метода используются для преобразования между исходным типом данных и примитивным, сериализуемым типом данных. Примитивными типами данных обычно являются числа, строки, булевы, date
/** time
/** datetime
или None
. Они также могут быть любым списком или словарем, который содержит только другие примитивные объекты. Могут поддерживаться и другие типы, в зависимости от используемого рендерера.
Метод .to_representation()
вызывается для преобразования исходного типа данных в примитивный, сериализуемый тип данных.
Метод .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
должно возвращаться к дикте, подходящей для обновления нашего целевого объекта. При использовании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¶
Пакет drf-compound-fields предоставляет «составные» поля сериализатора, такие как списки простых значений, которые могут быть описаны другими полями, а не сериализаторами с помощью опции many=True
. Также предоставляются поля для типизированных словарей и значений, которые могут быть либо определенным типом, либо списком элементов этого типа.
Дополнительные поля DRF¶
Пакет drf-extra-fields предоставляет дополнительные поля сериализатора для фреймворка REST, включая классы 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
модельного поля.