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

В некоторых случаях вам может потребоваться обойти переменную окружения 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()