Настройки 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)]
    
  • Он может импортировать значения из других файлов настроек.

Назначение настроек

DJANGO_SETTINGS_MODULE

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

Значение DJANGO_SETTINGS_MODULE должно быть в синтаксисе пути Python, например, mysite.settings. Обратите внимание, что модуль настроек должен находиться на Python import search 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 mod_wsgi documentation для получения дополнительной информации и других общих элементов для WSGI-приложения Django.

Настройки по умолчанию

Файл настроек 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!

Единственное место, куда следует назначать настройки, - это файл настроек.

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

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

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

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

Создание собственных настроек

Ничто не мешает вам создавать свои собственные настройки для своих 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 сделает это за вас.

django.setup() может быть вызван только один раз.

Поэтому избегайте размещения многократно используемой логики приложения в автономных скриптах, чтобы вам не пришлось импортировать из скрипта в другом месте вашего приложения. Если вы не можете этого избежать, поместите вызов django.setup() внутри блока if:

if __name__ == "__main__":
    import django

    django.setup()

См.также

The Settings Reference
Содержит полный список настроек основных и дополнительных приложений.
Вернуться на верх