Djangoの設定¶
Djangoの設定ファイルには、インストールしたDjangoの全ての設定が含まれています。このドキュメントでは、各設定の役割と、どのような設定を利用できるか説明していきます。
基礎¶
設定ファイルはモジュールレベルの変数が記述された、ただのPythonモジュールです。
設定例を幾つか示します:
ALLOWED_HOSTS = ["www.example.com"]
DEBUG = False
DEFAULT_FROM_EMAIL = "webmaster@example.com"
注釈
もし DEBUG を False にした場合、 ALLOWED_HOSTS も設定する必要があります。
設定ファイルはPythonのモジュールなので、以下のような性質を備えています。
Pythonの構文エラーになってはいけません。
通常の Pythonの構文を使って、動的に値を設定する事ができます。例えば:
MY_SETTING = [str(i) for i in range(30)]
他の設定ファイルから値を import できます。
設定ファイルの指定¶
-
DJANGO_SETTINGS_MODULE¶
Django を使うとき、どの設定を使うかを Django に伝える必要があります。そのためには環境変数 DJANGO_SETTINGS_MODULE を使います。
DJANGO_SETTINGS_MODULE の値は Python のパス構文、例えば mysite.settings で指定します。設定モジュールはPythonの sys.path にあることに注意してください。
django-admin ユーティリティ¶
django-admin を使う場合、環境変数を予め指定しておくか、ユーティリティを起動する度に設定モジュールを明示的に渡します。
例 (Unix Bash シェル):
export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver
例 (Windows シェル):
set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver
コマンドライン引数で設定モジュールを指定するには、次のように --settings を使用します。
django-admin runserver --settings=mysite.settings
サーバ (mod_wsgi) の設定¶
実際のサーバ環境では、 WSGI アプリケーションにどの設定ファイルを使うのか教えてあげる必要があります。これには os.environ:: を使います。
import os
os.environ["DJANGO_SETTINGS_MODULE"] = "mysite.settings"
さらなる情報や他のDjango WSGI アプリケーションでの共通の設定は Django mod_wsgi ドキュメント を参照してください。
デフォルトの設定¶
Django の設定ファイルでは、特に必要のない限り設定を行う必要はありません。各々の設定には注意深く決められたデフォルト値が入っています。デフォルト値は django/conf/global_settings.py に記述されています。
Django が設定をコンパイルする際には、以下のようなアルゴリズムを使います:
global_settings.pyから設定を読みだす。- 指定された設定ファイルから設定を読み込み、グローバルな設定を必要に応じて上書きします。
設定ファイルから global_settings を読み込むのは冗長なのでやらないでください。
設定の変更を確かめる¶
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 はデフォルト設定とサイト固有の設定を抽象化し、単一のインタフェースを提供しています。また設定を使うコードと設定ファイルの場所を分離しています。
実行時に設定を変更する¶
アプリケーションの実行中に設定を変えてはいけません。例えば、viewの中で以下の実装を行ってはいけません。
from django.conf import settings
settings.DEBUG = True # Don't do this!
設定を変えて良いのは、設定ファイルの中だけです。
セキュリティ¶
設定ファイルにはデータベースのパスワードのような重要な情報が入っているため、設定ファイルへのアクセスはできるだけ制限してください。たとえば、設定ファイルのパーミッションを、あなたとウェブサーバだけが読み取れるようにしてください。共有ホスティング環境で運用する場合、これは極めて重要な事項です。
利用可能な設定¶
利用可能な設定は settings リファレンス を参照してください。
設定項目を自作する¶
Django アプリケーションの設定項目は自由に作成できますが、以下のガイドラインに従ってください。
- 設定項目の変数名は、全て大文字にしなければなりません。
- 既存の設定の再発明はやめましょう。
設定値をシーケンスにする際は、リストを使ってください。ただしこれはDjangoの慣習です。
DJANGO_SETTINGS_MODULE 設定を使わない設定方法¶
DJANGO_SETTINGS_MODULE 環境変数をパイパスしたい場合もあるかもしれません。たとえば、テンプレートシステムを単体で使いたい場合、設定モジュールを示すような環境変数は設定したくないでしょう。
こういったケースのため、Djangoでは以下の関数を呼ぶことで手動で設定できるようになっています。
-
django.conf.settings.configure(default_settings, **settings)¶
実装例:
from django.conf import settings
settings.configure(DEBUG=True)
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のデフォルトを完全に 置き換える ため、インポートしているコードで使用される可能性のあるすべての設定に対して値を指定する必要があることに注意してください。全リストは django.conf.settings.global_settings を参照してください。
configure() と DJANGO_SETTINGS_MODULE は片方だけが必要¶
環境変数 DJANGO_SETTINGS_MODULE を設定していない場合、設定を読み込むコードを使用する前に configure() を呼び出す 必要があります 。
DJANGO_SETTINGS_MODULE を設定せず、 configure() を呼び出さない場合、 Django は設定に初めてアクセスしたときに ImportError 例外を発生させます。
DJANGO_SETTINGS_MODULE を設定し、何らかの方法で設定値にアクセスし、 その後に configure() を呼び出すと、Django は設定が既に設定されていることを示す RuntimeError を送出します。このためのプロパティがあります:
-
django.conf.settings.configured¶
例:
from django.conf import settings
if not settings.configured:
settings.configure(myapp_defaults, DEBUG=True)
また、 configure() を2回以上呼び出したり、設定にアクセスした後に configure() を呼び出したりするとエラーになります。
結論はこうです： configure() と DJANGO_SETTINGS_MODULE のどちらか片方だけを使ってください。両方使うのも、両方使わないのもいけません。
スタンドアロンで Django を使うには django.setup() を呼び出す必要がある¶
Django のコンポーネントを "スタンドアロン" で使う場合、たとえば、 Django テンプレートを読み込んでレンダリングする Python スクリプトを書いたり、 ORM を使ってデータを取得したりする場合、設定の他にもう一つ必要なステップがあります。
DJANGO_SETTINGS_MODULE を設定するか、 configure() を呼び出したら、 django.setup() を呼び出して設定をロードし、 Django のアプリケーションレジストリに入力する必要があります。たとえば、以下のようにします:
import django
from django.conf import settings
from myapp import myapp_defaults
settings.configure(default_settings=myapp_defaults, DEBUG=True)
django.setup()
# Now this script or any imported module can use any part of Django it needs.
from myapp import models
django.setup() を呼び出す必要があるのは、あなたのコードが本当にスタンドアロンである場合だけだということに注意してください。ウェブサーバから起動された場合、あるいは django-admin から起動された場合は、Django がこの処理を行います。
django.setup() は一度しか呼び出せません。
そのため、再利用可能なアプリケーションロジックをスタンドアロンスクリプトに置いて、アプリケーションの他の場所でそのスクリプトからインポートしなければならないようにするのは避けてください。それを避けられない場合は、下記のように django.setup() の呼び出しを if ブロックの中に入れてください:
if __name__ == "__main__":
import django
django.setup()
参考
- 設定のリファレンス
- コア・アプリと contlib アプリの設定の完全なリストを記載しています。
