[DRF] Serializer fields

강민성·2024년 9월 21일
Django REST frameworkdjangodrf

DRF API Guide

목록 보기
10/28

Serializer 필드

Form 클래스에서 각 필드는 데이터 유효성 검사를 수행할 뿐만 아니라 데이터를 "정리"하고, 일관된 형식으로 정규화하는 역할을 담당합니다.
— Django 문서

Serializer 필드는 기본 값과 내부 데이터 유형 간의 변환을 처리합니다. 또한 입력 값의 유효성 검사와 부모 객체에서 값을 가져오고 설정하는 역할도 담당합니다.

참고: Serializer 필드는 fields.py에 선언되어 있지만, 관례적으로 from rest_framework import serializers를 사용하여 가져와야 하며, 필드를 serializers.<FieldName> 형태로 참조해야 합니다.

핵심 인자

각 serializer 필드 클래스의 생성자는 최소한 다음 인자를 받습니다. 일부 필드 클래스는 추가 필드별 인자를 필요로 할 수 있지만, 다음 인자들은 항상 받아야 합니다:

read_only

읽기 전용 필드는 API 출력에 포함되지만, 생성 또는 업데이트 작업 중에는 입력으로 포함되어서는 안 됩니다. 잘못 포함된 'read_only' 필드는 serializer 입력에서 무시됩니다.

이 필드를 True로 설정하면 직렬화 과정에서는 사용되지만, 역직렬화 과정에서 인스턴스를 생성하거나 업데이트할 때는 사용되지 않습니다.

기본값은 False입니다.

write_only

이 필드를 True로 설정하면 인스턴스를 업데이트하거나 생성할 때 사용할 수 있지만, 직렬화 표현에서는 제외됩니다.

기본값은 False입니다.

required

보통 역직렬화 중에 필드가 제공되지 않으면 오류가 발생합니다. 이 필드가 역직렬화 중에 필수로 존재할 필요가 없는 경우 False로 설정할 수 있습니다.

이 값을 False로 설정하면 객체 속성이나 딕셔너리 키가 직렬화할 때 출력에서 생략될 수 있습니다. 키가 존재하지 않으면 단순히 출력 표현에서 제외됩니다.

기본값은 True입니다. Model Serializer를 사용할 경우, 모델 필드에서 blank=True 또는 default, null=True를 지정한 경우 기본값은 False로 설정됩니다.

default

설정된 경우, 입력 값이 제공되지 않았을 때 필드에 사용할 기본값을 제공합니다. 설정되지 않은 경우 기본 동작은 속성을 전혀 채우지 않는 것입니다.

기본값은 부분 업데이트 작업 중에는 적용되지 않습니다. 부분 업데이트의 경우, 입력 데이터에서 제공된 필드만 유효한 값이 반환됩니다.

기본값으로 함수나 기타 호출 가능한 객체를 설정할 수 있으며, 이 경우 값이 사용할 때마다 평가됩니다. 호출 시 인자를 받지 않습니다. requires_context = True 속성을 가진 호출 가능한 객체는 serializer 필드를 인자로 전달받습니다.

예를 들어:

class CurrentUserDefault:
    """
    serializer 필드에서 `default=...` 값으로 적용할 수 있습니다.
    현재 사용자를 반환합니다.
    """
    requires_context = True

    def __call__(self, serializer_field):
        return serializer_field.context['request'].user

인스턴스를 직렬화할 때, 객체 속성이나 딕셔너리 키가 인스턴스에 존재하지 않으면 default 값이 사용됩니다.

기본값을 설정하면 필드가 필수적이지 않다는 것을 의미합니다. default와 required 키워드 인수를 모두 포함하는 것은 유효하지 않으며 오류를 발생시킵니다.

allow_null

보통 None이 serializer 필드에 전달되면 오류가 발생합니다. None을 유효한 값으로 간주해야 하는 경우 이 인자를 True로 설정할 수 있습니다.

명시적인 기본값이 없는 경우, 이 인자를 True로 설정하면 직렬화 출력에 대해 기본적으로 null 값이 설정되지만, 입력 역직렬화에 대해서는 기본값이 설정되지 않습니다.

기본값은 False입니다.

source

필드를 채우기 위해 사용할 속성의 이름입니다. self 인자만 받는 메서드일 수 있으며, 예를 들어 URLField(source='get_absolute_url')와 같이 사용할 수 있습니다. 또한, EmailField(source='user.email')과 같이 점 표기법을 사용하여 속성을 탐색할 수도 있습니다.

