私たちのサンプルオブジェクト¶

カスタムフィールドを作成するには、細部に少し注意する必要があります。わかりやすくなるように、このドキュメントでは「ブリッジ Bridge の手札のやり取りを表すPythonオブジェクトの実装」を一貫した例として説明することにします。なお、この実装例を理解するために、ブリッジのプレイルールを理解する必要はありません。52枚のカードが、伝統的に 北 、 東 、 南 および 西 と呼ばれる4人のプレイヤーに均等に配られることだけを覚えておいてください。クラスは以下のように実装します:

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()

他のPythonクラスと同様に、モデルの hand 属性に割り当てたり、そこから取得したりします。コツは、そのようなオブジェクトの保存と読み込みの処理方法をDjangoに伝えることです。

モデルで Hand クラスを使用するために、このクラスを変更する必要はありません。 これは、ソースコードを変更できない既存のクラスのモデルサポートを簡単に記述できるため、理想的です。

データベースストレージ¶

モデルフィールドから始めましょう。分解すると、モデルフィールドは通常のPythonオブジェクト（文字列、ブール値、 datetime 、あるいは Hand のような複雑なもの）を、データベースを扱うときに便利な形式に変換する方法を提供します。(このような形式はシリアライズの際にも便利ですが、後で説明するように、データベース側を制御できるようになれば、その方が簡単です)。

モデルのフィールドは、既存のデータベースのカラムの型に適合するように何らかの方法で変換されなければなりません。データベースによって有効なカラム型のセットは異なりますが、利用できる型が決まっているという決まりは同じです。データベースに保存したいものはすべて、これらの型のいずれかに適合しなければなりません。

通常、特定のデータベースの列タイプに一致するようにDjangoフィールドを作成するか、データを文字列などに変換する方法が必要になります。

Hand の例では、すべてのカードをあらかじめ決められた順序で連結することで、カードデータを104文字の文字列に変換できます。たとえば、すべての 北 カード、次に 東 、 南 および 西 カードです。 したがって、Hand オブジェクトをデータベースのテキストまたは文字列に保存できます。

フィールドクラスが行うこと¶

Djangoのすべてのフィールド（およびこのドキュメントで フィールド (Field) と言うときは、常に フォームフィールド ではなくモデルフィールドを意味します）は django.db.models.Field のサブクラスです。 Django がフィールドについて記録する情報のほとんどは、名前、ヘルプテキスト、一意性など、すべてのフィールドに共通です。すべての情報の保存は Field によって処理されます。Field ができることの詳細については、後で詳しく説明します。とりあえず、すべてが Field から派生し、クラスの動作の重要な部分をカスタマイズすると言うだけで十分です。

Djangoフィールドクラスは、モデル属性に格納されているものではないことを理解することが重要です。 モデル属性には通常のPythonオブジェクトが含まれます。 モデルで定義するフィールドクラスは、モデルクラスが作成されるときに実際に Meta クラスに保存されます（これを行う方法の正確な詳細はここでは重要ではありません）。 これは、属性を作成および変更するだけの場合、フィールドクラスは必要ないためです。 代わりに、属性値とデータベースに保存されているもの、または シリアライザ に送信されるものとの間で変換するための機構を提供します。

独自のカスタムフィールドを作成する場合は、このことに留意してください。 作成するDjangoの Field サブクラスは、Pythonインスタンスとデータベース/シリアライザーの値をさまざまな方法で変換するための機構を提供します（たとえば、値の保存とルックアップでの値の使用には違いがあります）。 これが少しトリッキーに聞こえる場合でも、心配しないでください。以下の例で明らかになります。 カスタムフィールドが必要な場合、しばしば2つのクラスを作成することになります:

• 最初のクラスは、ユーザーが操作するPythonオブジェクトです。彼らはそれをモデル属性に割り当て、そのようなものを表示するためにそれから読み込みます。これは、この例の Hand クラスです。

• 2番目のクラスは Field サブクラスです。これは、最初のクラスを永続ストレージ形式とPython形式の間で変換する方法を知っているクラスです。

フィールドの解体¶

__init__() メソッドとは対照的なものとして、 deconstruct() メソッドがあります。これは モデルのマイグレーション 中に使用されるもので、新しいフィールドのインスタンスを取得する方法、インスタンスをどのようにシリアライズして減らすかの方法をDjangoに指示します。特に、インスタンスを再生成するためにどの引数を __init__() に渡すかを指示します。

