Настройки Django

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

Основы

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

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

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

Поскольку файл настроек — это модуль 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. Обратите внимание, что модуль настроек должен находиться в пути поиска импорта Python пути поиска импорта.

Утилита 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. Пример:

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.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, указывая, что настройки уже были сконфигурированы. Для этой цели есть свойство:

Например:

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

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

В итоге: используйте точно один из вариантов: configure() или DJANGO_SETTINGS_MODULE. Не оба и не ни один.

Вызов django.setup() требуется для автономного использования Django

Если вы используете компоненты Django автономно — например, пишете скрипт Python, который загружает некоторые шаблоны Django и отображает их, или используете 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 обработает это за вас.

if __name__ == '__main__':
    import django
    django.setup()