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

revision-up-to:	17812 (1.4) unfinished

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

フィールドオプション¶

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

`null`¶

Field.null¶

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

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

特別な理由のない限り、 CharField や TextField のような、文字列ベースのフィールドには 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`¶

リリースノートを参照してください

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¶

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

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

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

`unique_for_month`¶

Field.unique_for_month¶

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

`unique_for_year`¶

Field.unique_for_year¶

unique_for_date や unique_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`¶

リリースノートを参照してください

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`¶

リリースノートを参照してください

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.

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"> (ファイルアップロードウィジェット) で表現されます。

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

Django にアップロードされたファイルを保存させたい場所のフルパスを設定ファイル中の MEDIA_ROOT に指定します。(パフォーマンス上の理由から、アップロードされたファイルはデータベースに保存されません。) 保存場所への公開 URL を MEDIA_URL に指定します。ディレクトリが Web サーバのユーザアカウントによって書き込み可能であるか確認してください。
FileField や ImageField をモデルに定義します。このとき、 upload_to オプションを指定して、 MEDIA_ROOT 下のサブディレクトリのどこにアップロードされたファイルを置くべきかを Django に教えます。
データベースに保存されるのはファイルへのパス (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.txt や foo23.gif にはマッチしません。

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

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

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

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

は /home/images/foo.gif にはマッチしますが、ファイル名本体 (foo.gif や bar.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])¶

リリースノートを参照してください

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=True の BooleanField の代わりに使って下さい。 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_index を True に設定します。

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])¶

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

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

`URLField`¶

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

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

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_to に Q オブジェクトを指定した場合、そのモデル用の ModelAdmin の raw_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¶: リレーション先のオブジェクトの、リレーションを張る対象のフィールド名です。デフォルトでは、リレーション先のオブジェクトの主キーを使います。

リリースノートを参照してください

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 に対する多対多の関係に対称性を望まない場合は、 symmetrical を False にしてください。これにより、 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 で指定できる引数に加えて、以下の引数を指定できます:

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

Django 1.4 documentation

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

フィールドオプション¶

null¶

blank¶

choices¶

db_column¶

db_index¶

db_tablespace¶

default¶

editable¶

error_messages¶

help_text¶

primary_key¶

unique¶

unique_for_date¶

unique_for_month¶

unique_for_year¶

verbose_name¶

validators¶

フィールド型¶

AutoField¶

BigIntegerField¶

BooleanField¶

CharField¶

CommaSeparatedIntegerField¶

DateField¶

DateTimeField¶

DecimalField¶

EmailField¶

FileField¶

FileField and FieldFile¶

FilePathField¶

FloatField¶

ImageField¶

IntegerField¶

IPAddressField¶

GenericIPAddressField¶

NullBooleanField¶

PositiveIntegerField¶

PositiveSmallIntegerField¶

SlugField¶

SmallIntegerField¶

TextField¶

TimeField¶

URLField¶

XMLField¶

リレーションフィールド¶

ForeignKey¶

データベース上での表現¶

引数¶

ManyToManyField¶

データベース上での表現¶

引数¶

OneToOneField¶

Last update:

`null`¶

`blank`¶

`choices`¶

`db_column`¶

`db_index`¶

`db_tablespace`¶

`default`¶

`editable`¶

`error_messages`¶

`help_text`¶

`primary_key`¶

`unique`¶

`unique_for_date`¶

`unique_for_month`¶

`unique_for_year`¶

`verbose_name`¶

`validators`¶

`AutoField`¶

`BigIntegerField`¶

`BooleanField`¶

`CharField`¶

`CommaSeparatedIntegerField`¶

`DateField`¶

`DateTimeField`¶

`DecimalField`¶

`EmailField`¶

`FileField`¶

`FilePathField`¶

`FloatField`¶

`ImageField`¶

`IntegerField`¶

`IPAddressField`¶

`GenericIPAddressField`¶

`NullBooleanField`¶

`PositiveIntegerField`¶

`PositiveSmallIntegerField`¶

`SlugField`¶

`SmallIntegerField`¶

`TextField`¶

`TimeField`¶

`URLField`¶

`XMLField`¶

`ForeignKey`¶

`ManyToManyField`¶

`OneToOneField`¶