モデルフィールドリファレンス

revision-up-to:17812 (1.4) unfinished

このドキュメントは、 Django が提供している フィールドのオプションフィールド型 の雑多で細かい解説です。

See also

組み込みのフィールド型で不足なことがあれば django.contrib.localflavor を試してみてください。これは特定の国や文化で便利に使えるコードの詰め合わせ になっています。また、 独自のカスタムモデルフィールドの作成 も簡単にできます。

Note

技術的には、モデルフィールドは django.db.models.fields モジュー ルで定義されていますが、便宜上、 django.db.models 内で import さ れています。モデルフィールドを使うときは、慣習的に from django.db import models として、 models.<Foo>Field のよう に参照します。

フィールドオプション

全てのフィールド型で、以下の引数を指定できます。これらの引数はすべてオプショ ンです。

null

Field.null

True にすると、 Django は空の値を NULL としてデータベースに入れます。 デフォルト値は False です。

空の文字列値は NULL ではなく空文字列として保存されることに注意して下さ い。 null=True が使えるのは、整数型やブール型、日付のような、文字列では ないフィールド型の場合だけです。 null はデータベースでの記録 操作にのみかかわるパラメタなので、フォーム上で空の値を入力できるようにした ければ blank=True も指定する必要があるでしょう (blank も 参照してください)。

特別な理由のない限り、 CharFieldTextField のような、 文字列ベースのフィールドには null を指定しないでください。 文字列ベースのフィールドが null=True であるということは、「データがない」 ことを表すのに NULL と空文字列という二つの値が存在することを示します。 多くの場合、「データがない」ことを表すのに二つのを取り得るのは冗長でしかあ りません。 Django の慣習では、データのない文字列フィールドの値は NULL ではなく空文字列です。

Note

Oracle バックエンドを使っている場合、データベースの制約のため、 空文字列を許すような文字列ベースのフィールドは、 null=True オプショ ンが強制的に付加され、 NULL は空の文字列を指します。

If you want to accept null values with BooleanField, use NullBooleanField instead.

blank

Field.blank

True にすると、フィールドの値を空白 (blank) にできます。デフォルト値は False です。

null とは違うことに注意してください。 null が 純粋にデータベース上の表現に関わる概念であるのに対し、 blank とは値の検証 (validation) に関わる概念です。あるフィールドに blank=True を指定すると、 Django の admin サイト上で、空の値のエントリを作成できます。 blank=False にすると、そのフィールドには必ず値を入れねばなりません。

choices

Field.choices

2 要素のタプルからなる iterable (リストまたはタプル) を、フィールドの値の選 択肢にします。

この値を指定すると、 Django の admin には標準的なテキストフィールドの代わり に選択ボックスが表示され、指定された選択肢だけをえらべます。

選択肢リストは以下のように指定します:

YEAR_IN_SCHOOL_CHOICES = (
    ('FR', 'Freshman'),
    ('SO', 'Sophomore'),
    ('JR', 'Junior'),
    ('SR', 'Senior'),
    ('GR', 'Graduate'),
)

各タプルの最初の要素は、データベースに実際に保存される値です。二つ目の値は 各オプションに対する人間可読な名前です。

選択肢リストは、モデルクラスの一部として定義できます:

class Foo(models.Model):
    GENDER_CHOICES = (
        ('M', 'Male'),
        ('F', 'Female'),
    )
    gender = models.CharField(max_length=1, choices=GENDER_CHOICES)

また、モデルクラスの外でも定義できます:

GENDER_CHOICES = (
    ('M', 'Male'),
    ('F', 'Female'),
)
class Foo(models.Model):
    gender = models.CharField(max_length=1, choices=GENDER_CHOICES)

また、選択肢をグループごとに集めて、名前をつけられます:

MEDIA_CHOICES = (
    ('Audio', (
            ('vinyl', 'Vinyl'),
            ('cd', 'CD'),
        )
    ),
    ('Video', (
            ('vhs', 'VHS Tape'),
            ('dvd', 'DVD'),
        )
    ),
    ('unknown', 'Unknown'),
)

各タプルの最初の要素は、選択肢グループの名前です。二つ目の要素は、2 要素の タプルからなるイテレーション可能なオブジェクトです。各 2 要素タプルには、 選択肢の値と、人間可読な名前を指定します。(上の例の unknown オプション のように) グループ化されたオプションとされていないオプションを混ぜても構い ません。