점 표기법으로 필드를 직렬화할 때, 속성 탐색 중 객체가 존재하지 않거나 비어 있는 경우 기본값을 제공해야 할 수도 있습니다. 관계형 ORM 모델을 참조하는 경우 source 속성을 사용할 때 n+1 문제에 주의해야 합니다. 예를 들어:

class CommentSerializer(serializers.Serializer):
    email = serializers.EmailField(source="user.email")

이 경우, 데이터베이스에서 user 객체를 가져와야 합니다. 이를 피하고 싶다면 prefetch_related 및 select_related 메서드를 적절히 사용해야 합니다. 이 메서드에 대한 자세한 내용은 Django 문서를 참조하세요.

source='*' 값은 특별한 의미를 가지며, 전체 객체를 필드로 전달해야 함을 나타냅니다. 이는 중첩된 표현을 생성하거나, 출력 표현을 결정하기 위해 전체 객체에 접근해야 하는 필드에 유용할 수 있습니다.

기본값은 필드 이름입니다.

validators

입력 필드 값에 대해 적용할 유효성 검사 함수 목록입니다. 유효성 검사 함수는 일반적으로 serializers.ValidationError를 발생시켜야 하지만, Django의 내장 ValidationError도 Django 코드베이스나 서드파티 패키지에서 정의된 유효성 검사와의 호환성을 위해 지원됩니다.

error_messages

오류 코드와 오류 메시지의 딕셔너리입니다.

label

HTML 폼 필드나 기타 설명 요소에서 필드 이름으로 사용될 수 있는 짧은 텍스트 문자열입니다.

help_text

HTML 폼 필드나 기타 설명 요소에서 필드 설명으로 사용될 수 있는 텍스트 문자열입니다.

initial

HTML 폼 필드 값을 미리 채우는 데 사용할 값입니다. 이를 정규 Django 필드에서와 마찬가지로 호출 가능한 객체로 설정할 수 있습니다:

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

style

렌더러가 필드를 렌더링하는 방식을 제어하는 데 사용할 수 있는 키-값 쌍의 딕셔너리입니다.

두 가지 예는 input_type과 base_template입니다:

# 입력 필드를 <input type="password">로 사용
password = serializers.CharField(
    style={'input_type': 'password'}
)

# select 대신 라디오 입력 사용
color_channel = serializers.ChoiceField(
    choices=['red', 'green', 'blue'],
    style={'base_template': 'radio.html'}
)

더 자세한 내용은 HTML & Forms 문서를 참조하세요.

Boolean 필드

BooleanField

불리언 값을 나타냅니다.

HTML로 인코딩된 form 입력을 사용할 때 값을 생략하면, 해당 필드에 default=True 옵션이 지정되어 있더라도 항상 False로 처리된다는 점을 유의해야 합니다. 이는 HTML 체크박스 입력이 선택되지 않은 상태를 값의 생략으로 나타내기 때문에, REST 프레임워크에서는 값이 생략된 경우를 빈 체크박스로 간주합니다.

Django 2.1부터는 models.BooleanField에서 blank 인수가 제거되었습니다. Django 2.1 이전에는 models.BooleanField 필드가 항상 blank=True로 설정되었습니다. 따라서 Django 2.1 이후에는 기본적으로 serializers.BooleanField 인스턴스가 required 인수 없이 생성되며(즉, required=True와 동일), 이전 버전에서는 required=False 옵션이 있는 기본 BooleanField 인스턴스가 생성되었습니다. 이 동작을 수동으로 제어하려면, 직렬화 클래스에서 BooleanField를 명시적으로 선언하거나, extra_kwargs 옵션을 사용하여 required 플래그를 설정할 수 있습니다.

해당 필드는 django.db.models.fields.BooleanField에 대응합니다.

표기: BooleanField()

문자열 필드

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 인수는 문자열이거나 컴파일된 파이썬 정규 표현식 객체일 수 있습니다.
Django의 django.core.validators.RegexValidator를 사용하여 검증합니다.

SlugField

입력이 [a-zA-Z0-9_-]+ 패턴과 일치하는지 검증하는 RegexField입니다.

해당 필드는 django.db.models.fields.SlugField에 대응합니다.

표기: SlugField(max_length=50, min_length=None, allow_blank=False)

