モデル API リファレンス

AutoField

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

BooleanField

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

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

CharField

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

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

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

CharField には max_length という必須の引数があります。この引数はフィー ルドの (文字数で表した) 最大長です。 max_length への制約はデータベースと Django 内の検証の両方のレベルで行われます。

ベテラン Django ユーザへの注意: Django 内での一貫性を持たせるため、 引数名 maxlength は max_length に変わりました。これまで通り maxlength 引数は使えますが、今後は max_length を使うよう勧めます。

CommaSeparatedIntegerField

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

DateField

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

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

admin では、 JavaScript のカレンダーと 「今日」へのショートカットのついた <input type="text"> として表現されます。 JavaScript カレンダーは常に 日曜日から週が始まります。

DateTimeField

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

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

DecimalField

開発版の Django で新たに追加された機能です

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

引数	説明
max_digits	値を表現するのに使える最大桁数です。
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"> (一行のテキスト入力) で表現されます。

EmailField

値が有効な e-mail アドレスであるかチェックする CharField です。

Django 0.96 では、 max_length を指定できません。 max_length は自動的に 75 にセットされるからです。 開発版の Django では、 max_length はデフォルト で 75 にセットされますが、デフォルト値を書き換えるよう指定することができます。

FileField

ファイルアップロードのためのフィールドです。 必須の 引数を一つ持ちます:

引数	説明
upload_to	ローカルのファイルシステム上のパスです。 このパスは MEDIA_ROOT に設定したパスの後ろに つけられ、 get_<fieldname>_url() ヘルパ関数 の出力を決める際に使われます。

パスには strftime によるフォーマット を入れてもかまいません、フォーマッ ト文字列が入っていれば、(ディレクトリが同名のアップロードファイルで埋まらな いように)ファイルのアップロード日時に置き換わります。

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

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

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

アップロードファイルのディスク上でのファイル名を取得したい場合や、ファイル にアクセスするための URL を調べたい場合、ファイルのサイズを知りたい場合は、 それぞれ get_FOO_filename(), get_FOO_url(), get_FOO_size() メソッドを使えます。詳しくは get_FOO_ メソッド の説明を参照してください。

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

開発版の機能です: デフォルトでは、 FileField インスタンスは varchar(100) カラムをデータベースに作成します。他のフィールドにしたければ、 max_length 引数を使って最大長を変更することができます。

FilePathField

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

引数	説明
path	必須です。 FilePathField が選択肢を作成するための ディレクトリへの絶対パスです。例: "/home/images"
match	オプションです。正規表現を表す文字列で、 FilePathField がファイル名のフィルタに使います。正 規表現はフルパスではなくファイル名に適用されるので注意 してください。 例: "foo.*\.txt$" は foo23.txt にはマッチしますが、 bar.txt や foo23.gif には マッチしません。
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

開発版の Django で仕様が変更されました。

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

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

NOTE: 開発版の Django では、 FloatField の仕様が変更されています。 以前の仕様は、 Django 0.96 のドキュメント を参照してください。

ImageField

FileField に似ていますが、アップロードされたオブジェクトが有効なイメー ジかどうか検証します。二つのオプション引数、 height_field および width_field をとり、これらの値が設定されている場合には、モデルのインス タンスを保存するときに画像の高さと幅も同時に保存します。

ファイルフィールドで使える get_FOO_* メソッドの他に、 ImageField で は get_FOO_height() および get_FOO_width() メソッドを使えます。詳し くは get_FOO_height() と get_foo_width() の説明 を参照してください。

Python Imaging Library が必要です。

開発版の機能です: デフォルトでは、 ImageField インスタンスは varchar(100) カラムをデータベースに作成します。他のフィールドにしたければ、 max_length 引数を使って最大長を変更することができます。

IntegerField

整数です。

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

IPAddressField

IP アドレスを 文字列形式で表したもの (例: "192.0.2.30") です。

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

NullBooleanField