choices セットを持つモデルフィールド各々について、 Django は 特殊なメソッドを追加し、フィールドの現在値を人間可読な形式で取得できるよう にします。データベース API ドキュメントの get_FOO_display() を参照してください。

最後に、 choices はリストやタプルでなくともよく、任意の iterable オブジェク トでかまわないことに注意してください。つまり、 choices は動的生成できるので す。とはいえ、 choices を動的生成するようなハックをするくら いなら、適当なデータベーステーブルを ForeignKey で参照した方がよい でしょう。というのも、 choices はあまり変更のない静的な選択 肢のためのオプションだからです。

db_column

Field.db_column

フィールドに使うデータベースカラム名です。この値を指定しなければ、 Django はフィールド名を使います。

データベースカラム名が SQL の予約語であったり、 Python で変数名として使えな い文字を含んでいる (よくあるのはハイフンです) 場合でも問題ありません。 舞台裏で Django はカラム名やテーブル名をクオートします。

db_index

Field.db_index

True にすると django-admin.py sqlindexes を実行した時に、フィールドに対して CREATE INDEX 文を出力します。

db_tablespace

Field.db_tablespace

フィールドをインデクス化する場合に、このインデクスを格納する データベースのテーブルスペース の名前です。デフォルトの値は、プロジェクトで設定されている DEFAULT_INDEX_TABLESPACE です。この値がなければ、モデルの db_tablespace を使います。データベースバックエンドが インデクス格納用テーブルスペースをサポートしていない場合、 このオプションは無視されます。

default

Field.default

フィールドのデフォルト値です。この値は、何らかの値でも、呼び出し可能オブジェ クトでもかまいません。呼び出し可能オブジェクトの場合、新たなオブジェクトが 生成されるたびに呼び出されます。

editable

Field.editable

False にすると、 admin 上や、モデルクラスから生成したフォームの上でフィー ルドの値を編集できなくなります。デフォルト値は True です。

error_messages

Django 1.2 で新たに登場しました: リリースノートを参照してください
Field.error_messages

The error_messages argument lets you override the default messages that the field will raise. Pass in a dictionary with keys matching the error messages you want to override.

Error message keys include null, blank, invalid, invalid_choice, and unique. Additional error message keys are specified for each field in the `Field types`_ section below.

help_text

Field.help_text

オブジェクトの admin フォームの下に表示される、追加の「ヘルプ」テキストです。 とはいえ、オブジェクトが admin のフォームを持っていなくてもドキュメントとし て有用でしょう。

この値は admin インタフェース上に表示されるときに HTML エスケープされ ない ので注意してください。必要ならば、下記の例のように help_text に HTML を含めてもかまいません:

help_text="Please use the following format: <em>YYYY-MM-DD</em>."

プレーンテキストを使って、 django.utils.html.escape() でHTML の特殊文字 をエスケープしてもかまいません。

primary_key

Field.primary_key

True に指定すると、フィールドをモデルの主キーにします。

モデルのどのフィールドにも primary_key=True を指定しなければ、Django は 自動的に IntegerField を追加して主キーを保存します。従って、デフォ ルトの主キーの振舞いを変更したいのでないかぎり、 primary_key=True をフィー ルドに指定しておく必要はありません。詳しくは 主キーフィールドの自動設定 を参照してください。

primary_key=True であるということは、 null=False かつ unique=True であることを指します。一つのオブジェ クトには一つしか主キーを指定できません。

unique

Field.unique

True であれば、フィールドはテーブル全体で一意の値を取らねばなりません。

この制約は、データベースレベルと Django の admin のレベルで適用されます。 重複した値を持つ unique フィールドを含んだモデルを保存しよう とすると、モデルの save() メソッドによって django.db.IntegrityError が送出されます。

このオプションは、 ManyToManyField 以外の全てのフィールドで利用で きます。

unique_for_date

Field.unique_for_date

DateFieldDateTimeField 型のフィールドの名前を指定して おくと、そのフィールドの日付に対して一意な値になるように制約します。

例えば、 title という名前のフィールドがあり、 unique_for_date="pub_date" が指定されていたとすると、 Django は同じ titlepub_date の値を持つようなエントリを受け入れません。

この制約は Django の admin フォームのレベルで適用され、データベースレベルで は適用されません。

unique_for_month

Field.unique_for_month

unique_for_date と同様ですが、フィールドの値が月ごとに一意で あるように制約します。

unique_for_year

Field.unique_for_year

