revision-up-to: | 17812 (1.4) |
---|
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 の
モジュール検索パス になければなりません。
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
実際のサーバ環境では、 WSGIアプリケーショにどの設定モジュールを使うのか教え
る必要があります。これには os.environ
を使います:
import os
os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'
より詳しい情報やその他Django WSGIアプリケーションに一般的な事項に関しては mod_wsgiでDjango を使うためのドキュメント を参照してください。
Django の設定ファイルでは、特に必要のない限り設定をおこなう必要はありません。
各々の設定には注意深く決められたデフォルト値が入っています。デフォルト値は
django/conf/global_settings.py
ファイルに収められています。
Django が設定をコンパイルする際には、以下のようなアルゴリズムを使います:
global_settings.py
から設定を読みだします。設定ファイルから global_setting
を import するのは無駄で、
必要ありません 。
デフォルトの設定と自分の設定の違いを確かめる簡単な方法があります。
python manage.py diffsettings
を実行すると、現在の設定と Django のデフォ
ルト設定との違いを表示します。
詳しくは diffsettings
のドキュメントを参照してください。
自作の 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 の設定は手動で行えるようになっています。手動
の設定には django.conf.settings.configure()
を呼び出します。
django.conf.settings.
configure
(default_settings, **settings)¶例えば:
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
にあります。
環境変数 DJANGO_SETTINGS_MODULE
を指定しない場合、設定を利用する何らか
のコードが実行される前に、 必ず configure()
を呼び出しておかねばなり
ません。
環境変数 DJANGO_SETTINGS_MODULE
を指定せず、 configure()
も呼び出さ
なかった場合、 Django は最初に設定にアクセスした時点で ImportError
例外を送出します。
環境変数 DJANGO_SETTINGS_MODULE
を指定して、何らかの設定にアクセスした
後に configure()
を呼び出すと、 Django は設定がすでに行われている旨の
RuntimeError
例外を送出します。
また、 configure()
を何度も呼び出したり、何らかの設定にアクセスした後に
configure()
を呼び出してもエラーになります。
つまりは、「 configure()
と DJANGO_SETTINGS_MODULE
のどちらかを設定
してください」ということです。両方設定してはなりませんし、両方とも忘れても
なりません。
Oct 26, 2017