Настройки 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 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. Пример:

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

django.conf.settings.configured

Например:

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()