URLField

입력이 URL 패턴과 일치하는지 검증하는 RegexField입니다. 완전한 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': 하이픈이 포함된 16진수 표준 표현: "5ce0e9a5-5ffa-654b-cee0-1238041fb31a"
    • 'hex': 하이픈이 없는 16진수 간결 표현: "5ce0e9a55ffa654bcee01238041fb31a"
    • 'int': 128비트 정수로 표현: "123456789012312313134124512351145145114"
    • 'urn': RFC 4122 URN 표현: "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: path의 모든 하위 디렉토리를 포함할지 여부를 지정합니다. 기본값은 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

소수(decimal)를 표현하는 필드로, 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로 설정하고, Decimal 객체가 반환되어야 할 경우 False로 설정합니다. 기본값은 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입니다.
  • normalize_output: 직렬화 시 소수 값을 정규화할지 여부를 설정합니다. 이 옵션을 활성화하면 모든 끝에 붙은 0이 제거되고, 데이터를 잃지 않고 값을 표현할 수 있는 최소 정밀도로 값의 정밀도가 변경됩니다. 기본값은 False입니다.

사용 예시:
숫자를 999까지, 소수 자릿수 2로 검증하려면 다음과 같이 사용할 수 있습니다:

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

숫자를 10억 미만, 소수 자릿수 10으로 검증하려면 다음과 같이 사용할 수 있습니다:

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

날짜와 시간 필드

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으로 설정하면 to_representation이 Python datetime 객체를 반환하며, 이 경우 datetime 인코딩은 렌더러에 의해 결정됩니다.
  • input_formats: 날짜를 구문 분석하는 데 사용할 수 있는 입력 형식 목록입니다. 지정하지 않으면 DATETIME_INPUT_FORMATS 설정이 사용되며, 기본값은 ['iso-8601']입니다.
  • default_timezone: 시간대를 나타내는 tzinfo 하위 클래스(zoneinfo 또는 pytz)입니다. 지정하지 않고 USE_TZ 설정이 활성화되어 있으면 기본적으로 현재 시간대를 사용합니다. USE_TZ가 비활성화된 경우 datetime 객체는 naive 상태로 남습니다.

DateTimeField 형식 문자열
형식 문자열은 Python의 strftime 형식을 사용하거나, ISO 8601 스타일 날짜 및 시간을 나타내는 특수 문자열 'iso-8601'을 사용할 수 있습니다. (예: '2013-01-29T12:34:56.000000Z')

형식을 None으로 설정하면 to_representation에서 datetime 객체가 반환되고 최종 출력 형식은 렌더러 클래스에 의해 결정됩니다.

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_representation 반환 값이 문자열로 변환됩니다. 형식 문자열은 아래에 설명되어 있습니다. 이 값을 None으로 설정하면 to_representation에서 Python date 객체가 반환되고, 이 경우 날짜 인코딩은 렌더러에 의해 결정됩니다.
  • input_formats: 날짜를 구문 분석하는 데 사용할 수 있는 입력 형식 목록입니다. 지정하지 않으면 DATE_INPUT_FORMATS 설정이 사용되며, 기본값은 ['iso-8601']입니다.

DateField 형식 문자열
형식 문자열은 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_representation의 반환 값이 문자열로 변환됩니다. 형식 문자열은 아래에 설명되어 있습니다. 이 값을 None으로 설정하면 to_representation에서 Python time 객체가 반환되고, 이 경우 시간 인코딩은 렌더러에 의해 결정됩니다.
  • input_formats: 시간을 구문 분석하는 데 사용할 수 있는 입력 형식 목록입니다. 지정하지 않으면 TIME_INPUT_FORMATS 설정이 사용되며, 기본값은 ['iso-8601']입니다.

TimeField 형식 문자열
형식 문자열은 Python의 strftime 형식을 사용하거나, ISO 8601 스타일 시간을 나타내는 특수 문자열 'iso-8601'을 사용할 수 있습니다. (예: '12:34:56.000000')

DurationField

기간을 표현하는 필드로, Python timedelta 인스턴스를 사용합니다.

django.db.models.fields.DurationField에 대응합니다.

이 필드는 Python의 timedelta 인스턴스와 상호작용하며, ISO 8601 기간 형식 (예: "P4DT1H"은 4일 1시간을 나타냄) 또는 Django 기본 표현 형식인 "HH:MM[:ss[.uuuuuu]]"로 직렬화됩니다.