BooleanField と, 同じですが、 NULL を選択肢に使えます。 null=True の BooleanField の代わりに使って下さい。

admin では、「不明」 ("Unknown") 「はい」 ("Yes")、「いいえ」 ("No") の選択 肢をもつ <select> ボックスで表現されます。

PhoneNumberField

CharField と同じですが、値がアメリカ形式の電話番号として有効な形式 (XXX-XXX-XXXX) かどうかをチェックします。

PositiveIntegerField

IntegerField と同じですが、正の数でなければなりません。

PositiveSmallIntegerField

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

SlugField

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

CharField と同様、 max_length を指定できます。指定しなかった場合、 Django はデフォルト値の 50 を使います。 db_index=True になります。

SmallIntegerField

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

TextField

長いテキストのためのフィールドです。

admin では、 <textarea> (複数行の入力フィールド) で表現されます。

TimeField

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

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

URLField

URL を表すフィールドです。 verify_exists オプションを True (デフォ ルト値です) にすると、指定された URL が実在する (URL は実際にロードでき、か つ 404 応答を返さない) かどうか検証します。

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

URLField にはオプションの引数として、フィールドの最大長 (文字数) を表す max_length を指定できます。 max_length はデータベースのレベルや Django のバリデーションで自動的に指定されます。 max_length を指定しない ときのデフォルトの値は 200 です。

USStateField

2 文字のアメリカ合衆国州名略号です。

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

XMLField

TextField と同様ですが、指定されたスキーマに従って、値が有効な XML であ るか検証します。 schema_path を必須の引数にとります。 schema_path は検証に使う RelaxNG スキーマを指すファイルシステム上のパス名です。

null

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

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

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

blank

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

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

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 はあまり変更のない静的な選択肢のためのオプションだ からです。

core

オブジェクトが他のオブジェクトからリレーションを張られていて、インライン編 集の対象であるときに、フィールドをコアデータとしてマークします。

Django の admin 上でインライン編集しているオブジェクトの "core" フィールド の値を全て消去すると、そのオブジェクトは削除されます。

インライン編集可能なリレーションには、 core=True であるフィールドが少な くとも一つ必要です。なければエラーになります。

"core" を指定したフィールドは、Django admin サイト上では必須のフィールドと して扱われるので注意してください。実質的には、インライン編集の対象になるよ うなオブジェクトの全てのフィールドに core=True を指定しておかねばなり ません。

db_column

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

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

db_index

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

db_tablespace

開発版の Django で新たに追加された機能です

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

default

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

editable

False にすると、 admin 上や、オブジェクトの AddManipulator および ChangeManipulator クラスを使ったフォーム処理でフィールドの値を編集でき なくなります。デフォルト値は True です。

help_text

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

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

help_text="<em>YYYY-MM-DD</em> の形式で記入してください。"

primary_key

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

モデルのどのフィールドにも primary_key=True を指定しなければ、Django は 自動的に以下のフィールドを追加します:

id = models.AutoField('ID', primary_key=True)

従って、デフォルトの主キーの振舞いを変更したいのでないかぎり、 primary_key=True をフィールドに指定しておく必要はありません。

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

radio_admin

デフォルトでは、 ForeignKey のフィールドや choices の設定されたフィー ルドに対して、 Django の admin は選択ボックスインタフェース (<select>) を使 います。 radio_admin を True にすると、 Django はラジオボタンのイン タフェースを使います。

フィールドが ForeignKey であるか、 choices が設定されている のでなければ、このオプションを指定してはなりません。

unique

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

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

unique_for_date

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

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

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

unique_for_month

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

unique_for_year

unique_for_date や unique_for_month と同様です。

validator_list

フィールドに適用する追加のバリデータ (検証機構) のリストです。各バリデータ は呼び出し可能オブジェクトで、引数に field_data, all_data を取り、エラー が生じたときには django.core.validators.ValidationError を送出するよう になっていなければなりません (バリデータのドキュメント) を参照してくださ い。