unique_for_dateunique_for_month と同じで す。

verbose_name

Field.verbose_name

A human-readable name for the field. If the verbose name isn’t given, Django will automatically create it using the field’s attribute name, converting underscores to spaces. See Verbose field names.

validators

Django 1.2 で新たに登場しました: リリースノートを参照してください
Field.validators

A list of validators to run for this field. See the validators documentation for more information.

フィールド型

AutoField

class AutoField(**options)

IntegerField の一種で、利用可能な ID の中から自動的にインクリメン トしていきます。通常、このフィールドが直接必要になることはないでしょう。主 キーのフィールドは、特に指定しない限り自動的に追加されます。 主キーフィールドの自動設定 を参照してください。

BigIntegerField

Django 1.2 で新たに登場しました: リリースノートを参照してください
class BigIntegerField([**options])

A 64 bit integer, much like an IntegerField except that it is guaranteed to fit numbers from -9223372036854775808 to 9223372036854775807. The admin represents this as an <input type="text"> (a single-line input).

BooleanField

class BooleanField(**options)

真偽 (true/false) 値を表すフィールドです。

admin ではこのフィールドはチェックボックスとして表現されます。

If you need to accept null values then use NullBooleanField instead.

Django 1.2 で変更されました: In previous versions of Django when running under MySQL BooleanFields would return their data as ints, instead of true bools. See the release notes for a complete description of the change.

CharField

class CharField(max_length=None[, **options])

文字列フィールドで、短い文字列からやや長いものに適しています。

大量のテキストを入れたい場合には TextField を使っ て下さい。

admin では <input type="text"> (一行の入力フィールド) で表現されます。

CharField 必須の引数があります:

CharField.max_length

フィールドの (文字数で表した) 最大長です。 max_length への制約はデー タベースと Django 内の検証の両方のレベルで行われます。

Note

If you are writing an application that must be portable to multiple database backends, you should be aware that there are restrictions on max_length for some backends. Refer to the database backend notes for details.

MySQL ユーザへの注意

MySQLdb 1.2.2 でこのフィールドを使っていて、コレーションを (デフォルト 設定 でない) utf8_bin に設定していると、いろいろと問題を引き起こ します。詳しくは MySQL データベースに関する注意 を参照してください。

CommaSeparatedIntegerField

class CommaSeparatedIntegerField(max_length=None[, **options])

カンマで区切った整数からなるフィールドです。 CharField と同じく、 max_length 引数が必要です。

DateField

class DateField([auto_now=False, auto_now_add=False, **options])

日付フィールドです。オプションの引数がいくつかあります:

DateField.auto_now

オブジェクトを保存する度に、その時の時刻を自動的に設定します。 “last-modified” タイムスタンプの実現に便利です。この値はオーバライドで きるデフォルト値ではなく、 常に 現在の日付になるので注意してください。

DateField.auto_now_add

オブジェクトを生成した時の時刻を自動的に設定します。タイムスタンプの生 成に便利です。この値はオーバライドできるデフォルト値ではなく、 常に 現在の日付になるので注意してください。

admin では、 JavaScript のカレンダーと 「今日」へのショートカットのついた <input type="text"> として表現されます。追加エラーメッセージのキー invalid_date を含みます。

Note

As currently implemented, setting auto_now or auto_now_add to True will cause the field to have editable=False and blank=True set.

DateTimeField

class DateTimeField([auto_now=False, auto_now_add=False, **options])

日付と時刻のフィールドです。 DateField と同じオプションを取ります。

admin では JavaScript のショートカットのついた <input type="text"> フィールドで表現されます。

DecimalField

class DecimalField(max_digits=None, decimal_places=None[, **options])

固定精度の 10 進小数です。 Python の Decimal 型インスタン スとして表現されます。 必須の 引数が 2 つあります:

DecimalField.max_digits

値を表現するのに使える最大桁数です。なお decimal_places が指定された場合、それ以上の値である必要があります。

DecimalField.decimal_places

小数部の保存に使われる桁数です。

例えば、小数部が 2 桁で、 999 までの数を表現できるようなフィールドを作成す るには、以下のようにします:

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

小数部の精度が 10 桁で、 10 億までの数を表現できるようにしたければ、以下の ようにします:

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

admin では、 <input type="text"> (一行のテキスト入力) で表現されます。

Note

For more information about the differences between the FloatField and DecimalField classes, please see FloatField vs. DecimalField.