継承元のフィールドの上に追加のオプションを追加していない場合、新しい deconstruct() メソッドを記述する必要はありません。 ただし、__init__() で渡される引数を変更する場合（HandField のように）、渡される値を補足する必要があります。

deconstruct() 関数は4要素のタプルを返します。それは、フィールドの属性、インポートするフィールドクラスのフルパス、位置引数（リスト型）、キーワード引数（辞書型）です。この関数は deconstruct() メソッドとは異なることに注意してください。 deconstruct() メソッドは カスタムクラスのためのもの で、3要素のタプルを返します。

カスタムフィールドの作成者は、最初の2つの値を気にする必要はありません。 ベース Field クラスには、フィールドの属性名とインポートパスを計算するためのすべてのコードがあります。 ただし、位置引数とキーワード引数は、変更する可能性が高いため、注意する必要があります。

たとえば、 HandField クラスでは、常に __init__() でmax_lengthを強制的に設定しています。 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

新しいキーワード引数を追加する場合、自分で kwargs に値を設定する deconstruct() でコードを記述する必要があります。 また、デフォルト値が使用されている場合など、フィールドの状態を再構築する必要がない場合は、kwargs から値を省略してください:

from django.db import models


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

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

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

より複雑な例はこのドキュメントの範囲外ですが、これだけは覚えておいてください – 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): ...

フィールドを削除する で説明したように、それを参照するマイグレーションがある限り、元の CustomCharField クラスを保持する必要があります。

カスタムフィールドのドキュメントを書く¶

いつものように、フィールドタイプのドキュメントを作成し、それがどんなものかをユーザがわかるようにしましょう。開発者にとって便利な docstring を提供するだけでなく、 django.contrib.admindocs アプリケーションを通して、管理者アプリのユーザにフィールドタイプの短い説明を表示することもできます。これを行うには、カスタムフィールドの description クラス属性に説明文を記述します。上記の例では、 admindocs アプリケーションが表示する HandField の説明は ‘A hand of cards (bridge style)’ （日本語で「手札(ブリッジスタイル)」の意）となります。

django.contrib.admindocs の表示では、フィールドの説明は field.__dict__ によって補完され、説明文にフィールドの引数を組み込むことができます。例えば、 CharField の説明は次のようになります:

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

便利なメソッド¶

Field サブクラスを作成したら、フィールドの動作に応じて、いくつかの標準メソッドをオーバーライドすることを検討できます。以下のメソッドのリストは、おおよそ重要度の高いものから順に並んでいるので、上から始めてください。

from django.db import models


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

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

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

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


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

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

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


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

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

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

import re

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


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


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

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

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

        if value is None:
            return value

        return parse_hand(value)

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

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

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

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

    def formfield(self, **kwargs):
        # 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. 既存の Django フィールド ( django/db/models/fields/__init__.py にあります) を見て、着想を得てください。ゼロから全く新しいフィールドを作るのではなく、あなたの欲しいものに似たフィールドを見つけ、それを少し拡張してみてください。

2. フィールドとしてラップしているクラスに __str__() メソッドを追加します。フィールドのコードのデフォルトの動作として、値に対して str() を呼び出す箇所が多くあります。(このドキュメントの例では、 value は HandField ではなく Hand インスタンスになります）。そのため、 __str__() メソッドが自動的に Python オブジェクトの文字列形式に変換してくれれば、多くの手間を省けます。

いくつかの提案¶

上記の詳細に加えて、フィールドのコードの効率と読みやすさを劇的に改善するいくつかのガイドラインがあります。

1. Django 独自の ImageField のソース ( django/db/models/fields/files.py ) は、上で説明したテクニックを全て組み込んでいるので、特定のファイルタイプをサポートするために FileField をサブクラス化する方法の良い例です。

2. できるだけファイル属性をキャッシュします。ファイルはリモートのストレージシステムに保存されている可能性があるため、それらを取得するには、必ずしも必要ではない余分な時間やコストがかかる可能性があります。一度ファイルを検索してその内容に関するデータを取得したら、そのデータをできるだけ多くキャッシュして、その情報を取得するために以後ファイルを検索する回数を減らします。