モデルリファレンス ドキュメントでは、Djangoの標準フィールドクラスである、 CharField や、 DateField などの使い方を説明しています。多くの場合、これらのクラスがあれば十分です。ただし、Djangoのバージョンが正確な要件を満たしていない場合や、Djangoに同梱されているものとはまったく異なるフィールドを使用したい場合があります。
Django の組み込みフィールド型は、データベースで利用可能な全てのカラム型をカバーしているわけではなく、 VARCHAR や INTEGER のような一般的な型のみに対応しています。地理的な多角形や PostgreSQL カスタム型 のようなユーザが作成した型など、より曖昧なカラム型については、独自の Django Field サブクラスを定義することができます。
あるいは、複雑な Python オブジェクトを、標準的なデータベースのカラム型に合うようにシリアライズすることもできます。これもまた、Field サブクラスがオブジェクトをモデルで使用するのに役立つケースです。
カスタムフィールドを作成するには、細部に少し注意する必要があります。わかりやすくなるように、このドキュメントでは「ブリッジ Bridge の手札のやり取りを表すPythonオブジェクトの実装」を一貫した例として説明することにします。なお、この実装例を理解するために、ブリッジのプレイルールを理解する必要はありません。52枚のカードが、伝統的に 北 、 東 、 南 および 西 と呼ばれる4人のプレイヤーに均等に配られることだけを覚えておいてください。クラスは以下のように実装します:
\nclass Hand:\n """A hand of cards (bridge style)"""\n\n def __init__(self, north, east, south, west):\n # Input parameters are lists of cards ('Ah', '9s', etc.)\n self.north = north\n self.east = east\n self.south = south\n self.west = west\n\n # ... (other possibly useful methods omitted) ...\nこれはDjangoの仕様を使っていない、普通のPythonクラスです。モデルでこれと同じようなことを実行できるようにしたいと思います（モデルの中の hand 属性は Hand インスタンスだと想定しています）
example = MyModel.objects.get(pk=1)\nprint(example.hand.north)\n\nnew_hand = Hand(north, east, south, west)\nexample.hand = new_hand\nexample.save()\n他のPythonクラスと同様に、モデルの hand 属性に割り当てたり、そこから取得したりします。コツは、そのようなオブジェクトの保存と読み込みの処理方法をDjangoに伝えることです。
モデルで Hand クラスを使用するために、このクラスを変更する必要はありません。 これは、ソースコードを変更できない既存のクラスのモデルサポートを簡単に記述できるため、理想的です。
モデルフィールドから始めましょう。分解すると、モデルフィールドは通常のPythonオブジェクト（文字列、ブール値、 datetime 、あるいは Hand のような複雑なもの）を、データベースを扱うときに便利な形式に変換する方法を提供します。(このような形式はシリアライズの際にも便利ですが、後で説明するように、データベース側を制御できるようになれば、その方が簡単です)。
モデルのフィールドは、既存のデータベースのカラムの型に適合するように何らかの方法で変換されなければなりません。データベースによって有効なカラム型のセットは異なりますが、利用できる型が決まっているという決まりは同じです。データベースに保存したいものはすべて、これらの型のいずれかに適合しなければなりません。
\n通常、特定のデータベースの列タイプに一致するようにDjangoフィールドを作成するか、データを文字列などに変換する方法が必要になります。
\nHand の例では、すべてのカードをあらかじめ決められた順序で連結することで、カードデータを104文字の文字列に変換できます。たとえば、すべての 北 カード、次に 東 、 南 および 西 カードです。 したがって、Hand オブジェクトをデータベースのテキストまたは文字列に保存できます。
Djangoのすべてのフィールド（およびこのドキュメントで フィールド (Field) と言うときは、常に フォームフィールド ではなくモデルフィールドを意味します）は django.db.models.Field のサブクラスです。 Django がフィールドについて記録する情報のほとんどは、名前、ヘルプテキスト、一意性など、すべてのフィールドに共通です。すべての情報の保存は Field によって処理されます。Field ができることの詳細については、後で詳しく説明します。とりあえず、すべてが Field から派生し、クラスの動作の重要な部分をカスタマイズすると言うだけで十分です。
Djangoフィールドクラスは、モデル属性に格納されているものではないことを理解することが重要です。 モデル属性には通常のPythonオブジェクトが含まれます。 モデルで定義するフィールドクラスは、モデルクラスが作成されるときに実際に Meta クラスに保存されます（これを行う方法の正確な詳細はここでは重要ではありません）。 これは、属性を作成および変更するだけの場合、フィールドクラスは必要ないためです。 代わりに、属性値とデータベースに保存されているもの、または シリアライザ に送信されるものとの間で変換するための機構を提供します。
独自のカスタムフィールドを作成する場合は、このことに留意してください。 作成するDjangoの Field サブクラスは、Pythonインスタンスとデータベース/シリアライザーの値をさまざまな方法で変換するための機構を提供します（たとえば、値の保存とルックアップでの値の使用には違いがあります）。 これが少しトリッキーに聞こえる場合でも、心配しないでください。以下の例で明らかになります。 カスタムフィールドが必要な場合、しばしば2つのクラスを作成することになります:
最初のクラスは、ユーザーが操作するPythonオブジェクトです。彼らはそれをモデル属性に割り当て、そのようなものを表示するためにそれから読み込みます。これは、この例の Hand クラスです。
2番目のクラスは Field サブクラスです。これは、最初のクラスを永続ストレージ形式とPython形式の間で変換する方法を知っているクラスです。
Field のサブクラス化を考える前に、まず、新しいフィールドが、既存のどの Field クラスに最も似ているかを考えてください。既存の Django フィールドをサブクラス化して、手間を省くことはできませんか？そうでなければ、すべてのフィールドの基底となる、 Field クラスをサブクラス化すべきです。
新しいフィールドの初期化は、ケース固有の引数を共通の引数から分離し、後者を Field の __init__() メソッドに渡すことです。 （または親クラスに対して）。
この例では、フィールドを HandField と呼ぶことにします。（ Field サブクラス <Something>Field と名付けることをオススメします。 Field サブクラスであることが簡単にわかるためです）\n既存のフィールドのようには動作しないため、この例では Field から直接サブクラス化しています。
from django.db import models\n\n\nclass HandField(models.Field):\n description = "A hand of cards (bridge style)"\n\n def __init__(self, *args, **kwargs):\n kwargs["max_length"] = 104\n super().__init__(*args, **kwargs)\n私たちの HandField は、ほとんどの標準フィールドオプションを受け入れます（以下のリストを参照してください）。しかし、52枚のカードの値とそれらのスート（マーク）を保持するだけで十分なため、固定長を持つようにします。合計で104文字です。
Field.__init__() メソッドは以下のパラメーターを取ります:
name
rel: 関連フィールドに使用される (ForeignKey など)。上級者向けです。
serialize: False の場合、Django の シリアライザ にモデルが渡されたときに、フィールドをシリアライズしません。デフォルトの値は True です。
もしバックエンドが テーブル空間 (tablespace) をサポートする場合、db_tablespace: はインデックスの作成のみ行います。通常、このオプションは無視できます。
モデル継承で使用される OneToOneField のように、フィールドが自動的に作成された場合は、auto_created は True です。 高度な使用向けです。
上記のリストに説明のないオプションはすべて、通常のDjangoフィールドと同じ意味を持ちます。例と詳細については、 フィールドのドキュメント を参照してください。
\n__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\n\n\nclass HandField(models.Field):\n def __init__(self, *args, **kwargs):\n kwargs["max_length"] = 104\n super().__init__(*args, **kwargs)\n\n def deconstruct(self):\n name, path, args, kwargs = super().deconstruct()\n del kwargs["max_length"]\n return name, path, args, kwargs\n新しいキーワード引数を追加する場合、自分で kwargs に値を設定する deconstruct() でコードを記述する必要があります。 また、デフォルト値が使用されている場合など、フィールドの状態を再構築する必要がない場合は、kwargs から値を省略してください:
from django.db import models\n\n\nclass CommaSepField(models.Field):\n "Implements comma-separated storage of lists"\n\n def __init__(self, separator=",", *args, **kwargs):\n self.separator = separator\n super().__init__(*args, **kwargs)\n\n def deconstruct(self):\n name, path, args, kwargs = super().deconstruct()\n # Only include kwarg if it's not the default\n if self.separator != ",":\n kwargs["separator"] = self.separator\n return name, path, args, kwargs\nより複雑な例はこのドキュメントの範囲外ですが、これだけは覚えておいてください - deconstruct() は、フィールドインスタンスのどのような設定に対しても、その状態を再構築するために __init__ に渡す引数を返さなければなりません。
Field スーパークラス内の引数に新しいデフォルト値を設定する場合には、特に注意してください。古いデフォルト値を使うと消えるようにするのではなく、デフォルト値が常に含まれるようにしてください。
また、値を位置引数として返さないようにしてください。 可能な限り、将来の互換性を最大限にするために、キーワード引数として値を返してください。コンストラクタの引数リストにおける位置よりも、頻繁に引数の名前を変更する場合、位置引数で指定しがちになるかもしれません。しかし、利用者はかなり長期間（おそらく何年も）にわたって、シリアライズされたバージョンからフィールドを再構築することに注意してください。これはバージョンのライフサイクルの長さにも依存します。
\nフィールドを含む移行を調べることで分解の結果を確認できます。フィールドを分解して再構築することで、単体テストで分解をテストできます:
\nname, path, args, kwargs = my_field_instance.deconstruct()\nnew_instance = MyField(*args, **kwargs)\nself.assertEqual(my_field_instance.some_attribute, new_instance.some_attribute)\nField.non_db_attrs をオーバーライドすることで、カラム定義に影響しないフィールドの属性をカスタマイズできます。これはモデルのマイグレーションの間に使われ、no-opの AlterField 操作を検出します。
例えば:
\nclass CommaSepField(models.Field):\n @property\n def non_db_attrs(self):\n return super().non_db_attrs + ("separator",)\nカスタムフィールドの基底クラスを変更することはできません。なぜなら、 Django はその変更を検知できず、マイグレーションも行わないからです。例えば次のように書き始めたとして、:
\nclass CustomCharField(models.CharField): ...\nそして、代わりに TextField を使用することに決めた場合、サブクラスを次のように変更することはできません:
class CustomCharField(models.TextField): ...\n代わりに、新しいカスタムフィールドクラスを作成し、モデルを更新してそれを参照する必要があります:
\nclass CustomCharField(models.CharField): ...\n\n\nclass CustomTextField(models.TextField): ...\nフィールドを削除する で説明したように、それを参照するマイグレーションがある限り、元の 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)")\nField サブクラスを作成したら、フィールドの動作に応じて、いくつかの標準メソッドをオーバーライドすることを検討できます。以下のメソッドのリストは、おおよそ重要度の高いものから順に並んでいるので、上から始めてください。
mytype というPostgreSQLのカスタム型を作成したとします。このとき、 Field をサブクラス化し、 db_type() 関数を以下のように実装できます:
from django.db import models\n\n\nclass MytypeField(models.Field):\n def db_type(self, connection):\n return "mytype"\nMytypeField を取得したら、他の Field タイプと同様に、どのモデルでも使用できます:
class Person(models.Model):\n name = models.CharField(max_length=80)\n something_else = MytypeField()\nデータベースに依存しないアプリケーションを構築することを目指している場合、データベースカラムの型の違いを考慮する必要があります。たとえば、PostgreSQL の日付や時刻のカラムの型は timestamp と呼ばれますが、同じカラムが MySQL では datetime と呼ばれます。この違いは db_type() メソッド内で connection.vendor 属性をチェックすることでハンドリングできます。現在のビルトインされているベンダー名は、sqlite、postgresql、mysql、oracle です。
例えば:
\nclass MyDateField(models.Field):\n def db_type(self, connection):\n if connection.vendor == "mysql":\n return "datetime"\n else:\n return "timestamp"\nDjango は、アプリケーションのために CREATE TABLE ステートメントを構築するとき、つまり最初にテーブルを作成するときに db_type() と rel_db_type() メソッドを呼びます。このメソッドは、モデルのフィールドを含む WHERE 句を構築するとき、つまり QuerySet の get()、filter()、exclude() などのメソッドを使用してデータを取得するときにも呼ばれます。
一部のデータベースカラムの型は CHAR(25) などのパラメータを受け付けます。ここで、パラメータ 25 はカラムの最大長を表します。このような場合、パラメータを db_type() メソッド内でハードコードするよりも、モデル内で指定したほうがより柔軟になります。たとえば、ここで示すように、CharMaxlength25Field のようなフィールドを持つ意味はあまりありません。
# This is a silly example of hard-coded parameters.\nclass CharMaxlength25Field(models.Field):\n def db_type(self, connection):\n return "char(25)"\n\n\n# In the model:\nclass MyModel(models.Model):\n # ...\n my_field = CharMaxlength25Field()\nこれを行うためのよりよい方法は、実行時に、つまりクラスがインスタンス化されるときにパラメータを指定できるようにする方法です。そのためには、次のように Field.__init__() を実装します。
# This is a much more flexible example.\nclass BetterCharField(models.Field):\n def __init__(self, max_length, *args, **kwargs):\n self.max_length = max_length\n super().__init__(*args, **kwargs)\n\n def db_type(self, connection):\n return "char(%s)" % self.max_length\n\n\n# In the model:\nclass MyModel(models.Model):\n # ...\n my_field = BetterCharField(25)\n最後に、カラムが本当に複雑な SQL のセットアップを必要とする場合、db_type() から None を返してください。こうすると、Django の SQL 生成コードがこのフィールドをスキップするようになります。その後、別の方法で正しいテーブルにカラムを作成すする必要がありますが、Django に邪魔をしないように伝えることができます。
rel_db_type() メソッドは、他のフィールドを指す ForeignKey や OneToOneField などのフィールドによって、データベースのカラムのデータ型を特定するために呼ばれます。たとえば、UnsignedAutoField がある場合、同じデータ型を使うためにそのフィールドを指す外部キーも必要になります。
# MySQL unsigned integer (range 0 to 4294967295).\nclass UnsignedAutoField(models.AutoField):\n def db_type(self, connection):\n return "integer UNSIGNED AUTO_INCREMENT"\n\n def rel_db_type(self, connection):\n return "integer UNSIGNED"\nもしカスタムの Field クラスが文字列、日付、整数、または浮動小数点数よりも複雑なデータ構造を扱う場合は、 from_db_value() と to_python() をオーバーライドする必要があるかもしれません。
フィールドのサブクラスに存在する場合、データがデータベースから読み込まれるすべての状況で、 from_db_value() が呼び出されます。これには集計や values() の呼び出しも含まれます。
to_python() は、デシリアライズ時やフォームから使用される clean() メソッドの中で呼び出されます。
一般的なルールとして、 to_python() は以下の引数を適切に処理するべきです。
正しいタイプのインスタンス（例：このページの例でいう Hand ）。
文字列
None (フィールドが null=True を許す場合)
私たちの HandField クラスでは、データをデータベースの VARCHAR フィールドとして保存しているため、 from_db_value() で文字列と None を処理できる必要があります。 to_python() では、 Hand のインスタンスも処理する必要があります。
import re\n\nfrom django.core.exceptions import ValidationError\nfrom django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\ndef parse_hand(hand_string):\n """Takes a string of cards and splits into a full hand."""\n p1 = re.compile(".{26}")\n p2 = re.compile("..")\n args = [p2.findall(x) for x in p1.findall(hand_string)]\n if len(args) != 4:\n raise ValidationError(_("Invalid input for a Hand instance"))\n return Hand(*args)\n\n\nclass HandField(models.Field):\n # ...\n\n def from_db_value(self, value, expression, connection):\n if value is None:\n return value\n return parse_hand(value)\n\n def to_python(self, value):\n if isinstance(value, Hand):\n return value\n\n if value is None:\n return value\n\n return parse_hand(value)\nこれらのメソッドからは常に Hand インスタンスが返されることに注意してください。これは、モデルの属性に保存したいPythonオブジェクトの型です。
to_python() において、値の変換中に何か問題が発生した場合は、 ValidationError 例外を発生させる必要があります。
データベースを使用するには両方の変換が必要なので、 from_db_value() をオーバーライドする場合は、 get_prep_value() もオーバーライドして Python オブジェクトをクエリの値に戻す必要があります。
例えば:
\nclass HandField(models.Field):\n # ...\n\n def get_prep_value(self, value):\n return "".join(\n ["".join(l) for l in (value.north, value.east, value.south, value.west)]\n )\nいくつかのデータ型(例えば、日付)はデータベースのバックエンドで使用する前に特定の形式にする必要があります。 get_db_prep_value() はこれらの変換を行うメソッドです。クエリに使用される特定の接続は connection パラメータとして渡されます。これにより、必要に応じてバックエンド固有の変換ロジックを使用できます。
例えば、Django は BinaryField で以下のメソッドを使います:
def get_db_prep_value(self, value, connection, prepared=False):\n value = super().get_db_prep_value(value, connection, prepared)\n if value is not None:\n return connection.Database.Binary(value)\n return value\nカスタムフィールドを保存する際に、通常のクエリパラメータで使われる変換とは別の特別な変換が必要な場合、 get_db_prep_save() をオーバーライドできます。
保存する直前に値を前処理したい場合は pre_save() を使います。例えば、 Django の DateTimeField はこのメソッドを使って、 auto_now や auto_now_add に正しく属性を設定します。
もしこのメソッドをオーバーライドするならば、最後にその属性の値を返す必要があります。さらに、もしその値になんらかの変更を加えたならば、そのモデルへの参照を含んでいるコードが常に正しい値を指すように、モデルの属性を更新しなくてはなりません。
\nModelForm で使用するフォームフィールドをカスタマイズするには、 formfield() をオーバーライドします。
フォームフィールドのクラスは form_class と choices_form_class 引数で指定できます。これらの引数を指定しなければ、 CharField または TypedChoiceField が使用されます。
すべての kwargs 辞書は、フォームフィールドの __init__() メソッドに直接渡されます。通常、 form_class ( または choices_form_class ) 引数に適切なデフォルト値を設定し、それ以降の処理を親クラスに委譲するだけです。そのためには、カスタムフォームフィールド (そしてフォームウィジェット) を書く必要があるかもしれません。これについては フォームのドキュメント を参照してください。
上の例に続き、 formfield() メソッドは次のように書けます:
class HandField(models.Field):\n # ...\n\n def formfield(self, **kwargs):\n # This is a fairly standard way to set up some defaults\n # while letting the caller override them.\n defaults = {"form_class": MyFormField}\n defaults.update(kwargs)\n return super().formfield(**defaults)\nこれは MyFormField フィールドクラス (デフォルトのウィジェットを持ちます) のインポートを想定しています。このドキュメントでは、カスタムフォームフィールドの書き方の詳細は説明しません。
もし db_type() メソッドを作成したのなら、 get_internal_type() はあまり使わないので気にしなくても大丈夫です。しかし、データベースストレージの型は他のフィールドと似ていることがあるので、正しいカラムを作成するために他のフィールドのロジックを使うこともできます。
例えば:
\nclass HandField(models.Field):\n # ...\n\n def get_internal_type(self):\n return "CharField"\nどのデータベースのバックエンドを使用していても、migrate やその他のSQLコマンドは文字列を格納するための正しいカラムタイプを作成します。
もし get_internal_type() が、使用しているデータベースのバックエンドで Django が知らない文字列 (つまり、django.db.backends.<db_name>.base.DatabaseWrapper.data_types にない文字列) を返した場合、シリアライザはその文字列を使用しますが、デフォルトの db_type() メソッドは None を返します。これが便利な理由は db_type() のドキュメントを参照してください。シリアライザのフィールドの型として説明的な文字列を入れるのは、シリアライザの出力を Django 以外の他の場所で使う場合に便利なアイデアです。
シリアライザによる値のシリアライズ方法をカスタマイズするには、 value_to_string() をオーバーライドします。 value_from_object() を使うのは、シリアライズの前にフィールドの値を取得する最も良い方法です。例えば、 HandField はデータの保存に文字列を使うので、既存の変換コードを再利用できます:
class HandField(models.Field):\n # ...\n\n def value_to_string(self, obj):\n value = self.value_from_object(obj)\n return self.get_prep_value(value)\nカスタムフィールドの作成は、特に Python の型とデータベースやシリアライズのフォーマットとの間で複雑な変換を行う場合、厄介なプロセスになることがあります。ここでは、スムーズに進めるためのヒントをいくつか紹介します:
\n既存の Django フィールド ( django/db/models/fields/__init__.py にあります) を見て、着想を得てください。ゼロから全く新しいフィールドを作るのではなく、あなたの欲しいものに似たフィールドを見つけ、それを少し拡張してみてください。
フィールドとしてラップしているクラスに __str__() メソッドを追加します。フィールドのコードのデフォルトの動作として、値に対して str() を呼び出す箇所が多くあります。(このドキュメントの例では、 value は HandField ではなく Hand インスタンスになります）。そのため、 __str__() メソッドが自動的に Python オブジェクトの文字列形式に変換してくれれば、多くの手間を省けます。
FileField サブクラスを書くLink to this heading#上記のメソッドに加えて、ファイルを扱うフィールドには考慮すべき特別な要件がいくつかあります。 FileField によって提供される仕組みの大部分、例えばデータベースの保存と取得の制御などは、変更することなく、サブクラスに特定のタイプのファイルをサポートさせることができます。
Django は File クラスを提供し、ファイルの内容や操作のプロキシとして使われます。これをサブクラス化することで、ファイルへのアクセス方法や利用可能なメソッドをカスタマイズできます。このクラスは django.db.models.fields.files にあり、デフォルトの動作は ファイルのドキュメント で解説しています。
一度 File のサブクラスが作成されると、新しい FileField サブクラスにはそれを使用するように指示する必要があります。そのためには、新しい File サブクラスを FileField サブクラスの特別な attr_class 属性に割り当てます。
上記の詳細に加えて、フィールドのコードの効率と読みやすさを劇的に改善するいくつかのガイドラインがあります。
\nDjango 独自の ImageField のソース ( django/db/models/fields/files.py ) は、上で説明したテクニックを全て組み込んでいるので、特定のファイルタイプをサポートするために FileField をサブクラス化する方法の良い例です。
できるだけファイル属性をキャッシュします。ファイルはリモートのストレージシステムに保存されている可能性があるため、それらを取得するには、必ずしも必要ではない余分な時間やコストがかかる可能性があります。一度ファイルを検索してその内容に関するデータを取得したら、そのデータをできるだけ多くキャッシュして、その情報を取得するために以後ファイルを検索する回数を減らします。