Django にはほんの少しだけバリデータがついてきます。バリデータは django.core.validators に収められています。

多対一のリレーション

多対一のリレーションを定義するには ForeignKey を使います。このフィール ドは他のフィールド型と同じように、モデルのクラス属性に含めて使えます。

ForeignKey には、固定引数が一つあり、リレーションを張る対象のクラスを 指定します。

例えば、 Car モデルに Manufacturer というフィールドを持たせたいとし ましょう。すなわち、ある Manufacturer には複数の Car が対応するが、 各 Car には一つだけ Manufacturer が対応するようにしたいとしましょう。 この場合、以下のように定義します:

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

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

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

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

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

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

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

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

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

必須ではありませんが、 ForeignKey の名前 (上の例では manufacturer) は、モデル名を小文字にしたものにするよう勧めます。もちろん好きな名前を付け てもかまいません。例えば:

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

完全な使用例は 多対一のリレーションを持つモデルの例 を参照してください。

ForeignKey フィールドはリレーションの動作を定義するための引数をいくつか とれます。これらは全てオプションです:

引数	説明
edit_inline	True にすると、リレーション先のオブジェクト をリレーション元のオブジェクトのページで「イン ラインで」編集できます。これにより、リレーショ ン先のオブジェクトは独自の admin インタフェース を持たなくなります。 models.TABULAR または models.STACKED を指 定してください。それぞれ、インライン編集可能な オブジェクトをテーブルまたはスタックしたフィー ルドとして表示します。
limit_choices_to	admin で利用可能な選択肢を制限するための、ラベ ルと値を対応づけた辞書です (データベース API のリファレンス 参照)。 Python の datetime モジュールと組み合わせて、 オブジェクトを日付で制限できます。例えば: limit_choices_to = { 'pub_date__lte': datetime.now} のようにすると、 pub_date が現在の日時より 前のオブジェクトしか選べなくなります。 より複雑なクエリを実現するために、辞書の代りに Q オブジェクト (get_sql() メソッドを備 えたオブジェクト) も指定できます。 edit_inline と互換性がありません。
max_num_in_admin	インライン編集オブジェクトを編集するときに、 リレーションの張られたオブジェクトを admin に 最大何個まで表示するかを指定します。例えば、 ピザに乗せられるトッピングを 10 個までに制限 したければ、 max_num_in_admin=10 とする ことで、ユーザに 10 個以上のトッピングを 入力させなくできます。 この制限では、リレーションの張られたオブジェク トを実際に 10 個以上生成できなくするわけでは ないので注意してください。この引数が制御して いるのは admin インタフェースだけで、 Python API レベルやデータベースレベルでは制限を課しま せん。
min_num_in_admin	リレーションの張られたオブジェクトを admin に少なくとも何個表示するかを指定します。 通常、オブジェクトの生成ステージ (creation stage) では、 num_in_admin 個のインラインオブジェ クトが表示され、編集ステージ (edit stage) では 既存のオブジェクトに加えて num_extra_on_change 個の空白オブジェクトを 表示するようになっています。 ただし、リレーションの張られたオブジェクトの数 が min_num_in_admin 個以下の場合には表示 しません。
num_extra_on_change	オブジェクトの変更ステージにおいて、追加のブラ ンクのフィールドを何個表示するかを指定します。
num_in_admin	オブジェクトの追加ステージで、インラインオブジェ クトをデフォルトで何個表示するかを指定します。
raw_id_admin	ドロップダウンメニューの代わりに、整数を入力す るフィールドだけを表示します。 関連づけの対象になるオブジェクトの数が多すぎて 選択ボックスが実用的でない場合に便利です。 edit_inline とは組み合わせて使えません。
related_name	リレーション先のオブジェクトから逆参照するとき に使われる名前です。詳しくは オブジェクトのリレーションに関する解説 を参照してください。 抽象ベースクラス を使っているなら、 補足 の related_name に関する説明にも目を通して ください。
to_field	リレーション先のオブジェクトの、リレーションを 張る対象のフィールド名です。デフォルトでは、 リレーション先のオブジェクトの主キーを使います。

