Django v1.0 documentation

Django の設定

revision-up-to:8961 (1.0)

Django の設定ファイルには、インストールした Django の使う全ての設定が入って います。このドキュメントでは、各設定の役割と、どのような設定を利用できるか について説明します。

基礎

設定ファイルはモジュールレベルの変数の入った単なる Python モジュールです。

設定の例をいくつか示します:

DEBUG = False
DEFAULT_FROM_EMAIL = 'webmaster@example.com'
TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john')

設定ファイルは Python モジュールなので、以下のような性質を備えています:

  • Python の構文エラーが入っていてはなりません。

  • 通常の Python 構文を使って動的に値を設定できます。例えば:

    MY_SETTING = [str(i) for i in range(30)]
    
  • 他の設定ファイルから値を import できます。

設定ファイルの特定

Django を使う場合、どの設定を使っているのかを Django に教えなければなりませ んが、これには環境変数 DJANGO_SETTINGS_MODULE を使います。

DJANGO_SETTINGS_MODULE は Python のモジュールパス構文、たとえば mysite.settings のようにします。設定モジュールは Python の モジュール検索パス になければなりません。

The django-admin.py utility

django-admin.py ユーティリティ

django-admin.py を使う場合、環境変数をあらかじめ 指定しておくか、ユーティリティを起動する度に設定モジュールを明示的に渡しま す。

例 (Unix Bash シェル):

export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin.py runserver

例 (Windows コマンドプロンプト):

set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin.py runserver

コマンドライン引数で設定モジュールを指定するには --settings を使います:

django-admin.py runserver --settings=mysite.settings

サーバ (mod_python) の設定

実際のサーバ環境では、 Apache/mod_python にどの設定モジュールを使うのか教え る必要があります。これには SetEnv を使います:

<Location "/mysite/">
    SetHandler python-program
    PythonHandler django.core.handlers.modpython
    SetEnv DJANGO_SETTINGS_MODULE mysite.settings
</Location>

詳しくは mod_python で Django を使うためのドキュメント を参照してください。

デフォルトの設定

Django の設定ファイルでは、特に必要のない限り設定をおこなう必要はありません。 各々の設定には注意深く決められたデフォルト値が入っています。デフォルト値は django/conf/global_settings.py ファイルに収められています。

Django が設定をコンパイルする際には、以下のようなアルゴリズムを使います:

  • global_settings.py から設定を読みだします。
  • 指定の設定ファイルから設定を読み出し、グローバルな設定をオーバライド します。

設定ファイルから global_setting を import するのは冗長であり、 やってはなりません

変更結果を確かめる

デフォルトの設定と自分の設定の違いを確かめる簡単な方法があります。 python manage.py diffsettings を実行すると、現在の設定と Django のデフォ ルト設定との違いを表示します。

詳しくは diffsettings のドキュメントを参照してください。

Python コード内で設定を参照する

自作の Django アプリケーションから設定を参照するには、 django.conf モ ジュールから settings オブジェクトを import します:

from django.conf import settings

if settings.DEBUG:
    # Do something

django.conf.settings はモジュールではなくオブジェクトです。このため、 個々の設定は別々に import できません:

from django.conf.settings import DEBUG  # This won't work.

また、 global_settings や自作の設定ファイルを直接 import しては ならない ので注意して下さい。 django.conf.settings はデフォルト設定と サイト固有の設定を抽象化しており、単一のインタフェースで設定を提供するとと もに、設定を使うコードとユーザの設定ファイルの置き場所とを脱カップリングし ています。

実行時に設定を変更する

実行時に設定を変更してはなりません。たとえば、ビューの中で以下のような操作 を行ってはなりません:

from django.conf import settings

settings.DEBUG = True   # やってはダメ!

設定を書いてよいのは設定ファイルの中だけです。

セキュリティ

設定ファイルにはデータベースのパスワードのような重要な情報が入っているので、 設定ファイルへのアクセスはできるだけ制限してください。例えば、設定ファイル のパーミッションを、Web サーバを駆動しているユーザとあなただけが読み書きで きるように変更してください。共有ホスティング環境で運用するような場合、これ は極めて重要な事項です。

