우리의 예제 객체¶

사용자 지정 필드를 만들려면 세부 정보에 약간 주의를 기울여야 합니다. 이 문서에서는 Bridge_의 손에서 카드 거래를 나타내는 Python 개체를 감싸는 일관된 예를 보여드리겠습니다. 걱정하지 마세요, 이 예를 따르기 위해 브리지 게임을 하는 방법을 알 필요는 없어요. 52장의 카드가 전통적으로 north, east, south 및 *west*라고 불리는 네 명의 플레이어에 동일하게 배포된다는 것만 알면 됩니다. 저희 클래스는 다음과 같습니다.

class Hand:
    """A hand of cards (bridge style)"""

    def __init__(self, north, east, south, west):
        # Input parameters are lists of cards ('Ah', '9s', etc.)
        self.north = north
        self.east = east
        self.south = south
        self.west = west

    # ... (other possibly useful methods omitted) ...

이것은 Django 특유의 것이 없는 평범한 Python 클래스이다. 우리는 우리의 모델에서 이와 같은 것을 할 수 있기를 원한다(우리는 모델의 “hand” 속성은 “hand”의 예라고 가정한다.):

example = MyModel.objects.get(pk=1)
print(example.hand.north)

new_hand = Hand(north, east, south, west)
example.hand = new_hand
example.save()

“우리는 다른 파이썬 클래스처럼 우리 모델의 “손” 속성에 할당하고 이를 조회한다. 요령은 Django에게 그러한 객체를 저장하고 적재하는 방법을 알려주는 것이다.

모델에서 “Hand” 클래스를 사용하기 위해서는 이 클래스를 전혀 변경할 필요가 없다. 소스 코드를 변경할 수 없는 기존 클래스에 대한 모델 지원을 쉽게 작성할 수 있으므로 이상적입니다.

데이터베이스 저장¶

먼저 모델 필드부터 살펴보겠습니다. 이를 세분화하면 모델 필드는 문자열, 부울, “datetime” 또는 “hand”와 같은 일반적인 Python 개체를 가져와서 데이터베이스를 처리할 때 유용한 형식으로 변환하거나 변환하는 방법을 제공한다. (이러한 형식은 직렬화에도 유용하지만 나중에 볼 수 있듯이 데이터베이스를 제어하면 더 쉽습니다.)

모델의 필드는 기존 데이터베이스 열 유형에 맞게 변환되어야 합니다. 데이터베이스마다 서로 다른 유효한 열 유형 집합을 제공하지만 규칙은 여전히 동일합니다. 즉, 이러한 유형만 사용해야 합니다. 데이터베이스에 저장할 항목은 해당 유형 중 하나에 포함되어야 합니다.

일반적으로 특정 데이터베이스 열 유형과 일치하는 Django 필드를 작성하거나 데이터를 문자열로 변환하는 방법이 필요합니다.

우리의 “Hand” 예에서는 모든 카드를 미리 정해진 순서대로 연결함으로써 104자 문자열로 카드 데이터를 변환할 수 있습니다. 예를 들어 모든 북 카드, 그 다음 동, 남 및 서 카드). 따라서 “Hand” 개체를 데이터베이스의 텍스트 또는 문자 열에 저장할 수 있습니다.

필드클래스가 무엇을 하나요?¶

