Django settings

Django settings

Django的settings文件包含Django应用的所有配置项。该文档会介绍settings是如何运行，以及有哪些设置项是可用的。

基础

配置文件只是一个使用模块级变量的一个Python模块。

一组配置例子:

ALLOWED_HOSTS = ['www.example.com']
DEBUG = False
DEFAULT_FROM_EMAIL = 'webmaster@example.com'

Note

If you set DEBUG to False, you also need to properly setthe ALLOWED_HOSTS setting.

因为配置文件是Python模块，所以要注意以下几项:

不能有Python语法错误
可以用Python语法实现动态配置，例如:

MY_SETTING = [str(i) for i in range(30)]

可以从其他配置文件中引入变量

指定配置文件

DJANGO_SETTINGS_MODULE
使用Django时要通知Django当前使用的是哪个配置文件。可以改变环境变量 DJANGO_SETTINGS_MODULE 实现这一点。

DJANGO_SETTINGS_MODULE 的值是一个符合Python语法的路径，比如 mysite.settings 。要注意settings模块应该在Python可搜索到的路径中 import search path.

The django-admin utility

When using django-admin, you can either set theenvironment variable once, or explicitly pass in the settings module each timeyou run the utility.

例子（Unix Bash shell）:

export DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver

例子（Windows shell）:

set DJANGO_SETTINGS_MODULE=mysite.settings
django-admin runserver

使用 —settings 命令行参数指定配置模块路径:

django-admin runserver --settings=mysite.settings

On the server (mod_wsgi)

在服务器环境下，要通知WSGI应用当前使用的是哪个配置文件，用到 os.environ:

import os
 
os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'

阅读 Django mod_wsgi documentation 了解更多关于Django WSGI应用的信息和相关设置。

默认配置

在无需配置的情况下，Django配置文件没必要定义任何配置项。因为每个配置项都有一个明确的默认值。默认值都保存在模块 django/conf/global_settings.py 中。

Django按如下算法编译配置模块:

从 global_settings.py 中加载配置项
从指定的配置文件中加载配置项, 覆盖对应的全局配置项.注意: 配置文件中不要再重复引用 global_settings , 因为这样做是多余的.

查看你已经更改了哪个配置项

查看你修改了哪几个配置项很容易, 在命令行输入 python manage.py diffsettings 就会显示当前配置与默认配置中的不同.

想了解更多, 可以查看 diffsettings 文档.

在Python代码中使用settings

在具体的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 整合了默认配置和网站指定配置, 从而只提供一个接口读取配置. 它也解耦了使用自定义配置文件的代码.

运行时更改设置

不建议在运行时更改设置. 比如, 不要在view中这样用:

from django.conf import settings
 
settings.DEBUG = True   # Don't do this!

应该只在settings文件中更改设置.

安全

由于配置文件包含敏感信息, 比如数据库密码, 所以应该限制对配置文件的访问. 比如更改文件权限, 从而只能令你和你的WEB服务器能读取配置文件. 这在共享主机的环境中非常重要!

可用的配置项

查看 settings reference 了解完整的配置项列表.

创建你自己的配置文件

There's nothing stopping you from creating your own settings, for your ownDjango apps. Just follow these guidelines:

Setting names must be all uppercase.
不要重新设置已存在的配置项.For settings that are sequences, Django itself uses lists, but this is onlya convention.

Using settings without setting DJANGO_SETTINGS_MODULE

某些场合中, 你想绕过 DJANGO_SETTINGS_MODULE 环境变量来进行配置. 比如, 你正在使用django自带的模板系统, 而你并不想使用环境变量指定某个具体的配置文件.

在这种情况下, 可以手动设定Django的配置项. 要用到下面这个方法:

django.conf.settings.configure(default_settings, **settings)
举例：

from django.conf import settings
 
settings.configure(DEBUG=True)

通过 configure() 可以设置任何配置项, 每个参数对应一个值. 参数名称必须大写, 而且参数名必须是真实存在. 没有在 configure() 中出现的设置项在随后用到时, 仍会使用默认值.

如果你并不想使用整个框架, 仅仅是其中一小部分时, 如上述这般配置Django是非常必要的. 事实上, 我们建议您这样做.

因此, 通过 settings.configure() 配置django时, 并不会对当前进程的环境变量做任何修改.（可以查看 TIME_ZONE 了解为什么要这么做）. 这意味着在上述情况下你仍然完全掌控着当前环境.

定制默认配置项

如果你实在不想使用 django.conf.global_settings, 而想自定义配置默认值, 你可以在调用 configure() 时使用 default_settings 参数(或是默认做为第一个参数传入). 该参数是一个提供默认值的模块或是类.

在下面这个例子中, 由 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 了解全部默认值.

Either configure() or DJANGO_SETTINGS_MODULE is required

在没有设置 DJANGOSETTINGS_MODULE 环境的情况下, 就 必须_ 在运行读取配置项的代码之前就调用 configure() .

如果你没有设置 DJANGO_SETTINGS_MODULE 也没有调用 configure() , 那么Django会在第一次访问配置项时抛出 ImportError 异常.

如果已经调了 DJANGO_SETTINGS_MODULE , 再调用 configure() 的话, Django也会抛出一个 RuntimeError 异常, 表明已经配置了settings.

例如:

from django.conf import settings
if not settings.configured:
    settings.configure(myapp_defaults, DEBUG=True)

重复调用 configure() 或是在访问任何一个配置项后再调用 configure() , 也会引起错误.

这意味着: 确保要使用 configure() 或 DJANGO_SETTINGS_MODULE 其中一个, 不要多, 也不要少.

Calling django.setup() is required for "standalone" Django usage

If you're using components of Django "standalone" — for example, writing aPython script which loads some Django templates and renders them, or uses theORM to fetch some data — there's one more step you'll need in addition toconfiguring settings.

After you've either set DJANGO_SETTINGS_MODULE or calledconfigure(), you'll need to call django.setup() to load yoursettings and populate Django's application registry. For example:

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

Note that calling django.setup() is only necessary if your code is trulystandalone. When invoked by your Web server, or through django-admin, Django will handle this for you.

django.setup() may only be called once.

Therefore, avoid putting reusable application logic in standalone scriptsso that you have to import from the script elsewhere in your application.If you can't avoid that, put the call to django.setup() inside anif block:

if __name__ == '__main__':
    import django
    django.setup()