多対多のリレーション

多対多の (many-to-many) リレーションを定義するには ManyToManyField を使います。このフィールドは他のフィールド型と同じように、モデルのクラス属 性に含めて使えます。

ManyToManyField には固定引数が一つあり、リレーションを張る対象のクラスを 指定します。

例えば、 Pizza には複数の Topping オブジェクトを持たせられます。 すなわち、ある Topping は複数のピザの上に置けて、逆にそれぞれのピザには 複数のトッピングを置けるというわけです。このリレーションを表すには次のように します:

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

class Pizza(models.Model):
    # ...
    toppings = models.ManyToManyField(Topping)

ForeignKey と同じく、モデル名ではなく文字列 'self' を使えば自分自身 へのリレーションを定義できます。また、モデル名の入った文字列を使えば、未定 義のモデルも参照できます。ただし、文字列を使ってモデルを参照できるのは、同 じ models.py ファイル中にあるモデルだけです。別のアプリケーション中のモデル や、その他の場所から import したモデルは文字列で参照できません。

必須ではありませんが、 ManyToManyField の名前 (上の例では toppings) は、リレーション先のモデル名の複数形にするよう勧めます。

背後では、 Django は中間の join テーブルを生成して、多対多のリレーション を表現します。

どちらのモデルで ManyToManyField を定義してもかまいませんが、 どちらか片方のモデルにしか必要ありません -- 両方には指定できません。

一般的に、 Django の admin を使っている場合、 ManyToManyField インスタ ンスを入れておくのは、 admin インタフェースで編集される側のオブジェクトにし ておきます。上の例では、 topping は (Topping に ManyToManyField の pizzas をもたせるのではなく) Pizza に入れておきます。というのも、 「トッピングを乗せるピザ」と考えるよりも「ピザの上に乗せるトッピング」を考 える方が自然だからです。こうして上の例では、 Pizza の admin フォームで ユーザにトッピングを選ばせることになります。

完全な例は 多対多のリレーションを持つモデルの例 を参照してください。

ManyToManyField フィールドはリレーションの動作を定義するための引数を いくつかとれます。これらは全てオプションです:

引数	説明
related_name	前述の ForeignKey の説明を参照してください。
filter_interface	ユーザビリティが紙一重の <select multiple> の代わりに、気の利いた控えめな Javascript の 「フィルタ」インタフェースを使います。値は models.HORIZONTAL または models.VERTICAL のいずれか (インタフェースを横ならびにするか縦 ならびするか) です。
limit_choices_to	ForeignKey の同名オプションの説明を参照し てください。
symmetrical	自分自身への ManyToManyField を定義すると きにのみ使います。以下のようなモデルを考えます: class Person(models.Model): friends = models.ManyToManyField("self") Django がこのモデルを処理する際、自分自身に対 する ManyToManyField が定義されていること を認識して、 Person クラスに person_set 属性を追加しないようにします。 その代り、 ManyToManyField を対称的 (symmetrical) であるとみなします。すなわち、私 があなたの友達なら、あなたは私の友達である、と いうようにです。 self に対する ManyToMany の関係に対称 性を望まない場合は、 symmetrical を False にしてください。これにより、 Django に逆参照用のデスクリプタを追加させ、 ManyToMany を非対称にできます。
db_table	多対多のリレーション情報を保存するために作成さ れるテーブルの名前です。名前を指定しなければ、 Django はデフォルトの名前を使います。デフォル トの名前は、結合する二つのテーブルの名前に基づ いて決められます。

一対一のリレーション

一対一のリレーションを定義するには、 OneToOneField を使います。 このフィールドは他のフィールド型と同じように、モデルのクラス属 性に含めて使えます。

このリレーションがもっとも有用なのは、あるオブジェクトが別のオブジェクト を何らかの形で「拡張」している場合の主キーとして使う場合です。