EmailField

class EmailField([max_length=75, **options])

値が有効なメールアドレスであることをチェックする CharField です。

FileField

class FileField(upload_to=None[, max_length=100, **options])

ファイルアップロードのためのフィールドです。

Note

The primary_key and unique arguments are not supported, and will raise a TypeError if used.

必須の 引数を一つ持ちます:

FileField.upload_to

ローカルのファイルシステム上のパスです。このパスは MEDIA_ROOT に設定したパスの後ろにつけられ、 url 属性の値を決める際に使われます。

This path may contain strftime() formatting, which will be replaced by the date/time of the file upload (so that uploaded files don’t fill up the given directory).

upload_to には、関数のような呼び出し可能オブジェクトも指定できます。 呼び出し可能オブジェクトを指定すると、ファイル名を含むアップロードパス を決めるために呼び出されます。この呼び出し可能オブジェクトを定義する場 合、二つの引数をとり、 (スラッシュで始まる) Unix 形式のパスを返さねば なりません。返したパスはストレージシステムで使われます。二つの引数の説 明を以下に示します:

引数 説明
instance FileField を定義しているモデルのインス タンスです。もっと正確には、ファイルを添付 しようとしているインスタンスです。ほとんど の場合、このオブジェクトはまだデータベース に保存されていないので、デフォルトの AutoField を使っている場合、 まだ主キーフィールドの値が決まっていない ことがあります。
filename もともとファイルに付けられていたファイル名 です。最終的なファイルの保存パスを決めると きに考慮してもよいですし、しなくてもかまい ません。

また、オプションの引数を一つとります:

FileField.storage

省略可能です。ストレージの操作と、ファイルの取得を行うストレージ オブジェクトです。このオブジェクトの作り方については、 ファイルの管理 を参照してください。

admin では、 <input type="file"> (ファイルアップロードウィジェット) で表現されます。

モデル中で FileFieldImageField (下記参照) を使うには、 以下のようなステップが必要です:

  1. Django にアップロードされたファイルを保存させたい場所のフルパスを設 定ファイル中の MEDIA_ROOT に指定します。(パフォーマンス上 の理由から、アップロードされたファイルはデータベースに保存されませ ん。) 保存場所への公開 URL を MEDIA_URL に指定します。 ディレクトリが Web サーバのユーザアカウントによって書き込み可能であ るか確認してください。
  2. FileFieldImageField をモデルに定義します。この とき、 upload_to オプションを指定して、 MEDIA_ROOT 下のサブディレクトリのどこにアップロードされた ファイルを置くべきかを Django に教えます。
  3. データベースに保存されるのはファイルへのパス (MEDIA_ROOT からの相対) です。Django の提供している url を使うことになるでしょう。例えば、 mug_shot という名前の ImageField があれば、画像への絶対 パスは {{ object.get_mug_shot_url }} で取得できます。

例えば、 MEDIA_ROOT'/home/media' にして、 upload_to'photos/%Y/%m/%d' に設定したとします。 upload_to'%Y/%m/%d' の部分は strftime() と同じ フォーマット文字を使っています。すなわち、 '%Y' が 4 桁の年号、 '%m' が 2 桁の月、 '%d' が 2 桁の日を表します。従って、ファイルを 2007 年の 1 月 15 日にアップロードすると、 /home/media/photos/2007/01/15 に保存されます。

アップロードファイルのディスク上でのファイル名またはサイズを知りたい場合は、 それぞれ name, size 属性を使えます。利用可能な属性やメソッドの 詳細については File クラスのリファレンスと ファイルの管理 を参照してください。

Note

The file is saved as part of saving the model in the database, so the actual file name used on disk cannot be relied on until after the model has been saved.

The uploaded file’s relative URL can be obtained using the url attribute. Internally, this calls the url() method of the underlying Storage class.

ファイルのアップロードを処理するときには、常にアップロード先の場所やアップ ロードされるファイルに注意して、セキュリティホールを避けるようにしてくださ い。 アップロードされる全てのファイルをチェックして 、予想外のファイルが アップロードされないようにしましょう。例えば、バリデーションを行わずに Web サーバのドキュメントルート下へのファイルのアップロードを盲目的に受け入れる と、そこに誰かが CGI や PHP スクリプトをアップロードして、あなたのサイト上 の URL を訪問した人にスクリプトを実行させられてしまいます。そんなことを許し てはなりません。

