Настройки 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()