OneToOneField には固定引数が一つあり、リレーションを張る対象のクラスを 指定します。

例えば、「場所 (place)」のデータベースを作るときには、アドレス、電話番号、 といった標準的なものを作成します。その上で、レストランデータベースを作成 するときに、 Restaurant モデルの中に同じフィールドをつくるような 繰り返し作業 (repeat yourself) をする代わりに、場所データベースを基盤にして レストランのデータベースを作成したいとしましょう。このとき、 Restaurant には Place への OneToOneField をもたせられます (レストランは 場所に対して "is-a" の関係だからです)

ForeignKey と同じく、モデル名ではなく文字列 'self' を使えば自分自身 へのリレーションを定義できます。また、モデル名の入った文字列を使えば、未定 義のモデルも参照できます。

OneToOneField は以下のオプションを指定できます:

引数	説明
parent_link	他のモデルを継承しているモデル中で True に すると、子のクラスのインスタンスから親のクラスの インスタンスに向けたリンクのフィールドとして 使います。詳しくは モデルの継承 を参照してくださ い。 開発版の Django で新たに追加された機能です

開発版の Django で新たに追加された機能: 以前は、モデル中で OneToOneField を使うと、そのフィールドをモデルの主キーにしていました。 この仕様はもうなくなりましたが、主キーにしたければ手動で primary_key に 指定できます。この変更により、一つのモデル中で複数の OneToOneField を使 えるようになりました。

詳細な例は 一対一のリレーションを持つモデルの例 を参照してください。

fields

フィールドセット内に表示するフィールド名からなるタプルです。必須のキーです。

例:

{
'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
}

同じ行に複数のフィールドを表示したい場合、それらのフィールドをタプルでラッ プして入れます。下の例では、 first_name と last_name が同じ行に 表示されます:

{
'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
}

classes

フィールドセットに適用される追加の CSS クラス名です。単純な文字列を指定しま す。

例:

{
'classes': 'wide',
}

また、以下の例のように、スペースで区切ると複数のクラスを適用できます:

{
'classes': 'wide extrapretty',
}

デフォルトのスタイルシートで定義されている便利なクラスとして collapse や wide があります。 collapse スタイルのフィールドは、 admin ページ では最初折り畳まれ (collapse) ており、小さな "クリックして展開 (click to expand)" リンクに置き換わっています。 wide スタイルのフィールドセットに は水平方向に追加のスペースが加わります。

description

各フィールドセットの先頭に表示する追加の文字列で、オプションです。この文字 列はそのまま表示されるので、 HTML を使えますし、 HTML で特別扱いされる文字 (アンパーサンドなど) は自分でエスケープしておかねばなりません。

追加のマネジャメソッド定義

モデルに「テーブルレベル」の機能を持たせたい場合、マネジャへのメソッドは良 い方法です。 (「行レベル」の機能を持たせたい、例えばモデルオブジェクトの個々 のインスタンスに影響する関数を実装したい場合には、カスタムのマネジャメソッ ドではなく モデルのメソッド を使って下さい。)

カスタムのマネジャメソッドは何を返してもかまいません。 QuerySet を返さ なくてもよいのです。

例えば、以下のカスタムマネジャでは、 with_counts() というメソッドを提供 しています。このメソッドは全ての OpinionPoll オブジェクトからなるリスト を返しますが、その際に集約クエリの結果である num_responses という追加の 属性を追加します:

class PollManager(models.Manager):
    def with_counts(self):
        from django.db import connection
        cursor = connection.cursor()
        cursor.execute("""
            SELECT p.id, p.question, p.poll_date, COUNT(*)
            FROM polls_opinionpoll p, polls_response r
            WHERE p.id = r.poll_id
            GROUP BY 1, 2, 3
            ORDER BY 3 DESC""")
        result_list = []
        for row in cursor.fetchall():
            p = self.model(id=row[0], question=row[1], poll_date=row[2])
            p.num_responses = row[3]
            result_list.append(p)
        return result_list