표기: DurationField(max_value=None, min_value=None)

  • max_value: 기간의 값이 이 값보다 크지 않게끔 설정합니다.
  • min_value: 기간의 값이 이 값보다 작지 않게끔 설정합니다.

선택 필드 (Choice selection fields)

ChoiceField

제한된 선택지 중에서 하나의 값을 받아들이는 필드입니다.

해당 모델 필드에 choices=... 인자가 포함된 경우, ModelSerializer가 이 필드를 자동으로 생성하는 데 사용됩니다.

  • 표기: ChoiceField(choices)
  • choices: 유효한 값들의 리스트 또는 (key, display_name) 튜플 리스트.
  • allow_blank: True로 설정하면 빈 문자열도 유효한 값으로 간주됩니다. False로 설정하면 빈 문자열은 유효하지 않으며 유효성 검사 오류가 발생합니다. 기본값은 False입니다.
  • html_cutoff: 설정할 경우, HTML 선택 드롭다운에서 표시되는 선택지의 최대 수를 제한합니다. 매우 많은 선택지가 있는 경우, 템플릿 렌더링에 영향을 미치는 것을 방지할 수 있습니다. 기본값은 None입니다.
  • html_cutoff_text: HTML 선택 드롭다운에서 선택 항목이 잘릴 경우, 이 텍스트가 표시됩니다. 기본값은 "More than {count} items..."입니다.

allow_blank과 allow_null은 둘 다 ChoiceField에서 사용할 수 있지만, 둘 중 하나만 사용하는 것이 좋습니다. allow_blank는 텍스트 선택 항목에, allow_null은 숫자 또는 기타 텍스트가 아닌 선택 항목에 사용하는 것이 좋습니다.

MultipleChoiceField

제한된 선택지 중에서 0개, 1개 또는 여러 개의 값을 받을 수 있는 필드입니다. 필수 인자로 choices를 받습니다. to_internal_value는 선택된 값을 포함하는 집합을 반환합니다.

  • 표기: MultipleChoiceField(choices)
  • choices: 유효한 값들의 리스트 또는 (key, display_name) 튜플 리스트.
  • allow_blank: True로 설정하면 빈 문자열도 유효한 값으로 간주됩니다. False로 설정하면 빈 문자열은 유효하지 않으며 유효성 검사 오류가 발생합니다. 기본값은 False입니다.
  • html_cutoff: 설정할 경우, HTML 선택 드롭다운에서 표시되는 선택지의 최대 수를 제한합니다. 기본값은 None입니다.
  • html_cutoff_text: HTML 선택 드롭다운에서 선택 항목이 잘릴 경우, 이 텍스트가 표시됩니다. 기본값은 "More than {count} items..."입니다.

ChoiceField와 마찬가지로 allow_blank과 allow_null 옵션은 모두 사용 가능하지만, 둘 중 하나만 사용하는 것이 좋습니다. allow_blank는 텍스트 선택 항목에, allow_null은 숫자 또는 기타 텍스트가 아닌 선택 항목에 사용하는 것이 좋습니다.

파일 업로드 필드 (File upload fields)

파서와 파일 업로드 (Parsers and file uploads)

FileField와 ImageField 클래스는 MultiPartParser 또는 FileUploadParser와 함께 사용해야 합니다. JSON과 같은 대부분의 파서들은 파일 업로드를 지원하지 않습니다. Django의 일반적인 FILE_UPLOAD_HANDLERS는 업로드된 파일을 처리하는 데 사용됩니다.

FileField

파일을 나타내는 필드입니다. Django의 표준 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

이미지를 나타내는 필드로, 업로드된 파일이 유효한 이미지 형식인지 확인합니다.

  • 표기: 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 패키지는 더 이상 적극적으로 유지 관리되지 않습니다.

복합 필드 (Composite fields)

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

Django의 Postgres HStoreField와 호환되는 사전 필드입니다.

  • 표기: HStoreField(child=<A_FIELD_INSTANCE>, allow_empty=True)
  • child: 사전 값의 유효성을 검증하는 데 사용되는 필드 인스턴스입니다. 기본적으로 CharField를 사용하며, 빈 문자열 및 null 값을 허용합니다.
  • allow_empty: 빈 사전이 허용되는지 여부를 지정합니다.

