Настройки 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 mod_wsgi для получения дополнительной информации и других общих элементов 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!

Единственное место, где вы должны назначать значения настройкам, — это файл настроек.

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

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

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

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

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

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