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()