Also note that even an uploaded HTML file, since it can be executed by the browser (though not by the server), can pose security threats that are equivalent to XSS or CSRF attacks.

デフォルトでは、 FileField インスタンスは varchar(100) カラム をデータベースに作成します。他のフィールドと同様、 max_length 引数を使って最大長を変更できます。

FileField and FieldFile

When you access a FileField on a model, you are given an instance of FieldFile as a proxy for accessing the underlying file. This class has several methods that can be used to interact with file data:

FieldFile.open(mode='rb')

Behaves like the standard Python open() method and opens the file associated with this instance in the mode specified by mode.

FieldFile.close()

Behaves like the standard Python file.close() method and closes the file associated with this instance.

FieldFile.save(name, content, save=True)

This method takes a filename and file contents and passes them to the storage class for the field, then associates the stored file with the model field. If you want to manually associate file data with FileField instances on your model, the save() method is used to persist that file data.

Takes two required arguments: name which is the name of the file, and content which is an object containing the file’s contents. The optional save argument controls whether or not the instance is saved after the file has been altered. Defaults to True.

Note that the content argument should be an instance of django.core.files.File, not Python’s built-in file object. You can construct a File from an existing Python file object like this:

from django.core.files import File
# Open an existing file using Python's built-in open()
f = open('/tmp/hello.world')
myfile = File(f)

Or you can construct one from a Python string like this:

from django.core.files.base import ContentFile
myfile = ContentFile("hello world")

For more information, see ファイルの管理.

FieldFile.delete(save=True)

Deletes the file associated with this instance and clears all attributes on the field. Note: This method will close the file if it happens to be open when delete() is called.

The optional save argument controls whether or not the instance is saved after the file has been deleted. Defaults to True.

FilePathField

class FilePathField(path=None[, match=None, recursive=False, max_length=100, **options])

ファイルシステム上のあるディレクトリ下のファイル名だけを選べるようになって いる CharField です。 3 つの特別な引数があり、そのうち最初の一つは 必須 です:

FilePathField.path

必須です。 FilePathField が選択肢を作成するためのディレクトリ への絶対パスです。例: "/home/images"

FilePathField.match

オプションです。正規表現を表す文字列で、 FilePathField がファ イル名のフィルタに使います。正規表現はフルパスではなくファイル名に適用 されるので注意してください。 例: "foo.*\.txt$"foo23.txt に はマッチしますが、 bar.txtfoo23.gif にはマッチしません。

FilePathField.recursive

オプションです。 True または False です。デフォルトは False で、 path のサブディレクトリを含めるかどうかを指 定します。

もちろん、これらの引数を組み合わせて使ってもかまいません。

よくある勘違いは、 match がファイル名ではなくフルパ スに適用されると思ってしまうことです。以下の例:

FilePathField(path="/home/images", match="foo.*", recursive=True)

/home/images/foo.gif にはマッチしますが、ファイル名本体 (foo.gifbar.gif) にマッチするため、 /home/images/foo/bar.gif にはマッチ しません。

FilePathField インスタンスは varchar(100) カラムをデータベース に作成します。他のフィールドと同様、 max_length 引数を使っ て最大長を変更できます。

FloatField

class FloatField([**options])

浮動小数点数です。Python の float 型インスタンスで表現されます。

admin では、 <input type="text"> (一行の入力フィールド) で表現されます。

FloatField vs. DecimalField

The FloatField class is sometimes mixed up with the DecimalField class. Although they both represent real numbers, they represent those numbers differently. FloatField uses Python’s float type internally, while DecimalField uses Python’s Decimal type. For information on the difference between the two, see Python’s documentation for the decimal module.

ImageField

class ImageField(upload_to=None[, height_field=None, width_field=None, max_length=100, **options])

FileField の属性とメソッドをすべて継承し、さらにアップロードされた オブジェクトが有効なイメージかどうか検証します。

In addition to the special attributes that are available for FileField, an ImageField also has height and width attributes.

To facilitate querying on those attributes, ImageField has two extra optional arguments:

ImageField.height_field

モデルインスタンスを保存する際に画像の高さを自動的に入れたいモデルフィー ルドの名前です。

ImageField.width_field

モデルインスタンスを保存する際に画像の幅を自動的に入れたいモデルフィー ルドの名前です。

Python Imaging Library が必要です。

ImageField インスタンスは varchar(100) カラムをデータベースに 作成します。他のフィールドと同様、 max_length 引数を使っ て最大長を変更できます。

