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