| revision-up-to: | 11321 (1.1) unfinished |
|---|
このドキュメントは、 Django が提供している フィールドのオプション や フィールド型 の雑多で細かい解説です。
参考
組み込みのフィールド型で不足なことがあれば、簡単に 独自のカスタム モデルフィールドを作成できます 。
ノート
技術的には、モデルフィールドは django.db.models.fields モジュー ルで定義されていますが、便宜上、 django.db.models 内で import さ れています。モデルフィールドを使うときは、慣習的に from django.db import models として、 models.<Foo>Field のよう に参照します。
全てのフィールド型で、以下の引数を指定できます。これらの引数はすべてオプショ ンです。
True にすると、 Django は空の値を NULL としてデータベースに入れます。 デフォルト値は False です。
空の文字列値は NULL ではなく空文字列として保存されることに注意して下さ い。 null=True が使えるのは、整数型やブール型、日付のような、文字列では ないフィールド型の場合だけです。 null はデータベースでの記録 操作にのみかかわるパラメタなので、フォーム上で空の値を入力できるようにした ければ blank=True も指定する必要があるでしょう (blank も 参照してください)。
特別な理由のない限り、 CharField や TextField のような、 文字列ベースのフィールドには null を指定しないでください。 文字列ベースのフィールドが nill=True であるということは、「データがない」 ことを表すのに NULL と空文字列という二つの値が存在することを示します。 多くの場合、「データがない」ことを表すのに二つのを取り得るのは冗長でしかあ りません。 Django の慣習では、データのない文字列フィールドの値は NULL ではなく空文字列です。
ノート
Oracle バックエンドを使っている場合、データベースの制約のため、 空文字列を許すような文字列ベースのフィールドは、 null=True オプショ ンが強制的に付加され、 NULL は空の文字列を指します。
True にすると、フィールドの値を空白 (blank) にできます。デフォルト値は False です。
null とは違うことに注意してください。 null が 純粋にデータベース上の表現に関わる概念であるのに対し、 blank とは値の検証 (validation) に関わる概念です。あるフィールドに blank=True を指定すると、 Django の admin サイト上で、空の値のエントリを作成できます。 blank=False にすると、そのフィールドには必ず値を入れねばなりません。
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 はあまり変更のない静的な選択 肢のためのオプションだからです。
フィールドに使うデータベースカラム名です。この値を指定しなければ、 Django はフィールド名を使います。
データベースカラム名が SQL の予約語であったり、 Python で変数名として使えな い文字を含んでいる (よくあるのはハイフンです) 場合でも問題ありません。 Django は必要に応じてカラム名やテーブル名をクオートします。
True にすると django-admin.py sqlindexes を実行した時に、フィールドに対して CREATE INDEX 文を出力します。
フィールドの値をインデクス化する際、フィールドのインデクスとして使うデータ ベースのテーブル空間 (tablespace) の名前です。デフォルトの値は、プロジェク トで設定されている DEFAULT_INDEX_TABLESPACE です。この値がなけれ ば、モデルの db_tablespace を使います。データベースバックエ ンドがテーブルスペースをサポートしていなければ、このオプションは無視されま す。
フィールドのデフォルト値です。この値は、何らかの値でも、呼び出し可能オブジェ クトでもかまいません。呼び出し可能オブジェクトの場合、新たなオブジェクトが 生成されるたびに呼び出されます。
False にすると、 admin 上や、モデルクラスから生成したフォームの上でフィー ルドの値を編集できなくなります。デフォルト値は True です。
オブジェクトの admin フォームの下に表示される、追加の「ヘルプ」テキストです。 とはいえ、オブジェクトが admin のフォームを持っていなくてもドキュメントとし て有用でしょう。
この値は admin インタフェース上に表示されるときに HTML エスケープされ ない ので注意してください。必要ならば、下記の例のように help_text にHTML を含めてもかまいません:
help_text="Please use the following format: <em>YYYY-MM-DD</em>."
プレーンテキストを使って、 django.utils.html.escape() でHTML の特殊文字 をエスケープしてもかまいません。
True に指定すると、フィールドをモデルの主キーにします。
モデルのどのフィールドにも primary_key=True を指定しなければ、Django は 自動的に IntegerField を追加して主キーを保存します。従って、デフォ ルトの主キーの振舞いを変更したいのでないかぎり、 primary_key=True をフィー ルドに指定しておく必要はありません。詳しくは 主キーフィールドの自動設定 を参照してください。
primary_key=True であるということは、 null=False かつ unique=True であることを指します。一つのオブジェ クトには一つしか主キーを指定できません。
True であれば、フィールドはテーブル全体で一意の値を取らねばなりません。
この制約は、データベースレベルと Django の admin のレベルで適用されます。 重複した値を持つ unique フィールドを含んだモデルを保存しよう とすると、モデルの save() メソッドによって django.db.IntegrityError が送出されます。
このオプションは、 ManyToManyField 以外の全てのフィールドで利用で きます。
DateField や DateTimeField 型のフィールドの名前を指定して おくと、そのフィールドの日付に対して一意な値になるように制約します。
例えば、 title という名前のフィールドがあり、 unique_for_date="pub_date" が指定されていたとすると、 Django は同じ title や pub_date の値を持つようなエントリを受け入れません。
この制約は Django の admin フォームのレベルで適用され、データベースレベルで は適用されません。
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.
IntegerField の一種で、利用可能な ID の中から自動的にインクリメン トしていきます。通常、このフィールドが直接必要になることはないでしょう。主 キーのフィールドは、特に指定しない限り自動的に追加されます。 主キーフィールドの自動設定 を参照してください。
真偽 (true/false) 値を表すフィールドです。
admin ではこのフィールドはチェックボックスとして表現されます。
MySQL ユーザへの注意
MySQL では、ブール型のフィールドの値を TINYINT カラムに 0 または 1 で保存します (ほとんどのデータベースでは、適切な BOOLEAN 型を使いま す)。従って、 MySQL に限って、 BooleanField の値をデータベースから 取り出してモデルの属性に保存すると、その値は True や False では なく 1 や 0 になります。 Python は 1 == True かつ 0 == False を 保証しているので、通常、この動作が問題になることはありません。ただし、 obj is True のような式を書いていて、 obj がモデルのブール型属性 を指してるときには注意してください。 mysql バックエンドを使ってモデ ルを構築すると、この is テストは常に失敗します。 (== を使って) 等値比較を行ってください。
文字列フィールドで、短い文字列からやや長いものに適しています。
大量のテキストを入れたい場合には TextField を使っ て下さい。
admin では <input type="text"> (一行の入力フィールド) で表現されます。
CharField 必須の引数があります:
ノート
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 データベースに関する注意 を参照してください。
カンマで区切った整数からなるフィールドです。 CharField と同じく、 max_length 引数が必要です。
日付フィールドです。オプションの引数がいくつかあります:
admin では、 JavaScript のカレンダーと 「今日」へのショートカットのついた <input type="text"> として表現されます。 JavaScript カレンダーは常に日 曜日から週が始まります。
日付と時刻のフィールドです。 DateField と同じオプションを取ります。
admin では JavaScript のショートカットのついた <input type="text"> フィールドで表現されます。
固定精度の 10 進小数です。 Python の Decimal 型インスタン スとして表現されます。 必須の 引数が 2 つあります:
例えば、小数部が 2 桁で、 999 までの数を表現できるようなフィールドを作成す るには、以下のようにします:
models.DecimalField(..., max_digits=5, decimal_places=2)
小数部の精度が 10 桁で、 10 億までの数を表現できるようにしたければ、以下の ようにします:
models.DecimalField(..., max_digits=19, decimal_places=10)
admin では、 <input type="text"> (一行のテキスト入力) で表現されます。
ファイルアップロードのためのフィールドです。
ノート
The primary_key and unique arguments are not supported, and will raise a TypeError if used.
必須の 引数を一つ持ちます:
ローカルのファイルシステム上のパスです。このパスは MEDIA_ROOT に設定したパスの後ろにつけられ、 url 属性の値を決める際に使われます。
パスには strftime によるフォーマット を入れてもかまいません、フォー マット文字列が入っていれば、(ディレクトリが同名のアップロードファイルで 埋まらないように)ファイルのアップロード日時に置き換わります。
upload_to には、関数のような呼び出し可能オブジェクトも指定できます。 呼び出し可能オブジェクトを指定すると、ファイル名を含むアップロードパス を決めるために呼び出されます。この呼び出し可能オブジェクトを定義する場 合、二つの引数をとり、 (スラッシュで始まる) Unix 形式のパスを返さねば なりません。返したパスはストレージシステムで使われます。二つの引数の説 明を以下に示します:
| 引数 | 説明 |
|---|---|
| instance | FileField を定義しているモデルのインス タンスです。もっと正確には、ファイルを添付 しようとしているインスタンスです。ほとんど の場合、このオブジェクトはまだデータベース に保存されていないので、デフォルトの AutoField を使っている場合、 まだ主キーフィールドの値が決まっていない ことがあります。 |
| filename | もともとファイルに付けられていたファイル名 です。最終的なファイルの保存パスを決めると きに考慮してもよいですし、しなくてもかまい ません。 |
また、オプションの引数を一つとります:
省略可能です。ストレージの操作と、ファイルの取得を行うストレージオブジェ クトです。このオブジェクトの作り方は、 ファイルの管理 を参照してく ださい。
admin では、 <input type="file"> (ファイルアップロードウィジェット) で表現されます。
モデル中で FileField や ImageField (下記参照) を使うには、 以下のようなステップが必要です:
例えば、 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 に保存されます。
アップロードファイルのディスク上でのファイル名を取得したい場合や、ファイル にアクセスするための URL を調べたい場合、ファイルのサイズを知りたい場合は、 それぞれ name, url, size メソッドを使えます。詳しくは ファイルの管理 を参照してください。
ファイルのアップロードを処理するときには、常にアップロード先の場所やアップ ロードされるファイルに注意して、セキュリティホールを避けるようにしてくださ い。 アップロードされる全てのファイルをチェックして 、予想外のファイルが アップロードされないようにしましょう。例えば、バリデーションを行わずに Web サーバのドキュメントルート下へのファイルのアップロードを盲目的に受け入れる と、そこに誰かが CGI や PHP スクリプトをアップロードして、あなたのサイト上 の URL を訪問した人にスクリプトを実行させられてしまいます。そんなことを許し てはなりません。
デフォルトでは、 FileField インスタンスは varchar(100) カラム をデータベースに作成します。他のフィールドと同様、 max_length 引数を使って最大長を変更できます。
ファイルシステム上のあるディレクトリ下のファイル名だけを選べるようになって いる CharField です。 3 つの特別な引数があり、そのうち最初の一つは 必須 です:
もちろん、これらの引数を組み合わせて使ってもかまいません。
よくある勘違いは、 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 引数を使っ て最大長を変更できます。
浮動小数点数です。Python の float 型インスタンスで表現されます。
admin では、 <input type="text"> (一行の入力フィールド) で表現されます。
FileField に似ていますが、アップロードされたオブジェクトが有効なイ メージかどうか検証します。二つのオプション引数があります:
FileField で使える特殊属性の他に、 ImageField で File.height および File.width を使えます。 ファイルの管理 を参照してください。
Python Imaging Library が必要です。
ImageField インスタンスは varchar(100) カラムをデータベースに 作成します。他のフィールドと同様、 max_length 引数を使っ て最大長を変更できます。
整数です。 admin では、 <input type="text"> (一行の入力フィールド) で表 現されます。
IP アドレスを 文字列形式で表したもの (例: "192.0.2.30") です。admin では、 <input type="text"> (一行の入力フィールド) で表現されます。
BooleanField と同じですが、 NULL を選択肢に使えます。 null=True の BooleanField の代わりに使って下さい。 admin では、 「不明」 ("Unknown") 「はい」 ("Yes")、「いいえ」 ("No") の選択肢をもつ <select> ボックスで表現されます。
PositiveIntegerField と同じですが、ある範囲以下 (データベース依存 です)の値しか使えません。
「 スラグ (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.
IntegerField と同様ですが、ある (データベース依存の) 範囲の値しか 使えません。
長いテキストのためのフィールドです。admin では、 <textarea> (複数行の入 力フィールド) で表現されます。
MySQL ユーザへの注意
MySQLdb 1.2.2 でこのフィールドを使っていて、コレーションを (デフォルト 設定 でない) utf8_bin に設定していると、いろいろと問題を引き起こ します。詳しくは MySQL データベースに関する注意 を参照してください。
時刻です。 DateField や DateTimeField と同じく、自動的に 値を埋めるためのオプションを使えます。
admin では、JavaScript のショートカットがついた <input type="text"> で 表現されます。
URL を表すための CharField です。引数を一つとります:
admin では、 <input type="text"> (一行の入力フィールド) で表現されます。
CharField の他のサブクラスと同じく、 URLField にはオプショ ンの引数として、フィールドの最大長 (文字数) を表す max_length を指定できます。 max_length を指定しないときのデフォルトの値は 200 です。
Aug 19, 2010