IntegerField

class IntegerField([**options])

整数です。 admin では、 <input type="text"> (一行の入力フィールド) で表 現されます。

IPAddressField

class IPAddressField([**options])

IP アドレスを文字列形式で表したもの (例: “192.0.2.30”) です。admin では、 <input type="text"> (一行の入力フィールド) で表現されます。

GenericIPAddressField

class GenericIPAddressField([protocol=both, unpack_ipv4=False, **options])
Django 1.4 で新たに登場しました: リリースノートを参照してください

An IPv4 or IPv6 address, in string format (e.g. 192.0.2.30 or 2a02:42fe::4). The admin represents this as an <input type="text"> (a single-line input).

The IPv6 address normalization follows RFC 4291#section-2.2 section 2.2, including using the IPv4 format suggested in paragraph 3 of that section, like ::ffff:192.0.2.0. For example, 2001:0::0:01 would be normalized to 2001::1, and ::ffff:0a0a:0a0a to ::ffff:10.10.10.10. All characters are converted to lowercase.

GenericIPAddressField.protocol

Limits valid inputs to the specified protocol. Accepted values are 'both' (default), 'IPv4' or 'IPv6'. Matching is case insensitive.

GenericIPAddressField.unpack_ipv4

Unpacks IPv4 mapped addresses like ::ffff::192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.

NullBooleanField

class NullBooleanField([**options])

BooleanField と同じですが、 NULL を選択肢に使えます。 null=TrueBooleanField の代わりに使って下さい。 admin では、 「不明」 (“Unknown”) 「はい」 (“Yes”)、「いいえ」 (“No”) の選択肢をもつ <select> ボックスで表現されます。

PositiveIntegerField

class PositiveIntegerField([**options])

IntegerField と似ていますが、正の数か 0 でなければなりません。 0 が受け入れられる理由は、後方互換性を維持するためです。

PositiveSmallIntegerField

class PositiveSmallIntegerField([**options])

PositiveIntegerField と同じですが、ある範囲以下 (データベース依存 です)の値しか使えません。

SlugField

class SlugField([max_length=50, **options])

スラグ (slug)」は新聞業界の用語で、内容を示す短いラベル です。スラグは文字、数字、アンダースコア、ハイフンだけからなります。スラグ はよく URL に使われます。

CharField と同様、 max_length を指定できます。 (CharField のデータベース可搬性に関する注意と max_length の解説を参照してください) 指定しなかった場合、 Django はデフォルト値の 50 を使います。

Field.db_indexTrue に設定します。

It is often useful to automatically prepopulate a SlugField based on the value of some other value. You can do this automatically in the admin using prepopulated_fields.

SmallIntegerField

class SmallIntegerField([**options])

IntegerField と同様ですが、ある (データベース依存の) 範囲の値しか 使えません。

TextField

class TextField([**options])

長いテキストのためのフィールドです。admin では、 <textarea> (複数行の入 力フィールド) で表現されます。

MySQL ユーザへの注意

MySQLdb 1.2.2 でこのフィールドを使っていて、コレーションを (デフォルト 設定 でない) utf8_bin に設定していると、いろいろと問題を引き起こ します。詳しくは MySQL データベースに関する注意 を参照してください。

TimeField

class TimeField([auto_now=False, auto_now_add=False, **options])

時刻です。 DateFieldDateTimeField と同じく、自動的に 値を埋めるためのオプションを使えます。

admin では、JavaScript のショートカットがついた <input type="text"> で 表現されます。

URLField

class URLField([verify_exists=False, max_length=200, **options])

URL を表すための CharField です。引数を一つとります:

Django 1.4 で撤廃されました:

Deprecated since version 1.4: verify_exists is deprecated for security reasons as of 1.4 and will be removed in Django 1.5. Prior to 1.3.1, the default value was True.

URLField.verify_exists

True にすると、指定された URL が実在する (URL は実際にロードでき、 かつ 404 応答を返さない) かどうかを HEAD リクエストを使って検証します。 リダイレクト先はたどりません。

シングルスレッドで動作する開発サーバを使っていると、同じサーバ上の URL に対する検証をかけた瞬間にサーバがハングアップしてしまうので注意してく ださい。マルチスレッドで動作するサーバでは問題にならないはずです。

admin では、 <input type="text"> (一行の入力フィールド) で表現されます。

