Настройки 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, указывая, что настройки уже были сконфигурированы. Для этого есть свойство:

django.conf.settings.configured

Например:

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