child 필드는 반드시 CharField 인스턴스여야 합니다. 이는 hstore 확장이 값을 문자열로 저장하기 때문입니다.

JSONField

유효한 JSON 기본형으로 구성된 데이터 구조를 검증하는 필드 클래스입니다. 이 필드는 이진 모드에서도 JSON-인코딩된 문자열을 표현하고 검증할 수 있습니다.

  • 표기: JSONField(binary, encoder)
  • binary: True로 설정하면 필드는 JSON 인코딩된 문자열을 출력하고 검증합니다. 기본값은 False입니다.
  • encoder: 입력 객체를 직렬화하는 데 사용할 JSON 인코더입니다. 기본값은 None입니다.

기타 필드

ReadOnlyField

값을 수정 없이 그대로 반환하는 필드 클래스입니다.

이 필드는 모델 필드가 아닌 속성과 관련된 필드 이름을 포함할 때 기본적으로 ModelSerializer에 의해 사용됩니다.

  • 표기: ReadOnlyField()

예를 들어, has_expired가 Account 모델의 속성이라면, 다음과 같은 serializer가 자동으로 이를 ReadOnlyField로 생성합니다:

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

HiddenField

사용자 입력에 기반하여 값을 취하지 않고, 대신 기본값 또는 호출 가능한 객체에서 값을 취하는 필드 클래스입니다.

  • 표기: HiddenField()

예를 들어, 항상 현재 시간을 serializer 유효성 검사된 데이터의 일부로 제공하는 필드를 포함하려면 다음과 같이 사용할 수 있습니다:

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

HiddenField 클래스는 일반적으로 일부 미리 제공된 필드 값에 기반한 유효성 검사를 수행해야 할 때 필요하지만, 모든 필드를 최종 사용자에게 노출하고 싶지 않을 때 사용됩니다.

HiddenField에 대한 더 많은 예는 Validators 문서를 참조하세요.

참고: HiddenField()는 partial=True serializer(패치 요청을 할 때)에서 나타나지 않습니다. 이 동작은 향후 변경될 수 있으니, GitHub discussion에서 업데이트를 확인하세요.

ModelField

임의의 모델 필드에 연결될 수 있는 일반 필드입니다. ModelField 클래스는 직렬화/역직렬화 작업을 연결된 모델 필드에 위임합니다. 이 필드는 새로운 사용자 정의 serializer 필드를 만들지 않고도 사용자 정의 모델 필드에 대한 serializer 필드를 생성하는 데 사용할 수 있습니다.

이 필드는 ModelSerializer에 의해 사용자 정의 모델 필드 클래스에 대응하는 데 사용됩니다.

  • 표기: ModelField(model_field=<Django ModelField 인스턴스>)

ModelField 클래스는 일반적으로 내부 용도로 의도되지만, 필요에 따라 API에서 사용할 수 있습니다. 올바르게 ModelField를 인스턴스화하려면 인스턴스화된 모델에 연결된 필드를 전달해야 합니다. 예를 들어: ModelField(model_field=MyModel()._meta.get_field('custom_field'))

SerializerMethodField

읽기 전용 필드입니다. 이 필드는 연결된 serializer 클래스에서 메서드를 호출하여 값을 가져옵니다. 객체의 직렬화된 표현에 어떤 종류의 데이터를 추가하는 데 사용할 수 있습니다.

  • 표기: SerializerMethodField(method_name=None)

  • method_name: 호출될 serializer 메서드의 이름입니다. 포함되지 않은 경우 기본값은 get_<field_name>입니다.