Django의 모든 필드(그리고 이 문서에서 *fields*라고 말할 때, 우리는 항상 모델 필드를 의미하며 :doc:’form fields’가 아님)는 :class:’django.db.models의 하위 클래스이다. Django가 필드에 대해 기록하는 대부분의 정보는 이름, 도움말 텍스트, 고유성 등 모든 필드에 공통적입니다. 그 모든 정보를 저장하는 일은 “Field`”가 담당한다. 우리는 “Field`”가 나중에 무엇을 할 수 있는지 자세히 알아볼 것이다. 현재로서는 모든 것이 “Field`”에서 비롯되었다고 말하고 나서 계급 행동의 핵심 부분을 맞춤화한다고만 말해도 충분하다.

Django 필드 클래스는 모델 속성에 저장된 클래스가 아닙니다. 모델 속성은 일반 Python 개체를 포함합니다. 사용자가 모델에 정의한 필드 클래스는 모델 클래스가 생성될 때 “메타” 클래스에 저장됩니다(여기서는 자세한 작업 내용이 중요하지 않음). 그 이유는 속성을 만들고 수정할 때는 필드 클래스가 필요하지 않기 때문입니다. 대신, 그들은 속성 값과 데이터베이스에 저장되거나 :doc:’serializer’로 전송되는 것 사이에서 변환하는 기계를 제공한다.

사용자 정의 필드를 작성할 때 이 점을 유념하십시오. 작성하는 Django “Field” 하위 클래스는 다양한 방법으로 Python 인스턴스와 데이터베이스/시리얼라이저 값을 변환하는 기계를 제공합니다(예를 들어 값을 저장하는 것과 룩업에 값을 사용하는 것 사이에는 차이점이 있음). 만약 이것이 좀 까다롭게 들린다면, 걱정하지 마세요. 아래의 예에서 더 명확해질 것입니다. 사용자 지정 필드를 원할 때 두 개의 클래스를 만드는 경우가 많습니다.

• 첫 번째 클래스는 사용자가 조작할 Python 개체입니다. 그들은 그것을 모델 속성에 할당하고, 그것을 보여주기 위해 읽게 될 것입니다. 이것이 우리의 예에서 볼 수 있는 “Hand” 클래스이다.

• 두 번째 클래스는 “Field” 하위 클래스다. 이 클래스는 퍼스트 클래스를 영구 스토리지 폼과 Python 폼 사이에서 앞뒤로 변환하는 방법을 알고 있는 클래스입니다.

필드 해체¶

당신의 “__init__()” 방식을 쓰는 것의 대척점은 :meth:”를 쓰는 것이다.Field.deconstruction’ 메서드입니다. 그것은 :doc:’model migration </topics/migrations>’에서 Django에게 당신의 새로운 필드의 예를 들어 그것을 직렬화된 형태로 줄이는 방법, 특히 그것을 재생성하기 위해 “_init_()”로 전달할 인수들을 말한다.

물려받은 분야 위에 별도의 옵션을 추가하지 않았다면 굳이 새로운 “`deconstruct()” 방식을 쓸 필요가 없다. 그러나 만일 당신이 “_init__()” (우리가 “HandField”에 있는 것처럼)로 전달된 주장을 바꾼다면, 당신은 통과되는 값을 보완할 필요가 있을 것이다.

deconstruct()" 는 4개의 아이템의 튜플을 반환합니다 :필드 속성 이름, 필드 클래스의 전체 가져오기 경로, 위치 인수(목록으로) 및 키워드 인수(dict로)가 있습니다. 이는 3개의 튜플을 반환하는 ``deconstruct() method :ref:` 과는 다릅니다.

사용자 지정 필드 작성자로서 기본 “Field” 클래스는 필드의 속성 이름과 가져오기 경로를 결정하는 모든 코드를 가지고 있기 때문에 앞의 두 값에 신경 쓸 필요가 없습니다. 그러나 위치 및 키워드 인수에 주의해야 합니다. 이러한 인수는 사용자가 변경하는 것일 수 있기 때문입니다.

예를 들어 우리의 “HandField” 클래스에서 우리는 항상 max_length를 “__init__()”로 강제적으로 설정한다. “Field” 클래스의 “deconstruct() “방식은 이것을 보고 키워드 논쟁에서 반환하려고 할 것이다. 따라서 우리는 이것을 가독성을 위한 키워드 논쟁에서 빼놓을 수 있다.

from django.db import models


class HandField(models.Field):
    def __init__(self, *args, **kwargs):
        kwargs["max_length"] = 104
        super().__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super().deconstruct()
        del kwargs["max_length"]
        return name, path, args, kwargs

새로운 키워드 논거를 추가하면 그 가치를 스스로 “kwags”에 넣는 “decorruction()”이라는 코드를 쓸 필요가 있다. 기본값이 사용되는 경우와 같이 필드 상태를 재구성할 필요가 없는 경우 “kwags”에서 값을 생략해야 한다.

from django.db import models


class CommaSepField(models.Field):
    "Implements comma-separated storage of lists"

    def __init__(self, separator=",", *args, **kwargs):
        self.separator = separator
        super().__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super().deconstruct()
        # Only include kwarg if it's not the default
        if self.separator != ",":
            kwargs["separator"] = self.separator
        return name, path, args, kwargs