class OpinionPoll(models.Model):
    question = models.CharField(max_length=200)
    poll_date = models.DateField()
    objects = PollManager()

class Response(models.Model):
    poll = models.ForeignKey(Poll)
    person_name = models.CharField(max_length=50)
    response = models.TextField()

この例では、 OpinionPoll.objects.with_counts() を使うと、 num_responses 属性を備えた OpinionPoll オブジェクトのリストを返しま す。

この例でもう一つ注意して欲しいのは、マネジャメソッドが自分の属しているモデ ルクラスを取り出すために self.model にアクセスできるという点です。

初期 QuerySet の変更

マネジャのベースの QuerySet は、システム上の全てのオブジェクトを返しま す。例えば、以下のモデル:

class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)

では、 Book.objects.all() とすると、データベース上の全ての books を返し ます。

Manager.get_query_set() メソッドをオーバライドすれば、 Manager のベー スの QuerySet をオーバライドできます。 get_query_set() は必要なプロ パティを備えた QuerySet を返さねばなりません。

例えば、以下のモデルには 二つの マネジャがあります。片方は全てのオブジェ クトを返し、もう一方は Roald Dahl の書いた本だけを返します:

# まず Manager のサブクラスを定義します。
class DahlBookManager(models.Manager):
    def get_query_set(self):
        return super(DahlBookManager, self).get_query_set().filter(author='Roald Dahl')

# 次に Book モデルに明示的にフックします。
class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)

    objects = models.Manager() # デフォルトマネジャ。
    dahl_objects = DahlBookManager() # Dahl 縛りのマネジャ。

このモデル例では、 Book.objects.all() はデータベース上の Book を全て返 しますが、 Book.dahl_objects.all() は Roald Dahl の書いた本だけを返しま す。

get_query_set() は QuerySet オブジェクトを返すので、もちろん filter() や exclude() をはじめ全ての QuerySet メソッドを使えま す。従って、以下のような文を実行できます:

Book.dahl_objects.all()
Book.dahl_objects.filter(title='Matilda')
Book.dahl_objects.count()

この例はもう一つ興味深いテクニックの存在を示しています。それは同じモデルで 複数のマネジャを使えるということです。モデルには、好きなだけマネジャのイン スタンスをアタッチできます。この手法を使うと、よく利用するフィルタをモデル に簡単に実装できます。

例えば:

class MaleManager(models.Manager):
    def get_query_set(self):
        return super(MaleManager, self).get_query_set().filter(sex='M')

class FemaleManager(models.Manager):
    def get_query_set(self):
        return super(FemaleManager, self).get_query_set().filter(sex='F')

class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    sex = models.CharField(max_length=1, choices=(('M', 'Male'), ('F', 'Female')))
    people = models.Manager()
    men = MaleManager()
    women = FemaleManager()

この例では、 Person.men.all(), Person.women.all(), Person.people.all() といったクエリを発行できるようになっており、期待通 りの結果を得られます。

カスタムのマネジャオブジェクトを使う場合、 Django がモデル内に最初に見つけ たマネジャ (モデルに定義した順番で最初のマネジャ) は特別扱いされるというこ とに注意してください。 Django はクラス内で最初に見つけたマネジャを「デフォ ルトの」マネジャにし、このデフォルトマネジャを (admin アプリケーション以外 でも) あちこちでモデルのマネジャとして使います。ですから、 get_query_set() のオーバライドによって、扱いたいオブジェクトを取り出せ なくなるような羽目に陥らないように、デフォルトマネジャの選択には細心の注意 を払ってください。

permalink デコレータ

上に述べた get_absolute_url() の問題は、いささか DRY 則の侵犯である、す なわち URLconf とモデルの両方で URL が定義されているという点です。