method_name 인수로 참조된 serializer 메서드는 (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

사용자 정의 필드 (Custom fields)

사용자 정의 필드를 만들고 싶다면 Field를 서브클래싱하고 .to_representation() 및 .to_internal_value() 메서드 중 하나 또는 둘 모두를 오버라이딩해야 합니다. 이 두 메서드는 초기 데이터 유형과 원시 직렬화 가능한 데이터 유형 간에 변환하는 데 사용됩니다. 원시 데이터 유형은 일반적으로 숫자, 문자열, 불리언, 날짜/시간/날짜 시간 또는 None입니다. 또한 다른 원시 객체만 포함된 리스트 또는 딕셔너리와 같은 객체도 될 수 있습니다. 사용 중인 렌더러에 따라 다른 유형이 지원될 수 있습니다.

.to_representation() 메서드는 초기 데이터 유형을 원시 직렬화 가능한 데이터 유형으로 변환하기 위해 호출됩니다.

.to_internal_value() 메서드는 원시 데이터 유형을 내부 파이썬 표현으로 복원하기 위해 호출됩니다. 이 메서드는 데이터가 유효하지 않은 경우 serializers.ValidationError를 발생시켜야 합니다.

예제

기본 사용자 정의 필드

RGB 색상 값을 나타내는 클래스를 직렬화하는 예제를 살펴보겠습니다:

class Color:
    """
    RGB 색공간에서 표현되는 색상.
    """
    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):
    """
    색상 객체는 'rgb(#, #, #)' 형식으로 직렬화됩니다.
    """
    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):
        # 필드 속성이 아닌 객체 인스턴스를 `to_representation`에 전달합니다.
        return instance

    def to_representation(self, value):
        """
        값의 클래스 이름을 직렬화합니다.
        """
        return value.__class__.__name__

유효성 검사 오류 발생시키기

위의 ColorField 클래스는 현재 데이터 유효성 검사를 수행하지 않습니다. 유효하지 않은 데이터를 표시하려면 serializers.ValidationError를 발생시켜야 합니다:

def to_internal_value(self, data):
    if not isinstance(data, str):
        msg = '잘못된 유형입니다. 문자열을 예상했지만 %s를 받았습니다.'
        raise ValidationError(msg % type(data).__name__)

    if not re.match(r'^rgb\([0-9]+,[0-9]+,[0-9]+\)$', data):
        raise ValidationError('잘못된 형식입니다. `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('범위를 초과했습니다. 0과 255 사이여야 합니다.')

    return Color(red, green, blue)

.fail() 메서드는 error_messages 사전에서 메시지 문자열을 받아 ValidationError를 발생시키기 위한 단축키입니다. 예를 들어:

default_error_messages = {
    'incorrect_type': '잘못된 유형입니다. 문자열을 예상했지만 {input_type}을(를) 받았습니다.',
    'incorrect_format': '잘못된 형식입니다. `rgb(#,#,#)`를 예상했습니다.',
    'out_of_range': '범위를 초과했습니다. 0과 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='*' 사용하기

여기서는 x_coordinate와 y_coordinate 속성을 가진 평면 DataPoint 모델의 예를 들어보겠습니다.

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 인스턴스를 포함하는 중첩 serializer로 처리하는 것이 더 나을 수 있습니다.

예제의 핵심 포인트는:

  • 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)])

유사한 방식으로 중첩 serializer 접근 방식을 사용하여 같은 작업을 수행해 보겠습니다:

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': ['유효한 정수가 필요합니다.'],
              'y': ['유효한 정수가 필요합니다.']})])

이러한 이유로 중첩 serializer 접근 방식을 우선적으로 시도하는 것이 좋습니다. 중첩 serializer가 불가능하거나 지나치게 복잡해질 경우 사용자 정의 필드 접근 방식을 사용합니다.

외부 패키지

다음은 사용 가능한 외부 패키지입니다.

  • DRF Compound Fields: drf-compound-fields 패키지는 "복합" serializer 필드를 제공하며, 이는 다른 필드로 설명될 수 있는 단순 값의 리스트 등을 포함합니다. 또한 유형이 지정된 딕셔너리와 특정 유형 또는 해당 유형의 항목 리스트가 될 수 있는 값을 위한 필드도 제공됩니다.

  • DRF Extra Fields: drf-extra-fields 패키지는 REST 프레임워크에 대한 추가 serializer 필드를 제공하며, 여기에는 Base64ImageField 및 PointField 클래스가 포함됩니다.

  • djangorestframework-recursive: djangorestframework-recursive 패키지는 재귀 구조를 직렬화 및 역직렬화하기 위한 RecursiveField를 제공합니다.

  • django-rest-framework-gis: django-rest-framework-gis 패키지는 GeometryField 필드 및 GeoJSON 직렬 변환기와 같은 django REST 프레임워크에 대한 지리적 추가 기능을 제공합니다.

  • django-rest-framework-hstore: django-rest-framework-hstore 패키지는 django-hstore DictionaryField 모델 필드를 지원하는 HStoreField를 제공합니다.

Reference

DRF API Guide - Serializer fields

profile
강민성
Back-end Junior Developer
이전 포스트

[DRF] Serializers

다음 포스트

[DRF] Serializer relations

0개의 댓글