Настройки Django

Файл настроек Django содержит полную конфигурацию установленного проекта. Этот раздел описывает какие настройки доступны и как они работают.

Основы

Файл настроек – это просто модуль Python с переменными модуля.

Вот пример настроек:

ALLOWED_HOSTS = ['www.example.com']
DEBUG = False
DEFAULT_FROM_EMAIL = 'webmaster@example.com'

Примечание

Если установить False в DEBUG, вам также необходимо правильно определить ALLOWED_HOSTS.

Так как файл настроек это модуль Python, верно следующее:

  • Не допускаются ошибки синтаксиса Python.

  • Можно динамически определять настройки, используя обычный синтаксис Python. Например:

    MY_SETTING = [str(i) for i in range(30)]
    
  • Можно импортировать значения из других файлов настроек.

Определения файла настроек

DJANGO_SETTINGS_MODULE

При использовании Django необходимо указать какие настройки вы используете. Используйте для этого переменную окружения DJANGO_SETTINGS_MODULE.

Значение DJANGO_SETTINGS_MODULE должно содержать путь импорта Python, например mysite.settings. Обратите внимание, модуль с настройками должен быть доступен для импорта.

Использование django-admin

При использовании django-admin вы можете один раз определить переменную окружения, или каждый раз явно указывать модуль с настройками.

Например (Unix Bash shell):

export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver

Например (Windows shell):

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 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. Например:

from django.conf import settings

if settings.DEBUG:
    # Do something

Обратите внимание, django.conf.settings – это не модуль, а объект. По этому нельзя импортировать отдельные настройки:

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

Также ваш код не должен использовать непосредственно global_settings или ваш модуль настроек. django.conf.settings предоставляет единый интерфейс работы с настройками, реализуя концепцию настроек по умолчанию и настроек проекта. Также разделяет код, который использует настройки, и сами настройки.

Изменяем настройки в процессе работы

Вам не следует менять настройки в процессе работы приложения. Например, не делайте следующее в представлении:

from django.conf import settings

settings.DEBUG = True   # Don't do this!

Единственное место, где вы можете определять настройки – это файл с настройками.

Безопасность

Файл настроек содержит конфиденциальную информацию, например, как пароль к базе данных, вы должны хранить его в безопасности. Например, поменяйте права доступа к файлу, чтобы только вы и пользователь веб-сервера имел к нему доступ. Это особенно важно для хостингов с общим окружением.

Доступные настройки

Полный список настроек смотрите в разделе о настройках.

Добавление собственных настроек

Вы можете добавлять настройки для ваших приложений Django. Просто следуйте правилам:

  • Названия настроек должны быть в верхнем регистре.

  • Не изобретайте заново существующие настройки.

Для настроек, которые представляют множество, Django использует кортеж вместо списка, но это это не обязательно.

Использование настроек без DJANGO_SETTINGS_MODULE

В некоторых случаях вы можете не использовать переменную окружения DJANGO_SETTINGS_MODULE. Например, если вы используете систему шаблонов без Django, вряд ли вы захотите настраивать переменную окружения для настроек.

В этом случае вы можете явно определить настройки 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, вы можете указать аргумент default_settings (или первый аргумент) при вызове configure(), который содержит модуль или класс со значениями по умолчанию.

В этом примере настройки по умолчанию загружаются с myapp_defaults, и настройка DEBUG равна True, несмотря на значение из myapp_defaults:

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, указывая, что настройки уже определены. Для проверки этого существует свойство settings.configured.

Например:

from django.conf import settings
if not settings.configured:
    settings.configure(myapp_defaults, DEBUG=True)

Также нельзя вызывать configure() несколько раз, или вызывать configure() после обращения к настройкам.

Все сводится к правилам: используйте configure(), или DJANGO_SETTINGS_MODULE. Не оба, и хотя бы один.

См.также

Список настроек

Содержит полный список основных настроек и настроек встроенных приложений.