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