CharField の他のサブクラスと同じく、 URLField にはオプショ ンの引数として、フィールドの最大長 (文字数) を表す max_length を指定できます。 max_length を指定しないときのデフォルトの値は 200 です。

XMLField

class XMLField(schema_path=None[, **options])

TextField と同様ですが、指定されたスキーマに従って、値が有効な XML であ るか検証します。必須の引数を一つとります:

schema_path

検証に使う RelaxNG スキーマを指すファイルシステム上のパス名です。

リレーションフィールド

Django は、リレーションを表現するためのフィールドも定義しています。

ForeignKey

class ForeignKey(othermodel[, **options])

多対一のリレーションです。必須の固定引数として、リレーションを張るモデルの クラスをとります。

再帰的なリレーションを張る、つまり自分自身への多対一のリレーションを張る場 合には、 models.ForeignKey('self') を使います。

未定義のモデルへのリレーションを作成したい場合、モデルオブジェクトではなく モデルの名前も使えます:

class Car(models.Model):
    manufacturer = models.ForeignKey('Manufacturer')
    # ...

class Manufacturer(models.Model):
    # ...

他のアプリケーションで定義されているモデルを参照したければ、アプリケーショ ンラベルを明示的に指定せねばなりません。例えば、上の例の Manufacturer モデルが、 production という別のアプリケーションで定義されているのなら、 以下のように書かねばなりません:

class Car(models.Model):
    manufacturer = models.ForeignKey('production.Manufacturer')

この参照方法は、二つのアプリケーション間における循環インポート問題の解決に 使えます。

データベース上での表現

舞台裏では、 Django はフィールド名に "_id" をつけた名前でデータベースの カラム名を生成します。上の例では、 Car モデルのデータベーステーブルには manufacturer_id カラムが入ります (このカラム名は db_column を明示的 に指定して変更できます。詳しくは db_column を参照してくださ い) 。とはいえ、カスタムのSQL 文を発行するのでないかぎり、データベースのカ ラム名をコードで直接扱う必要はありません。

引数

ForeignKey は、他にもいくつかオプションの引数をとります。これらの 引数を使うと、リレーションの細かい動作を定義できます。

ForeignKey.limit_choices_to

データベースの照合オプション (クエリを生成する を参照) と値を対応 づけた辞書で、 admin で選択肢を表示するときに、表示するオブジェクトを絞 り込むために使えます。 Python の datetime モジュールと組み合わせれ ば、表示するオブジェクトを日付に基づいて制限できます。例えば:

limit_choices_to = {'pub_date__lte': datetime.now}

のようにすると、 pub_date が現在の日時より前のオブジェクトだけを選 べます。

辞書の代りに Q オブジェクトを使用すれば、 より 複雑なクエリ を指定できます。しかし limit_choices_toQ オブジェクトを指定した 場合、そのモデル用の ModelAdminraw_id_fields に、そのフィールド がリストアップされていない場合にだけ admin 上の選択肢に影響します。

ForeignKey.related_name

リレーション先のオブジェクトから逆参照するときに使われる名前です。 詳しくは related objects documentation を参照してください。 抽象ベースクラス で リレーションを定義する場合、この値を設定せねばなりません。また、抽象ベー スクラスで定義する場合には、 特殊な表記法 を使えます。

If you’d prefer Django didn’t create a backwards relation, set related_name to '+'. For example, this will ensure that the User model won’t get a backwards relation to this model:

user = models.ForeignKey(User, related_name='+')
ForeignKey.to_field

リレーション先のオブジェクトの、リレーションを張る対象のフィールド名で す。デフォルトでは、リレーション先のオブジェクトの主キーを使います。

Django 1.3 で新たに登場しました: リリースノートを参照してください
ForeignKey.on_delete

When an object referenced by a ForeignKey is deleted, Django by default emulates the behavior of the SQL constraint ON DELETE CASCADE and also deletes the object containing the ForeignKey. This behavior can be overridden by specifying the on_delete argument. For example, if you have a nullable ForeignKey and you want it to be set null when the referenced object is deleted:

user = models.ForeignKey(User, blank=True, null=True, on_delete=models.SET_NULL)