利用可能な設定

利用可能な設定は setting リファレンス を参照してくだ さい。

設定項目を自作する

設定項目は自由に自作でき、 Django アプリケーションから利用できます。いくつ か取り決めがあるので従うようにして下さい:

  • 設定名は全て大文字にします。
  • 設定値をシーケンス型にする場合、リストではなくタプルを使って下さい。 これは純粋にパフォーマンス上の要求です。
  • 既に存在する設定の再発明はやめましょう。

DJANGO_SETTINGS_MODULE を使わない設定方法

場合によっては、環境変数 DJANGO_SETTINGS_MODULE をバイパスしたい場合も あるでしょう。たとえばテンプレートシステムを単体で使いたい場合、設定ファイ ルの在処を指すような環境変数を取り入れたくはないかもしれません。

こうした場合のために、 Django の設定は手動で行えるようになっています。手動 の設定には django.conf.settings.configure() を呼び出します。

例えば:

from django.conf import settings

settings.configure(DEBUG=True, TEMPLATE_DEBUG=True,
    TEMPLATE_DIRS=('/home/web-apps/myapp', '/home/web-apps/base'))

configure() には必要なだけキーワードを指定してかまいません。各キーワー ドは設定とその値を表します。各引数名は全て大文字で、上記の各設定名と同じに せねばなりません。 configure() に渡さなかった指定が後で必要になった場合、 Django はデフォルトの設定値を使います。

ほとんどの場合、この方法で Django を設定する必要がありますし、より大規模な アプリケーション内でフレームワークの一部を使う場合には、実際上記の方法がお 勧めです。

settings.configure() で設定を行った場合、 Django はプロセスの環境変数に 何ら変更を加えません (理由は前述の TIME_ZONE の説明を参照してください。) これらのケースでは、ユーザがすでに環境変数を自由に制御できるものと仮定して います。

カスタムのデフォルト設定

デフォルト設定を django.conf.global_settings 以外の場所から取り込みたい 場合、モジュールやクラスの中で configure() を呼び出し、 default_settings 引数 (または最初の固定引数) でデフォルト設定を渡せます。

以下の例では、デフォルトの設定を myapp_defaults から取り出し、 DEBUG の設定を myapp_defaults の設定に関わらず True になるよう にしています:

from django.conf import settings
from myapp import myapp_defaults

settings.configure(default_settings=myapp_defaults, DEBUG=True)

以下の例では、 myapp_defaults を固定引数にしており、上の例と同じ意味に なります:

settings.configure(myapp_defaults, DEBUG = True)

通常、このようなやり方でデフォルト値をオーバライドする必要はありません。 Django は十分に扱いやすい設定値をデフォルト値にしていて、ほぼ問題なく利用で きます。新たなデフォルトモジュールを渡すと、そのモジュールは Django のデフォ ルトを 完全に 置き換えてしまうため、 import している側のコードで必要な全 ての設定値を指定せねばならないので注意して下さい。設定の完全なリストは django.conf.global_settings にあります。

configure() または DJANGO_SETTINGS_MODULE のいずれかが必要です

環境変数 DJANGO_SETTINGS_MODULE を指定しない場合、設定を利用する何らか のコードが実行される前に、 必ず configure() を呼び出しておかねばなり ません。

環境変数 DJANGO_SETTINGS_MODULE を指定せず、 configure() も呼び出さ なかった場合、 Django は最初に設定にアクセスした時点で ImportError 例外を送出します。

環境変数 DJANGO_SETTINGS_MODULE を指定して、何らかの設定にアクセスした 後に configure() を呼び出すと、 Django は設定がすでに行われている旨の RuntimeError 例外を送出します。

また、 configure() を何度も呼び出したり、何らかの設定にアクセスした後に configure() を呼び出してもエラーになります。

つまりは、「 configure()DJANGO_SETTINGS_MODULE のどちらかを設定 してください」ということです。両方設定してはなりませんし、両方とも忘れても なりません。