モデルリファレンス ドキュメントでは、Djangoの標準フィールドクラスである、 CharField や、 DateField などの使い方を説明しています。多くの場合、これらのクラスがあれば十分です。ただし、Djangoのバージョンが正確な要件を満たしていない場合や、Djangoに同梱されているものとはまったく異なるフィールドを使用したい場合があります。
Django の組み込みフィールド型は、データベースで利用可能な全てのカラム型をカバーしているわけではなく、 VARCHAR や INTEGER のような一般的な型のみに対応しています。地理的な多角形や PostgreSQL カスタム型 のようなユーザが作成した型など、より曖昧なカラム型については、独自の Django Field サブクラスを定義することができます。
あるいは、複雑な Python オブジェクトを、標準的なデータベースのカラム型に合うようにシリアライズすることもできます。これもまた、Field サブクラスがオブジェクトをモデルで使用するのに役立つケースです。
カスタムフィールドを作成するには、細部に少し注意する必要があります。わかりやすくなるように、このドキュメントでは「ブリッジの手札のやり取りを表す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のすべてのフィールド（およびこのドキュメントで fields と言うときは、常に form fields ではなくモデルフィールドを意味します）は django.db.models.Field のサブクラスです。 Djangoがフィールドについて記録する情報のほとんどは、名前、ヘルプテキスト、一意性など、すべてのフィールドに共通です。 すべての情報を保存することは Field によって処理されます。 Field ができることの詳細については、後で詳しく説明します。 とりあえず、すべてが Field から派生し、クラスの動作の重要な部分をカスタマイズすると言うだけで十分です。
Djangoフィールドクラスは、モデル属性に格納されているものではないことを理解することが重要です。 モデル属性には通常のPythonオブジェクトが含まれます。 モデルで定義するフィールドクラスは、モデルクラスが作成されるときに実際に Meta クラスに保存されます（これを行う方法の正確な詳細はここでは重要ではありません）。 これは、属性を作成および変更するだけの場合、フィールドクラスは必要ないためです。 代わりに、属性値とデータベースに保存されているもの、または serializer に送信されるものとの間で変換するための機構を提供します。
独自のカスタムフィールドを作成する場合は、このことに留意してください。 作成するDjangoの Field サブクラスは、Pythonインスタンスとデータベース/シリアライザーの値をさまざまな方法で変換するための機構を提供します（たとえば、値の保存とルックアップでの値の使用には違いがあります）。 これが少しトリッキーに聞こえる場合でも、心配しないでください。以下の例で明らかになります。 カスタムフィールドが必要な場合、しばしば2つのクラスを作成することになります:
最初のクラスは、ユーザーが操作するPythonオブジェクトです。彼らはそれをモデル属性に割り当て、そのようなものを表示するためにそれから読み込みます。これは、この例の Hand クラスです。
2番目のクラスは Field サブクラスです。これは、最初のクラスを永続ストレージ形式とPython形式の間で変換する方法を知っているクラスです。
class:~django.db.models.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)\nOur HandField accepts most of the standard field options (see the list\nbelow), but we ensure it has a fixed length, since it only needs to hold 52\ncard values plus their suits; 104 characters in total.
The Field.__init__() method takes the following parameters:
name
rel: 関連フィールドに使用される (ForeignKey など)。上級者向けです。
serialize: False の場合、Django の serializers にモデルが渡されたときに、フィールドをシリアライズしません。デフォルトの値は True です。
もしバックエンドが tablespaces をサポートする場合、db_tablespace: はインデックスの作成のみ行います。通常、このオプションは無視できます。
モデル継承で使用される OneToOneField のように、フィールドが自動的に作成された場合は、auto_created は True です。 高度な使用向けです。
上記のリストに説明のないオプションはすべて、通常のDjangoフィールドと同じ意味を持ちます。例と詳細については、 field documentation を参照してください。
\n__init__() メソッドとは対照的なものとして、~.Field.deconstruct`メソッドがあります。これは:doc:`model migrations 中に使用されるもので、新しいフィールドのインスタンスを取得する方法、インスタンスをどのようにシリアル化して減らすかの方法をDjangoに指示します。特に、インスタンスを再生成するためにどの引数を``__init__()``に渡すかを指示します。
継承元のフィールドの上に追加のオプションを追加していない場合、新しい deconstruct() メソッドを記述する必要はありません。 ただし、__init__() で渡される引数を変更する場合（HandField のように）、渡される値を補足する必要があります。
deconstruct() 関数は4つのアイテムを含むタプルを返します。それは、フィールドの属性、インポートするフィールドクラスのフルパス、位置引数（リスト型）、キーワード引数（辞書型）です。\nこの関数は deconstruct() メソッドとは異なることに注意してください。 deconstruct() メソッドは for custom classes で、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",)\nDjangoは変更を検出して移行を行わないため、カスタムフィールドの基本クラスを変更することはできません。たとえば、次で始まる場合:
\nclass CustomCharField(models.CharField):\n ...\nそして、代わりに TextField を使用することに決めた場合、サブクラスを次のように変更することはできません:
class CustomCharField(models.TextField):\n ...\n代わりに、新しいカスタムフィールドクラスを作成し、モデルを更新してそれを参照する必要があります:
\nclass CustomCharField(models.CharField):\n ...\n\n\nclass CustomTextField(models.TextField):\n ...\nAs discussed in removing fields, you\nmust retain the original CustomCharField class as long as you have\nmigrations that reference it.
いつものように、フィールドタイプのドキュメントを作成し、それがどんなものかをユーザがわかるようにしましょう。開発者にとって便利な docstring を提供するだけでなく、 django.contrib.admindocs ` アプリケーションを通して、管理者アプリのユーザにフィールドタイプの短い説明を表示することもできます。これを行うには、カスタムフィールドの :attr:`~Field.description クラス属性に説明文を記述します。上記の例では、 admindocs アプリケーションが表示する HandField の説明は 'A hand of cards (bridge style)' （日本語で「手札(ブリッジスタイル)」の意）となります。
django.contrib.admindocs の表示では、フィールドの説明は field.__dict__ によって補完され、説明文にフィールドの引数を組み込むことができます。例えば、 CharField の説明は次のようになります:
description = _("String (up to %(max_length)s)")\n Field サブクラスを作成したら、フィールドの動作に応じて、いくつかの標準メソッドをオーバーライドすることを検討できます。以下のメソッドのリストは、おおよそ重要度の高いものから順に並んでいるので、上から始めてください。
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"\nThe db_type() and rel_db_type() methods are called by\nDjango when the framework constructs the CREATE TABLE statements for your\napplication -- that is, when you first create your tables. The methods are also\ncalled when constructing a WHERE clause that includes the model field --\nthat is, when you retrieve data using QuerySet methods like get(),\nfilter(), and exclude() and have the model field as an argument.
一部のデータベースカラムの型は 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"\nIf your custom Field class deals with data structures that are more\ncomplex than strings, dates, integers, or floats, then you may need to override\nfrom_db_value() and to_python().
If present for the field subclass, from_db_value() will be called in all\ncircumstances when the data is loaded from the database, including in\naggregates and values() calls.
to_python() is called by deserialization and during the\nclean() method used from forms.
As a general rule, to_python() should deal gracefully with any of the\nfollowing arguments:
An instance of the correct type (e.g., Hand in our ongoing example).
文字列
None (フィールドが null=True を許す場合)
In our HandField class, we're storing the data as a VARCHAR field in\nthe database, so we need to be able to process strings and None in the\nfrom_db_value(). In to_python(), we need to also handle Hand\ninstances:
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)\nNotice that we always return a Hand instance from these methods. That's the\nPython object type we want to store in the model's attribute.
For to_python(), if anything goes wrong during value conversion, you should\nraise a ValidationError exception.
Since using a database requires conversion in both ways, if you override\nfrom_db_value() you also have to override\nget_prep_value() to convert Python objects back to query values.
例えば:
\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 )\nSome data types (for example, dates) need to be in a specific format\nbefore they can be used by a database backend.\nget_db_prep_value() is the method where those conversions should\nbe made. The specific connection that will be used for the query is\npassed as the connection parameter. This allows you to use\nbackend-specific conversion logic if it is required.
For example, Django uses the following method for its\nBinaryField:
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\nIn case your custom field needs a special conversion when being saved that is\nnot the same as the conversion used for normal query parameters, you can\noverride get_db_prep_save().
If you want to preprocess the value just before saving, you can use\npre_save(). For example, Django's\nDateTimeField uses this method to set the attribute\ncorrectly in the case of auto_now or\nauto_now_add.
もしこのメソッドをオーバーライドするならば、最後にその属性の値を返す必要があります。さらに、もしその値になんらかの変更を加えたならば、そのモデルへの参照を含んでいるコードが常に正しい値を指すように、モデルの属性を更新しなくてはなりません。
\nTo customize the form field used by ModelForm, you can\noverride formfield().
The form field class can be specified via the form_class and\nchoices_form_class arguments; the latter is used if the field has choices\nspecified, the former otherwise. If these arguments are not provided,\nCharField or TypedChoiceField\nwill be used.
All of the kwargs dictionary is passed directly to the form field's\n__init__() method. Normally, all you need to do is set up a good default\nfor the form_class (and maybe choices_form_class) argument and then\ndelegate further handling to the parent class. This might require you to write\na custom form field (and even a form widget). See the forms documentation for information about this.
Continuing our ongoing example, we can write the formfield() method\nas:
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)\nThis assumes we've imported a MyFormField field class (which has its own\ndefault widget). This document doesn't cover the details of writing custom form\nfields.
If you have created a db_type() method, you don't need to worry about\nget_internal_type() -- it won't be used much. Sometimes, though, your\ndatabase storage is similar in type to some other field, so you can use that\nother field's logic to create the right column.
例えば:
\nclass HandField(models.Field):\n # ...\n\n def get_internal_type(self):\n return "CharField"\nNo matter which database backend we are using, this will mean that\nmigrate and other SQL commands create the right column type for\nstoring a string.
If get_internal_type() returns a string that is not known to Django for\nthe database backend you are using -- that is, it doesn't appear in\ndjango.db.backends.<db_name>.base.DatabaseWrapper.data_types -- the string\nwill still be used by the serializer, but the default db_type()\nmethod will return None. See the documentation of db_type()\nfor reasons why this might be useful. Putting a descriptive string in as the\ntype of the field for the serializer is a useful idea if you're ever going to\nbe using the serializer output in some other place, outside of Django.
To customize how the values are serialized by a serializer, you can override\nvalue_to_string(). Using value_from_object() is the\nbest way to get the field's value prior to serialization. For example, since\nHandField uses strings for its data storage anyway, we can reuse some\nexisting conversion code:
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)\nWriting a custom field can be a tricky process, particularly if you're doing\ncomplex conversions between your Python types and your database and\nserialization formats. Here are a couple of tips to make things go more\nsmoothly:
\nLook at the existing Django fields (in\ndjango/db/models/fields/__init__.py) for inspiration. Try to find\na field that's similar to what you want and extend it a little bit,\ninstead of creating an entirely new field from scratch.
Put a __str__() method on the class you're wrapping up as a field. There\nare a lot of places where the default behavior of the field code is to call\nstr() on the value. (In our examples in this document, value would\nbe a Hand instance, not a HandField). So if your __str__()\nmethod automatically converts to the string form of your Python object, you\ncan save yourself a lot of work.
FileField サブクラスを書くLink to this heading#In addition to the above methods, fields that deal with files have a few other\nspecial requirements which must be taken into account. The majority of the\nmechanics provided by FileField, such as controlling database storage and\nretrieval, can remain unchanged, leaving subclasses to deal with the challenge\nof supporting a particular type of file.
Django provides a File class, which is used as a proxy to the file's\ncontents and operations. This can be subclassed to customize how the file is\naccessed, and what methods are available. It lives at\ndjango.db.models.fields.files, and its default behavior is explained in the\nfile documentation.
Once a subclass of File is created, the new FileField subclass must be\ntold to use it. To do so, assign the new File subclass to the special\nattr_class attribute of the FileField subclass.
上記の詳細に加えて、フィールドのコードの効率と読みやすさを劇的に改善するいくつかのガイドラインがあります。
\nThe source for Django's own ImageField (in\ndjango/db/models/fields/files.py) is a great example of how to\nsubclass FileField to support a particular type of file, as it\nincorporates all of the techniques described above.
Cache file attributes wherever possible. Since files may be stored in\nremote storage systems, retrieving them may cost extra time, or even\nmoney, that isn't always necessary. Once a file is retrieved to obtain\nsome data about its content, cache as much of that data as possible to\nreduce the number of times the file must be retrieved on subsequent\ncalls for that information.