permalink デコレータを使うと、 URLconf からモデルを脱カップリングできま す。このデコレータには、ビュー関数、引数のリスト、そして (オプションとして) 名前つきパラメタの入った辞書を指定します。これらの情報から、 Django は 指定したパラメタで URLconf を置き換えて完全な URL パスを計算します。例えば、 以下のような URLconf が定義されていたとしましょう:

(r'^people/(\d+)/$', 'people.views.details'),

また、モデルの get_absolute_url メソッドは以下のように定義できます:

from django.db.models import permalink

def get_absolute_url(self):
    return ('people.views.details', [str(self.id)])
get_absolute_url = permalink(get_absolute_url)

また、以下のような URLconf のエントリがあったとします:

(r'/archive/(?P<year>\d{4})/(?P<month>\d{1,2})/(?P<day>\d{1,2})/$',
    archive_view)

permalink は以下のように使えます:

def get_absolute_url(self):
    return ('archive_view', (), {
        'year': self.created.year,
        'month': self.created.month,
        'day': self.created.day})
get_absolute_url = permalink(get_absolute_url)

この例では、第 2 引数に空の配列 (空のタプル) を指定していますが、これは引数 リストを渡さず、キーワード引数だけを渡したいからです。

permalink を使えば、 URL に関する情報を繰り返すことなく、モデルの絶対 URL と表示に使ったビューを結びつけられます。以前と同様、 get_absolute_url はテンプレート中でも使えます。

汎用ビューを使う場合や、複数のモデルに対して同じビューを再利用する場合、ビュー 関数そのものを指定すると、（複数のパターンが同じビューを指してしまうため） URLディスパッチャが混乱をきたします。

この問題を解決するために、 Django には 名前つき URL パターン があります。 名前つき URL パターンを使えば、 URL パターンに固有の名前をつけておき、ビュー 関数の代わりに参照できます。名前つき URL パターンを定義するには、タプル表記 の URL パターンを url 関数に置き換えます:

from django.conf.urls.defaults import *

url(r'^people/(\d+)/$',
    'django.views.generic.list_detail.object_detail',
    name='people_view'),

この名前を使って、URL からビューの名前を以下のようにして逆解決します:

from django.db.models import permalink

def get_absolute_url(self):
    return ('people_view', [str(self.id)])
get_absolute_url = permalink(get_absolute_url)

名前つき URL パターンの詳細は URL ディスパッチャのドキュメント を参照してください。

Meta の継承

抽象ベースクラスを作成するとき、 Django は抽象ベースクラスの内部クラス Meta をクラス属性として参照できるようにします。子クラスで Meta クラスを定義しない場合、親クラスの Meta がそのまま継承されます。 子クラスで Meta を拡張したければ、親クラスをサブクラス化できます。 以下に例を示しましょう:

class CommonInfo(models.Model):
    ...
    class Meta:
        abstract = True
        ordering = ['name']

class Student(CommonInfo):
    ...
    class Meta(CommonInfo.Meta):
        db_table = 'student_info'

Django は抽象ベースクラスの Meta クラスを生成するときに一つだけ手を加え ます。すなわち、 Meta の属性を組み込む前に、 abstract=False を設定 するのです。これにより、抽象ベースクラスの子クラスが自動的に非抽象ベースク ラスになります。もちろん、他の抽象ベースクラスを継承した新たな抽象ベースク ラスも定義できます。継承するには、明示的に abstract=True をセットしてく ださい。

Meta クラスの属性の中には、抽象ベースクラスで定義しても意味のないものも あります。例えば、 db_table を抽象ベースクラスの Meta で定義すると、 その子クラス全て (で、独自に Meta を定義しないもの) が、同じデータベー ステーブルを使おうとしてしまいます。

related_name に注意

ForeignKey や ManyToManyField に related_name 属性を使っている 場合には、フィールドの 一意な 逆リレーション名を指定してください。 抽象ベースクラスのフィールドは (related_name の設定値を含み) 子クラスに そのまま組み込まれるので、 子クラスで同じ related_name のフィールドがで きてしまうため、問題を引き起こします。

