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 позаботится об этом за вас.