The possible values for on_delete are found in django.db.models:

  • CASCADE: Cascade deletes; the default.

  • PROTECT: Prevent deletion of the referenced object by raising django.db.models.ProtectedError, a subclass of django.db.IntegrityError.

  • SET_NULL: Set the ForeignKey null; this is only possible if null is True.

  • SET_DEFAULT: Set the ForeignKey to its default value; a default for the ForeignKey must be set.

  • SET(): Set the ForeignKey to the value passed to SET(), or if a callable is passed in, the result of calling it. In most cases, passing a callable will be necessary to avoid executing queries at the time your models.py is imported:

    def get_sentinel_user():
        return User.objects.get_or_create(username='deleted')[0]
    
    class MyModel(models.Model):
        user = models.ForeignKey(User, on_delete=models.SET(get_sentinel_user))
    
  • DO_NOTHING: Take no action. If your database backend enforces referential integrity, this will cause an IntegrityError unless you manually add a SQL ON DELETE constraint to the database field (perhaps using initial sql).

ManyToManyField

class ManyToManyField(othermodel[, **options])

多対多のリレーションです。必須の固定引数として、リレーション先のモデルを表 すクラスをとります。 ManyToManyField の引数は、 再帰的リレーショ ン遅延型のリレーション定義 に関するオプションを含め、 ForeignKey と 全く同じです。

データベース上での表現

舞台裏では、 Django は中間の結合テーブル (join table) を生成して、多対多の リレーションを表現します。デフォルトの設定では、テーブル名は many-to-many フィールドと、それを含むモデルの名前を使って生成されます。ただデータベース によっては一定の長さを超えるテーブル名をサポートしないため、テーブル名が長すぎる 場合は自動的に 64 文字に切り詰めて、さらにハッシュ値を使って一意な名前を 付けます。そのため author_books_9cdf4 といった名前のテーブルを見かけることが あると思いますが、これはまったく正常です。結合テーブルの名前は、 db_table オプションで手動指定できます。

引数

ManyToManyField は、他にもいくつかオプションの引数をとります。これ らの引数を使うと、リレーションの細かい動作を定義できます。

ManyToManyField.related_name

ForeignKey.related_name と同じです。

ManyToManyField.limit_choices_to

ForeignKey.limit_choices_to と同じです。

ManyToManyField を中間テーブル (intermediate table) と一緒に使うと、 limit_choices_to の効果はなくなります。

ManyToManyField.symmetrical

自分自身への ManyToManyField を定義すると きにのみ使います。以下のようなモデルを考えます:

class Person(models.Model):
    friends = models.ManyToManyField("self")

Django がこのモデルを処理する際、自分自身に対する ManyToManyField が定義されていることを認識して、 Person ク ラスに person_set 属性を追加しないようにします。その代り、 ManyToManyField を対称的 (symmetrical) であるとみなします。す なわち、私があなたの友達なら、あなたは私の友達である、というようにです。

self に対する多対多の関係に対称性を望まない場合は、 symmetricalFalse にしてください。これ により、 Django に逆参照用のデスクリプタを追加させて、 ManyToManyField を非対称にできます。

ManyToManyField.through

Django は多対多を管理するテーブルを自動的に作成しますが、中間テーブルを 独自に定義したいなら、 through オプションを使っ て、中間テーブルの表現に使いたいモデルを指定してください。

通常、このオプションを使うのは、 多対多の関係に追加のデータを持た せたいとき です。

ManyToManyField.db_table

多対多のリレーション情報を保存するために作成されるテーブルの名前です。 名前を指定しなければ、Django はデフォルトの名前を使います。デフォルトの 名前は、結合する二つのテーブルの名前に基づいて決められます。

OneToOneField

class OneToOneField(othermodel[, parent_link=False, **options])

一対一のリレーションです。一対一のリレーションは、概念的には unique=True であるような ForeignKey に似て いますが、リレーションの「逆」を辿ったときに、単一のオブジェクトを直接返す 点が違います。

最も OneToOneField が便利な局面は、他のモデルを何らかの形で拡張するとき のモデルの主キーとして使う場合です。例えば、 マルチテーブル継承 は、一対一のリレーションを子のモデルから親のモデルに自動的に張ることで実現 しています。

必須の固定引数として、リレーション先のモデルを表すクラスをとります。 引数は、 再帰的リレーション遅延 型のリレーション定義 に関するオプションを含め、 ForeignKey と全く同じです。

OneToOneField は、 ForeignKey で指定できる引数に加えて、以下の 引数を指定できます:

他のモデルを継承しているモデル中で True にすると、子のクラスのイン スタンスから親のクラスのインスタンスに向けたリンクのフィールドとして 使います。通常は、サブクラス化によって暗黙のうちに OneToOneField が作成されます。