좀 더 복잡한 예는 이 문서의 범위를 벗어나지만 기억하라. 즉, 필드 인스턴스의 구성에 대해서는 “`deconstruct()”가 해당 상태를 재구성하기 위해 “_init__”로 전달할 수 있는 인수를 반환해야 한다.

“Field” 슈퍼클래스의 인수에 대해 새로운 기본값을 설정하는 경우 특히 주의를 기울이십시오. 인수가 이전 기본값을 사용하는 경우 인수가 사라지더라도 항상 포함되도록 하려는 경우입니다.

또한 값을 위치 인수로 반환하지 않도록 하십시오. 가능한 경우 값을 키워드 인수로 반환하여 미래의 호환성을 최대화합니다. 생성자의 인수 목록에서 위치보다 항목의 이름을 더 자주 변경할 경우 위치 지정을 선호할 수 있지만 마이그레이션 기간(년)에 따라 사람들이 직렬화된 버전에서 사용자 필드를 오랫동안 재구성할 수 있습니다.

필드를 포함하는 마이그레이션을 확인하여 재구성 결과를 확인할 수 있으며, 필드를 재구성하고 재구성하여 단위 테스트에서 재구성을 테스트할 수 있습니다.

name, path, args, kwargs = my_field_instance.deconstruct()
new_instance = MyField(*args, **kwargs)
self.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)

데이터베이스 열 정의에 영향을 주지 않는 필드 속성¶

Field.non_db_attrs``를 재정의하여 열 정의에 영향을 미치지 않는 필드의 속성을 사용자 정의할 수 있습니다. no-op ``AlterField 작업을 감지하기 위해 모델 마이그레이션 중에 사용됩니다.

예시:

class CommaSepField(models.Field):
    @property
    def non_db_attrs(self):
        return super().non_db_attrs + ("separator",)

사용자 맞춤 정의 필드의 기본 클래스 변경¶

Django가 변경 내용을 검색하지 않고 해당 필드에 대해 마이그레이션을 수행하므로 사용자 정의 필드의 기본 클래스를 변경할 수 없습니다. 예를 들어, 다음 항목으로 시작하는 경우:

class CustomCharField(models.CharField): ...

대신 “TextField”를 사용하기로 결정하면 다음과 같이 하위 클래스를 변경할 수 없습니다.

class CustomCharField(models.TextField): ...

대신 새 사용자 지정 필드 클래스를 만들고 모델을 업데이트하여 참조해야 합니다.

class CustomCharField(models.CharField): ...


class CustomTextField(models.TextField): ...

“ref:’moving fields’에서 논했듯이, 당신은 그것을 참조하는 마이그레이션이 있는 한 원래의 “Custom CharField” 클래스를 보유해야 한다.

사용자 맞춤 정의 필드 문서화¶

사용자가 필드 유형을 알 수 있도록 항상 필드 유형을 문서화해야 합니다. 개발자에게 유용한 docstring을 제공할 뿐만 아니라 admin 앱의 사용자가 :doc:’django.contrib.admindocs’ 애플리케이션을 통해 필드 유형에 대한 간단한 설명을 볼 수 있도록 할 수 있습니다. 이렇게 하려면 사용자 정의 필드의 :attr:’~Field.description’ 클래스 속성에 설명 텍스트를 입력합니다. 위의 예에서 “핸드필드”를 신청하는 “애드민더스”가 보여주는 묘사는 카드의 손(브리지 스타일)이 될 것이다.

:mod:’django.contrib.admindocs’ 디스플레이에서 필드 설명은 “field”로 보간된다.__dict__’’는 필드 인수를 포함할 수 있는 설명입니다. 예를 들어 :class에 대한 설명:’~django.db.db.know.CharField’는 다음과 같다.

description = _("String (up to %(max_length)s)")

쓸모있는 메소드들¶

:class를 생성했으면:’~django.db.db.know.필드의 하위 클래스는 필드 동작에 따라 몇 가지 표준 방법을 재정의하는 것을 고려할 수 있습니다. 아래 방법 목록은 중요도가 대략적으로 감소하는 순서이므로 맨 위에서부터 시작하십시오.

from django.db import models


class MytypeField(models.Field):
    def db_type(self, connection):
        return "mytype"

class Person(models.Model):
    name = models.CharField(max_length=80)
    something_else = MytypeField()

class MyDateField(models.Field):
    def db_type(self, connection):
        if connection.vendor == "mysql":
            return "datetime"
        else:
            return "timestamp"

# This is a silly example of hard-coded parameters.
class CharMaxlength25Field(models.Field):
    def db_type(self, connection):
        return "char(25)"


# In the model:
class MyModel(models.Model):
    # ...
    my_field = CharMaxlength25Field()

# This is a much more flexible example.
class BetterCharField(models.Field):
    def __init__(self, max_length, *args, **kwargs):
        self.max_length = max_length
        super().__init__(*args, **kwargs)

    def db_type(self, connection):
        return "char(%s)" % self.max_length


# In the model:
class MyModel(models.Model):
    # ...
    my_field = BetterCharField(25)

# MySQL unsigned integer (range 0 to 4294967295).
class UnsignedAutoField(models.AutoField):
    def db_type(self, connection):
        return "integer UNSIGNED AUTO_INCREMENT"

    def rel_db_type(self, connection):
        return "integer UNSIGNED"

import re

from django.core.exceptions import ValidationError
from django.db import models
from django.utils.translation import gettext_lazy as _


def parse_hand(hand_string):
    """Takes a string of cards and splits into a full hand."""
    p1 = re.compile(".{26}")
    p2 = re.compile("..")
    args = [p2.findall(x) for x in p1.findall(hand_string)]
    if len(args) != 4:
        raise ValidationError(_("Invalid input for a Hand instance"))
    return Hand(*args)


class HandField(models.Field):
    # ...

    def from_db_value(self, value, expression, connection):
        if value is None:
            return value
        return parse_hand(value)

    def to_python(self, value):
        if isinstance(value, Hand):
            return value

        if value is None:
            return value

        return parse_hand(value)

class HandField(models.Field):
    # ...

    def get_prep_value(self, value):
        return "".join(
            ["".join(l) for l in (value.north, value.east, value.south, value.west)]
        )

def get_db_prep_value(self, value, connection, prepared=False):
    value = super().get_db_prep_value(value, connection, prepared)
    if value is not None:
        return connection.Database.Binary(value)
    return value

class HandField(models.Field):
    # ...

    def formfield(self, **kwargs):
        # Exclude the field from the ModelForm when some condition is met.
        some_condition = kwargs.get("some_condition", False)
        if some_condition:
            return None

        # Set up some defaults while letting the caller override them.
        defaults = {"form_class": MyFormField}
        defaults.update(kwargs)
        return super().formfield(**defaults)

class HandField(models.Field):
    # ...

    def get_internal_type(self):
        return "CharField"

class HandField(models.Field):
    # ...

    def value_to_string(self, obj):
        value = self.value_from_object(obj)
        return self.get_prep_value(value)

일반적인 조언¶

특히 Python 유형과 데이터베이스 및 직렬화 형식 간에 복잡한 변환을 수행하는 경우에는 사용자 지정 필드를 작성하는 작업이 까다로울 수 있습니다. 다음은 작업을 보다 원활하게 진행할 수 있도록 하는 몇 가지 팁입니다.

1. Look at the existing Django fields (in django/db/models/fields/__init__.py) for inspiration. Try to find a field that’s similar to what you want and extend it a little bit, instead of creating an entirely new field from scratch.

2. 필드로 마무리하는 수업에 “__str__()” 방식을 적용합니다. 필드 코드의 기본 동작은 값에 대해 “str()”라고 부르는 경우가 많다. (이 문서의 예에서 “가치”는 “핸드필드”가 아니라 “손”의 예일 것이다. 그래서 만약 당신의 “_str__()” 방법이 당신의 파이썬 객체의 문자열 형태로 자동 변환된다면, 당신은 많은 작업을 절약할 수 있다.

몇 가지 제안들¶

위의 세부 사항 외에도 필드 코드의 효율성과 가독성을 크게 개선할 수 있는 몇 가지 지침이 있습니다.

1. The source for Django’s own ImageField (in django/db/models/fields/files.py) is a great example of how to subclass FileField to support a particular type of file, as it incorporates all of the techniques described above.

2. 가능한 경우 파일 특성을 캐시합니다. 파일을 원격 스토리지 시스템에 저장할 수 있기 때문에 파일을 검색하는 데 추가 시간 또는 비용이 소요될 수 있습니다. 항상 필요한 것은 아닙니다. 파일이 검색되어 콘텐츠에 대한 데이터를 얻으면 해당 데이터를 가능한 많이 캐슁하여 이후 해당 정보를 호출할 때 파일을 검색해야 하는 횟수를 줄이십시오.