プロジェクトの作成¶

初めて Django を使うのなら、最初のセットアップを行う必要があります。通常は、 Django の プロジェクト (project) を構成するコードを自動生成 します。プロジェクトとは、データベースの設定や Django 固有のオプション、ア プリケーション固有の設定などといった、個々の Django インスタンスの設定をあ つめたものです。

コマンドラインから、コードを置きたい場所に cd して、 django-admin.py startproject mysite を実行してください。現在のディレク トリに mysite ディレクトリが作成されます。

python setup.py ユーティリティで Django をインストールしたのなら、 django-admin.py はシステムパスのどこかにあるはずです。パス上になけ れば、 site-packages/django/bin にあります。 site-packages は Python インストールディレクトリの中にあります。パス上のどこか、例えば /usr/local/bin にシンボリックリンクを張っておきましょう。)

startproject が何を作成したかをみてみましょう:

mysite/
    __init__.py
    manage.py
    settings.py
    urls.py

ファイルはそれぞれ以下のような役割を持っています:

• __init__.py: このディレクトリが Python パッケージであることを Python に知らせるための空のファイルです。(Python の初心者は、 Python の公式ドキュメントの (パッケージの詳しい説明 を読んで下さい。)
• manage.py: Django プロジェクトに対する様々な操作を行うための コマンドラインユーティリティです。詳しくは django-admin.py と manage.py を参照してください。
• settings.py: Django プロジェクトの設定ファイルです。 設定の仕組みは Django の設定 を参照してください。
• urls.py: Django プロジェクトの URL 宣言、いうなれば Django 化サイ トにおける「目次」に相当します。 URL ディスパッチャ を参照してく ださい。

Validating models...
0 errors found.

Django version 1.0, using settings 'mysite.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

python manage.py runserver 8080

python manage.py syncdb

モデルの作成¶

さあ、これで自分用の環境、すなわちプロジェクトが立ち上がり、作業にとりかか る準備ができました。

Django で書いたアプリケーションは Python パッケージからなり、 ある規約に従っ て Python パス のどこかに置かねばなりません。Django にはアプリケーション の基本的なディレクトリ構造を作成するためのユーティリティがついてくるので、 ディレクトリの作成は気にせずコードの記述に集中できます。

このチュートリアルでは、簡単のため、投票アプリケーションを mysite ディレクトリの中に作ります。その結果、アプリケーションはプロジェクトとカッ プリングします。すなわち、 poll アプリケーション内の Python コードは mysite.polls のように参照されることになります。チュートリアルの後半では、 アプリケーションを配布用に脱カップリングする方法について議論する予定です。

アプリケーションを作成するには、 mysite ディレクトリの下に入って、 以下のようなコマンド:

python manage.py startapp polls

を入力します。このコマンドは polls というディレクトリを作成し、その 中に以下のようにファイルを配置します:

polls/
    __init__.py
    models.py
    views.py

このディレクトリ構造こそが、 poll アプリケーションの全体像です。

Django でデータベース Web アプリケーションを書くための最初のステップは、モ デルの定義です。本質的には、データベースのレイアウトと、追加のメタデータの 定義です。

これから開発する簡単な poll アプリケーションでは、投票項目 (poll) と選択肢 (choice) の二つのモデルを作成します。 poll には質問事項 (question) と公開日 (publication date) の情報があります。 choice には選択肢のテキストと投票数 (vote) という二つのフィールドがあります。各 choice は一つの poll に関連づけ られることになります。

Django では、こうした概念を簡単な Python クラスで表現できます。 polls/models.py ファイルを以下のように編集してください:

from django.db import models

class Poll(models.Model):
    question = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')

class Choice(models.Model):
    poll = models.ForeignKey(Poll)
    choice = models.CharField(max_length=200)
    votes = models.IntegerField()

コードは単純明解ですね。各モデルは一つのクラスで表現され、いずれも django.db.models.Model のサブクラスです。各モデルには複数のクラス 変数があり、個々のクラス変数はモデルのデータベースフィールドを表現していま す。

各フィールドは Field クラスのインスタンスとして 表現されています。例えば、 CharField は 文字のフィールドで、 DateTimeField は日時フィー ルドです。こうしたクラスは、各フィールドにどのようなデータ型を記憶させるか を Django に教えます。

models.*Field` インスタンスの名前 (question や pub_date) はフィールドの名前で、計算機にとって扱いやすい名前を付けます。この名前は Python コードの中で使いますし、データベースではカラム名に使います。

django.db.models.Field の第一固定引数には、オプションとして人間可 読なフィールド名も指定できます。このフィールド名は Django の二つの内省 (introspection) 機能で使う他、ドキュメントとしての役割も果たします。人間可 読なフィールド名を指定しない場合、 Django は機械可読な名前を使います。上の 例では、 Poll.pub_date にだけ人間可読なフィールド名を指定しました。モデ ルの他のフィールドでは、フィールドの機械可読な名前は人間可読な名前としても 十分なので定義していません。

Field クラスの中には必須の引数を持つものがありま す。例えば CharField には max_length を指定する必要があります。この引 数はデータベーススキーマで使われる他、後で述べるバリデーションでも使われま す。

最後に、 ForeignKey を使ってリレーションが定義さ れていることに注意して下さい。このリレーションは、各 Choice が一つの Poll に関連づけられていることを Django に教えます。 Django は多対一、多対多、一 対一といった、広く使われているリレーション全てをサポートしています。

モデルを有効にする¶

前述のようなほんのわずかなコードをモデルに書くだけで、 Django はたくさんの 情報を手にします。このコードを使って、 Django は:

• アプリケーションのデータベーススキーマを作成 (CREATE TABLE 文を実 行) できます。
• Poll や Choice オブジェクトに Python からアクセスするためのデータベー ス API を作成できます。

ただし、その前に polls アプリケーションをインストールしたことをプロジェ クトに教えてやる必要があります。

再度 settings.py ファイルを編集して、 INSTALLED_APPS 設 定を変更し、 'mysite.polls' を入れます。以下のようになるはずです:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'mysite.polls'
)

これで Django は mysite に polls アプリケーションが入っているこ とを知りました。もう一つコマンドを実行してみましょう:

python manage.py sql polls

以下のような (polls アプリケーション用の CRATE TABLE SQL 文) が表示されるは ずです:

BEGIN;
CREATE TABLE "polls_poll" (
    "id" serial NOT NULL PRIMARY KEY,
    "question" varchar(200) NOT NULL,
    "pub_date" timestamp with time zone NOT NULL
);
CREATE TABLE "polls_choice" (
    "id" serial NOT NULL PRIMARY KEY,
    "poll_id" integer NOT NULL REFERENCES "polls_poll" ("id"),
    "choice" varchar(200) NOT NULL,
    "votes" integer NOT NULL
);
COMMIT;

以下の点に注意してください:

• 実際に出力される SQL 文は、使っているデータベースによって変わります。
• テーブル名はアプリケーションの名前 (polls) とモデルの小文字表記 (poll および choice) を使って自動的に生成されます (この挙動は オーバライドできます。)
• 主キー (primary key, ID) は自動的に生成されます (この挙動もオーバライ ド可能です)
• 便宜上、 Django は外部キーのフィールド名に "_id" を追加します。も ちろんこの挙動もオーバライド可能です。
• 外部キーのリレーションは REFERENCES 文で明示的に作成されます。
• SQL 文は使っているデータベースに応じて細かく調整されます。従って、 auto_increment (MySQL)、 serial (PostgreSQL)、 integer primary key (SQLite) といったデータベース固有のフィールド タイプは自動的に指定されます。クオートの仕方、すなわち一重と二重のど ちらの引用符を使うか、といったことも自動で調整します。このチュートリ アルの作者は PostgreSQL を使っており、例題での出力は PostgreSQL の文 法に準じています。
• sql コマンドを実行しても、実際にデータベースで SQL を実行 するわけではありません。 sql コマンドは、ユーザが Django の挙動を 知りたいと考えたときのため、単に SQL 文をスクリーンに表示しているだけ です。必要なら、この SQL 文をコピーしてデータベースクライアントのプロ ンプトにペーストできますが、後ですぐ述べるように、 Django では SQL を データベースに commit させる簡単な方法を提供しています。

興味があるなら、以下のコマンドも実行してみてください:

• python manage.py validate -- モデルの構成にエ ラーがないか調べます。
• python manage.py sqlcustom polls -- 各アプリケー ション向けに定義しておいた、カスタマイズ (テーブル形式の変更や制約) 用の SQL 文を出力します。
• python manage.py sqlclear polls -- アプリケーショ ン用のテーブルのうち、データベース上に存在するものについて必要に応じ て DROP TABLE 文を出力します。
• python manage.py sqlindexes polls -- アプリケー ション用の CREATE INDEX 文を出力します。
• python manage.py sqlall polls -- 'sql', 'sqlcustom', 'sqlindexes' コマンドを合わせたものです。

これらのコマンドの出力を見れば、水面下で実際に行われていることを理解する助 けになるでしょう。

syncdb を再度実行して、モデルテーブルをデータベース上に作成しま しょう:

python manage.py syncdb

syncdb コマンドは INSTALLED_APPS に登録されているアプ リケーションのうち、データベース上にまだ存在しないものに対して sqlall で生成した SQL を生成します。こにれよって、最後に syncdb を実行した時以後に新たにプロジェクトに追加されたアプリケー ションのテーブルと初期データ、インデクスを生成します。 syncdb はその都度存在しないテーブルだけを生成するので、繰り返し実行してもかまいま せん。

manage.py ユーティリティでできることについては django-admin.py のドキュメント を読んで下さい。

API で遊んでみる¶

さて、Python 対話シェルを起動して、 Django が提供する API で遊んでみましょ う。 Python シェルを起動するには、以下のコマンドを実行します:

python manage.py shell

単に "python" を実行しないのは、 manage.py でプロジェクトの環境を設定し ているからです。ここでいう「環境の設定」とは:

• mysite を sys.path に入れます。柔軟性を持たせるために、 Django を構成するコードの中には Python のドット表記 (例えば 'mysite.polls.models') でプロジェクトを参照するものがあります。 この表記でプロジェクトをうまく参照できるようにするには、 mysite パッケージは sys.path 上になければなりません。

  こうした表記法の例は、すでに見たことがあるはずです: 例えば INSTALLED_APPS 設定は、ドット表記のパッケージ名からなるリ ストです。

• 環境変数 DJANGO_SETTINGS_MODULE を設定して、 settings.py ファ イルの在処を Django に教えます。

シェルに入ったら、 データベース API の世界を探検 してみましょう:

>>> from mysite.polls.models import Poll, Choice # モデルクラスを import します。

# まだ Poll は一つもできていません。
>>> Poll.objects.all()
[]

# 新たな Poll を作成しましょう。
>>> import datetime
>>> p = Poll(question="What's up?", pub_date=datetime.datetime.now())

# 出来たオブジェクトをデータベースに保存します。 save() は明示的に呼ば
# ねばなりません。
>>> p.save()

# これでオブジェクトに ID が割り当てられました。お使いのデータベースに
# よっては、この値は "1" ではなく "1L" のときもあります。心配することは
# ありません。単にデータベースバックエンドが Python 長整数型で値を返す
# ようになっているだけのことです。
>>> p.id
1

# データベースの各カラムに Python の属性としてアクセスします。
>>> p.question
"What's up?"
>>> p.pub_date
datetime.datetime(2007, 7, 15, 12, 00, 53)

# 属性を変更して save() を呼び出すとカラムの値を変更します。
>>> p.pub_date = datetime.datetime(2007, 4, 1, 0, 0)
>>> p.save()

# objects.all() はデータベース上の全ての Poll を返します。
>>> Poll.objects.all()
[<Poll: Poll object>]

おっと、ちょっと待って下さい。 <Poll: Poll object> なんて全然親切な表現 ではありませんね。そこで (polls/models.py ファイルに定義されている) polls 関係のモデルを少し修正して、 Poll と Choice に __unicode__() メソッドを追加しましょう:

class Poll(models.Model):
    # ...
    def __unicode__(self):
        return self.question

class Choice(models.Model):
    # ...
    def __unicode__(self):
        return self.choice

__unicode__() をモデルに追加しておく重要性は、 対話プロンプトで扱うときに精神的によいだけでなく、Django が自動生成する管理 インタフェースのいたるところでオブジェクトの表現 (representation) が使われ ているという点にもあります。

__unicode__() は通常の Python メソッドという ことに注意してください。デモ用にカスタムのメソッドを追加してみましょう:

import datetime
# ...
class Poll(models.Model):
    # ...
    def was_published_today(self):
        return self.pub_date.date() == datetime.date.today()

import datetime で Python の標準モジュール datetime を参照している ことに注意してください。

python manage.py shell を実行して、Python 対話シェルに戻りましょう:

>>> from mysite.polls.models import Poll, Choice

# __unicode__() がきちんと働いていることを確認します。
>>> Poll.objects.all()
[<Poll: What's up?>]

# Django は様々なデータベース照合 API を提供しています。 API はキーワー
# ド引数で隅々まで操作できます。
>>> Poll.objects.filter(id=1)
[<Poll: What's up?>]
>>> Poll.objects.filter(question__startswith='What')
[<Poll: What's up?>]

# 2007 年の Poll を取り出しましょう。あなたがこのチュートリアルを実行
# しているのが 2007 年でないのなら、適当に値を読みかえてください。
>>> Poll.objects.get(pub_date__year=2007)
<Poll: What's up?>

>>> Poll.objects.get(id=2)
Traceback (most recent call last):
    ...
DoesNotExist: Poll matching query does not exist.
>>> Poll.objects.filter(question__startswith='What')
[<Poll: What's up?>]

# 主キーの照合はよくあることなので、 Django は主キーの厳密一致を照合
# するショートカットを提供しています。
# 以下の実行文は Poll.objects.get(id=1) と同じです。
>>> Poll.objects.get(pk=1)
<Poll: What's up?>

# カスタムメソッドが動作するか確かめてみましょう。
>>> p = Poll.objects.get(pk=1)
>>> p.was_published_today()
False

# Poll に二つの Choice を指定しましょう。 create を呼び出すと、新たな
# Choice オブジェクトを生成し、 INSERT 文を実行し、 Poll からアクセス可
# 能な Choice オブジェクトの集合に追加して、新たに作成された Choice オ
# ブジェクトを返します。

>>> p = Poll.objects.get(pk=1)
>>> p.choice_set.create(choice='Not much', votes=0)
<Choice: Not much>
>>> p.choice_set.create(choice='The sky', votes=0)
<Choice: The sky>
>>> c = p.choice_set.create(choice='Just hacking again', votes=0)

# Choice オブジェクトは自分に関連づけされた Poll オブジェクトに
# アクセスするための API を備えています。
>>> c.poll
<Poll: What's up?>

# 逆も行えます: Poll オブジェクトから Choice オブジェクトにアクセスでき
# ます。
>>> p.choice_set.all()
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]
>>> p.choice_set.count()
3

# API は必要に応じて自動的にリレーションを追跡します。リレーションを辿
# るには二重アンダースコアを使います。この表記法には制限がなく、何段階
# でも連鎖できます。以下の例では、 pub_date が 2007 の全ての Poll に関
# 連づけられている Choice を返します。
>>> Choice.objects.filter(poll__pub_date__year=2007)
[<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]

# choice を一つ削除しましょう。 delete() を使います。
>>> c = p.choice_set.filter(choice__startswith='Just hacking')
>>> c.delete()

データベース API の詳細は、 データベース API リファレンス を参照してください。 API を使いこなせるようになったら、 チュートリアル第 2 部 に進んで、Django が自動生成 する管理インタフェースを動かしてみましょう。