この問題を回避するには、抽象ベースクラスで related_name を使うときに (かつその時に限り)、文字列の一部に '%(class)s' を付加してください。 そうすると、 '%(class)s' は子クラスでクラスの小文字名に置き換えられます。 各クラスは個別の名前をもっているので、結果的にリレーション名は個別の名前に なります。例えば:

class Base(models.Model):
    m2m = models.ManyToMany(OtherModel, related_name="%(class)s_related")

    class Meta:
        abstract = True

class ChildA(Base):
    pass

class ChildB(Base):
    pass

この例で、 ChildA.m2m フィールドの逆リレーション名は childa_related になり、 ChildB.m2m フィールドの逆リレーション名は childb_related になります。逆リレーション名の定義で '%(class)s' をどう使うかはユーザ次 第ですが、 '%(class)s' を使いわすれると、モデルの検証時 (または syncdb 時) に例外を送出します。

抽象ベースクラスのフィールドに related_name 属性を指定しない場合、子ク ラスの名前に '_set' をつけた名前をデフォルトの逆リレーション名として使 います。これは子クラスで直接リレーションフィールドを定義した場合と同じ挙動 です。例えば、上のコードで related_name 属性を省略すると、 m2m フィー ルドの逆リレーション名は ChildA では childa_set 、 ChildB では childb_set です。

Meta とマルチテーブル継承

マルチテーブル継承では、子クラスが親クラスの Meta クラスを継承する意味 がありません。 Meta オプションは全て親クラスだけに適用されるべきもので、 他のクラスに同じ内容を適用しても、矛盾した振る舞いを引き起こすだけです (これは、独自のテーブルを持たない抽象ベースクラスと対照的な部分です)。

従って、マルチテーブル継承の子クラスは親クラスの Meta クラスにアクセス する方法を持ちません。ただし、限られたケースで、子クラスが親クラスの挙動を 継承する場合があります。それは、子クラスで ordering または get_latest_by 属性を指定していない場合に、親クラスの属性を継承するとい うものです。

親クラスで整列カラムが指定されていて、子クラス側で整列カラムを指定したくな い場合は、明示的に空の整列カラムを指定してください:

class ChildModel(ParentModel):
    ...
    class Meta:
        # 親クラスの整列カラム設定の効果を除去する
        ordering = []

継承と逆リレーション

マルチテーブル継承は親クラスと子クラスを暗黙の OneToOneField でリンクす るので、前述の例のように、親クラスから子クラスをたどれます。しかし、子クラ スをたどるときに使う名前は、 ForeignKey や ManyToManyField リレーショ ンを定義したときのデフォルトの related_name と同じ値を使っています。 従って、子クラスで ForeignKey や ManyToManyField を別のクラスに向け て張るときには、 必ず related_name をフィールドに指定せねばなりませ ん。指定し忘れると、 Django は manage.py validate や syncdb 時にエ ラーを送出します。

例えば、上の Place クラスに対して、 ManyToManyField を持った別のサ ブクラスを定義してみましょう:

class Supplier(Place):
    # 全てのリレーションで related_name を定義すること
    customers = models.ManyToManyField(Restaurant,
            related_name='provider')

逆リレーションの詳細は、 データベース API リファレンス を参照してくださ い。とりあえずは、マルチテーブル継承で新たなモデルを作成したときには、 manage.py validate を実行して、エラーメッセージが出ないか確かめるように しましょう。

親クラスのリンクフィールドを定義する

すでに触れたように、 Django は子クラスと抽象クラスでない親クラスにリンクし た OneToOneField を自動的に生成します。親クラスへのリンク名を操作したけ れば、自分で OneToOneField を作成し、パラメタに parent_link=True を 渡してください。例えば、上の例で Supplier から Place への明示的なリ ンクフィールドを作成するには、以下のようにします:

class Supplier(Place):
    parent = models.OneToOneField(Place, parent_link=True)
    ...