附录 E 配置参考

你的 Django 设置文件包含了所有的 Django 安装配置。本附录解释了如何设置去使它工作以及哪些设置是有效的。

注意

随着 Django 的发展，它有时候需要添加或改变（很少）一些 settings ，你应该经常去查看在线的settings 文档（ http://www.djangoproject.com/documentation/0.96/settings/ ），了解最新的信息。

什么是 settings 文件

一个 settings 文件 只是一个有一些模块级变量的 Python 模块。这里是一些 settings 例子：

DEBUG = False

DEFAULT_FROM_EMAIL = 'webmaster@example.com'

TEMPLATE_DIRS = ('/home/templates/mike', '/home/templates/john') 因为一个 settings 文件是一个 python 模块，必须符合下面的一些的规则：它必须是合法的 python 代码，不允许语法错误。

可以通过正常的 python 语法给 settings 动态赋值，比如： MY_SETTING = [str(i) for i in range(30)]

它可以从其他 settings 文件导入值。

默认 Settings

一个 django Settings 可以为空,如果你不需要的话。每一个 Settings 有一个切合实际的默认值，这些默认值值在文件 django/conf/global_settings.py 里。

下面是 django 在编译 settings 文件时运用的规则：

指派 Settings: DJANGO_SETTINGS_MODULE

当你使用 Django 的时候，你必须告诉它你用的哪个 settings （配置），你可以通过设置

DJANGO_SETTINGS_MODULE 环境变量来完成。

DJANGO_SETTINGS_MODULE 的值应该在 Python path 中（例如， mysite.settings ）。注意，

settings 模块应该在 Python import 的搜索路径（ PYTHONPATH ）之中。提示：

关于 PYTHONPATH 的指导文档可以在

http://diveintopython.org/getting_to_know_python/everything_is_an_object.html 找到。

django-admin.py 工具

当使用 django-admin.py （见附录 G）时，你可以一次性设置环境变量或者在每次运行这个工具时于 settings 模块中明确指明。

这是一个使用 Unix Bash Shell 的例子：

export DJANGO_SETTINGS_MODULE=mysite.settings django-admin.py runserver

这是一个使用 Windows 命令行的例子：

set DJANGO_SETTINGS_MODULE=mysite.settings django-admin.py runserver

使用 --settings 命令行参数来手工指明 settings： django-admin.py runserver --settings=mysite.settings

由 startproject 创建的作为工程骨架一部分的 manage.py 工具会自动设置 DJANGO_SETTINGS_MODULE` ；关于 manage.py 的详细说明见附录 G。

服务器端(mod_python)

在你的实际服务器环境中，你需要告诉 Apache/mod_python 使用哪一个 settings 文件。通过 SetEnv ：

<Location "/mysite/"> SetHandler python-program

PythonHandler django.core.handlers.modpython SetEnv DJANGO_SETTINGS_MODULE mysite.settings

</Location>

要了解更详细的信息，请阅读 Django mod_python 在线手册

http://www.djangoproject.com/documentation/0.96/modpython/ 。

不设置 DJANGO_SETTINGS_MODULE 而使用 Settings

有些情况下，你可能想绕过 DJANGO_SETTINGS_MODULE 环境变量。例如，如果你正在使用独立的模板系统，你很可能不想设置指向 settings 模块的环境变量。

这在些情况下，你可以手工设置 Django 的 settings，通过

django.conf.settings.configure() 。这里有一个例子： from django.conf import settings

settings.configure( DEBUG = True,

TEMPLATE_DEBUG = True, TEMPLATE_DIRS = [

'/home/web-apps/myapp', '/home/web-apps/base',

]

)

Pass configure() as many keyword arguments as youd like, with each keyword argument representing a setting and its value. Each argument name should be all uppercase, with the same name as the settings described earlier. If a particular setting is not passed to configure() and is needed at some later point, Django will use the default setting value.

Configuring Django in this fashion is mostly necessary and, indeed, recommended when youre using a piece of the framework inside a larger application.

Consequently, when configured via settings.configure() , Django will not make any modifications to the process environment variables. (See the explanation of TIME_ZONE later in this appendix for why this would normally occur.) Its assumed that youre already in full control of your environment in these cases.

定制默认的 Settings

如果你想从 django.conf.global_settings 以外的地方获得默认设置，你可以传入一个提供默认设置当作 default_settings 的参数（或者当作第一个参数) 到回调函数 configure()。

在下面的列子中，默认设置是是从 myapp_defaults 获取的，且 DEBUG 是设置为 True, regardless of its value in myapp_defaults :

from django.conf import settings from myapp import myapp_defaults

settings.configure(default_settings=myapp_defaults, DEBUG=True)下面的例子是等价的：

settings.configure(myapp_defaults, DEBUG = True)

Normally, you will not need to override the defaults in this fashion. The Django defaults are sufficiently tame that you can safely use them. Be aware that if you do pass in a new default module, it entirely replaces the Django defaults, so you must specify a value for every possible setting that might be used in that code you are importing. Check in django.conf.settings.global_settings for the full list.

configure()或 DJANGO_SETTINGS_MODULE 之一是必须的

If youre not setting the DJANGO_SETTINGS_MODULE environment variable, you must call configure() at some point before using any code that reads settings.

If you dont set DJANGO_SETTINGS_MODULE and dont call configure() , Django will raise an EnvironmentError exception the first time a setting is accessed.

If you set DJANGO_SETTINGS_MODULE , access settings values somehow, and then call configure() , Django will raise an EnvironmentError stating that settings have already been configured.

Also, its an error to call configure() more than once, or to call configure() after any setting has been accessed.

It boils down to this: use exactly one of either configure() or DJANGO_SETTINGS_MODULE . Not both, and not neither.

合法的 Settings

下面章节包括全部有效 setting 项（按字母顺序排序）及其默认值的一个完整列表。

ABSOLUTE_URL_OVERRIDES

默认 : {} (empty dictionary) 000000000000000000000000000000

ABSOLUTE_URL_OVERRIDES = {

'blogs.weblog': lambda o: "/blogs/%s/" % o.slug,

'news.story': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),

}

Note that the model name used in this setting should be all lowercase, regardless of the case of the actual model class name.

ADMIN_FOR

默认 : () (empty list)

This setting is used for admin site settings modules. It should be a tuple of settings modules (in the format 'foo.bar.baz' ) for which this site is an admin.

The admin site uses this in its automatically introspected documentation of models, views, and template tags.

ADMIN_MEDIA_PREFIX

默认 : '/media/'

This setting is the URL prefix for admin media: CSS, JavaScript, and images. Make sure to use a trailing slash.

ADMINS

默认 : () (empty tuple)

This is a tuple that lists people who get code error notifications. When DEBUG=False and a view raises an exception, Django will email these people with the full exception information. Each member of the tuple should be a tuple of (Full name, e-mail address), for example:

(('John', 'john@example.com'), ('Mary', 'mary@example.com'))

Note that Django will email all of these people whenever an error happens.

ALLOWED_INCLUDE_ROOTS

默认 : () (empty tuple)

This is a tuple of strings representing allowed prefixes for the {% ssi %} template tag. This is a security measure, so that template authors cant access files that the y shouldnt be accessing.

For example, if ALLOWED_INCLUDE_ROOTS is ('/home/html', '/var/www') , then {% ssi

/home/html/foo.txt %} would work, but {% ssi /etc/passwd %} wouldnt.

APPEND_SLASH

默认 : True

当此设置项为 True 的时候，系统会自动在 URL 的尾部加上一个反斜杠’/’。这个设置项仅仅在安装了``CommonMiddleware``的状态下使用（详见第 15 章）的``PREPEND_WWW``

CACHE_BACKEND

默认 : 'simple://'

指定使用的缓存后端（见第 13 章）。

CACHE_MIDDLEWARE_KEY_PREFIX

默认 : '' (empty string)

This is the cache key prefix that the cache middleware should use (see Chapter 13).

DATABASE_ENGINE

默认 : '' (empty string)

该设置用于指定使用下列哪种数据库作为存储后端: 'postgresql_psycopg2' , 'postgresql' , 'mysql' , 'mysql_old' or 'sqlite3' .

DATABASE_HOST

默认 : '' (empty string)

该设置指定连接数据库时所使用的主机。空字符串表示``localhost`` 。如果你使用SQLite，则不用设置该值。

如果你在使用 MySQL，而这个值是以反斜线('/' )开头，那么 MySQL 将通过指定的 Unix socket进行连接：

DATABASE_HOST = '/var/run/mysql'

如果你在使用 MySQL，而这个值又没有以反斜线开头，那么这个值就被视为是主机。

DATABASE_NAME

默认 : '' (empty string)

该设置为所使用数据库的名称。如果使用 SQLite，该设置为数据库文件的完整路径。

DATABASE_OPTIONS

默认 : {} (empty dictionary)

This is extra parameters to use when connecting to the database. Consult the back-end modules document for available keywords.

DATABASE_PASSWORD

默认 : '' (empty string)

该设置为数据库连接密码。如果使用 SQLite，则不用设置。

DATABASE_PORT

默认 : '' (empty string)

这是用来连接数据库的端口. 空字符代表缺省端口. SQLite 不用设置.

DATABASE_USER

默认 : '' (empty string)

该设置为连接数据库的用户名。当使用 SQLite 时无效。

DATE_FORMAT

默认 : 'N j, Y' (e.g., Feb. 4, 2003 )

This is the default formatting to use for date fields on Django admin change-list pages and, possibly, by other parts of the system. It accepts the same format as the now tag (see Appendix F, Table F-2).

另见 DATETIME_FORMAT , TIME_FORMAT , YEAR_MONTH_FORMAT , 和 MONTH_DAY_FORMAT .

DATETIME_FORMAT

默认 : 'N j, Y, P' (例如, Feb. 4, 2003, 4 p.m. )

This is the default formatting to use for datetime fields on Django admin change-list pages and, possibly, by other parts of the system. It accepts the same format as the now tag (see Appendix F, Table F-2).

另见 DATE_FORMAT , DATETIME_FORMAT , TIME_FORMAT , YEAR_MONTH_FORMAT , 和 MONTH_DAY_FORMAT .

DEBUG

默认 : False

This setting is a Boolean that turns debug mode on and off.

If you define custom settings, django/views/debug.py has a HIDDEN_SETTINGS regular expression that will hide from the DEBUG view anything that contains 'SECRET , PASSWORD , or PROFANITIES' . This allows untrusted users to be able to give backtraces without seeing sensitive (or offensive) settings.

Still, note that there are always going to be sections of your debug output that are inappropriate for public consumption. File paths, configuration options, and the like

all give attackers extra information about your server. Never deploy a site with DEBUG turned on.

DEFAULT_CHARSET

默认 : 'utf-8'

This is the default charset to use for all HttpResponse objects, if a MIME type isnt manually specified. It is used with DEFAULT_CONTENT_TYPE to construct the Content-Type header. See Appendix H for more about HttpResponse objects.

DEFAULT_CONTENT_TYPE

默认 : 'text/html'

This is the default content type to use for all HttpResponse objects, if a MIME type isnt manually specified. It is used with DEFAULT_CHARSET to construct the Content-Type header. See Appendix H for more about HttpResponse objects.

DEFAULT_FROM_EMAIL

默认 : 'webmaster@localhost'

This is the default email address to use for various automated correspondence from the site manager(s).

DISALLOWED_USER_AGENTS

默认 : () (empty tuple)

This is a list of compiled regular expression objects representing User-Agent strings that are not allowed to visit any page, systemwide. Use this for bad robots/crawlers. This is used only if CommonMiddleware is installed (see Chapter 15).

EMAIL_HOST

默认 : 'localhost'

This is the host to use for sending email. See also EMAIL_PORT .

EMAIL_HOST_PASSWORD

默认 : '' (empty string)

This is the password to use for the SMTP server defined in EMAIL_HOST . This setting is used in conjunction with EMAIL_HOST_USER when authenticating to the SMTP server. If either of these settings is empty, Django wont attempt authentication.

另见 EMAIL_HOST_USER .

EMAIL_HOST_USER

默认 : '' (empty string)

This is the username to use for the SMTP server defined in EMAIL_HOST . If its empty, Django wont attempt authentication. See also EMAIL_HOST_PASSWORD .

EMAIL_PORT

默认 : 25

This is the port to use for the SMTP server defined in EMAIL_HOST .

EMAIL_SUBJECT_PREFIX

默认 : '[Django] '

This is the subject-line prefix for email messages sent with django.core.mail.mail_admins or django.core.mail.mail_managers . Youll probably want to include the trailing space.

FIXTURE_DIRS

默认 : () (empty tuple)

This is a list of locations of the fixture data files, in search order. Note that these paths should use Unix-style forward slashes, even on Windows. It is used by Djangos testing framework, which is covered online at http://www.djangoproject.com/documentation/0.96/testing/.

IGNORABLE_404_ENDS

默 认 : ('mail.pl', 'mailform.pl', 'mail.cgi', 'mailform.cgi', 'favicon.ico', '.php')

另见 IGNORABLE_404_STARTS 和 Error reporting via e-mail .

IGNORABLE_404_STARTS

默认 : ('/cgi-bin/', '/_vti_bin', '/_vti_inf')

This is a tuple of strings that specify beginnings of URLs that should be ignored by the 404 emailer. See also SEND_BROKEN_LINK_EMAILS and IGNORABLE_404_ENDS .

INSTALLED_APPS

默认 : () (empty tuple)

A tuple of strings designating all applications that are enabled in this Django installation. Each string should be a full Python path to a Python package that contains a Django application. See Chapter 5 for more about applications.

INTERNAL_IPS

默认 : () (empty tuple)

A tuple of IP addresses, as strings, that

• See debug comments, when DEBUG is True

• Receive X headers if the XViewMiddleware is installed (see Chapter 15)

  JING_PATH

  默认 : '/usr/bin/jing'

  This is the path to the Jing executable. Jing is a RELAX NG validator, and Django uses it to validate each XMLField in your models. See http://www.thaiopensource.com/relaxng/jing.html.

  LANGUAGE_CODE

  默认 : 'en-us'

  This is a string representing the language code for this installation. This should be in standard language format for example, U.S. English is "en-us" . See Chapter 18.

  LANGUAGES

  Default : A tuple of all available languages. This list is continually growing and any copy included here would inevitably become rapidly out of date. You can see the current list of translated languages by looking in django/conf/global_settings.py .

  The list is a tuple of two-tuples in the format (language code, language name) for example, ('ja', 'Japanese') . This specifies which languages are available for language selection. See Chapter 18 for more on language selection.

  Generally, the default value should suffice. Only set this setting if you want to restrict language selection to a subset of the Django-provided languages.

  If you define a custom LANGUAGES setting, its OK to mark the languages as translation strings, but you should never import django.utils.translation from within your settings file, because that module in itself depends on the settings, and that would cause a circular import.

  The solution is to use a dummy gettext() function. Heres a sample settings file: gettext = lambda s: s

  LANGUAGES = (

  ('de', gettext('German')),

  ('en', gettext('English')),

  )

  With this arrangement, make-messages.py will still find and mark these strings for translation, but the translation wont happen at runtime so youll have to remember to wrap the languages in the real gettext() in any code that uses LANGUAGES at runtime.

  MANAGERS

  默认 : () (empty tuple)

  This tuple is in the same format as ADMINS that specifies who should get broken-link notifications when SEND_BROKEN_LINK_EMAILS=True .

  MEDIA_ROOT

  默认 : '' (empty string)

  This is an absolute path to the directory that holds media for this installation ( e.g., "/home/media/media.lawrence.com/" ). See also MEDIA_URL .

  MEDIA_URL

  默认 : '' (empty string)

  This URL handles the media served from MEDIA_ROOT (e.g., "http://media.lawrence.com" ).

  Note that this should have a trailing slash if it has a path component:

• 正确 : "http://www.example.com/static/"

• 错误 : "http://www.example.com/static"

MIDDLEWARE_CLASSES

默认 :

("django.contrib.sessions.middleware.SessionMiddleware", "django.contrib.auth.middleware.AuthenticationMiddleware", "django.middleware.common.CommonMiddleware", "django.middleware.doc.XViewMiddleware")

This is a tuple of middleware classes to use. See Chapter 15.

MONTH_DAY_FORMAT

默认 : 'F j'

This is the default formatting to use for date fields on Django admin change-list pages and, possibly, by other parts of the system in cases when only the month and day are displayed. It accepts the same format as the now tag (see Appendix F, Table F-2).

For example, when a Django admin change-list page is being filtered by a date, the header for a given day displays the day and month. Different locales have different formats. For example, U.S. English would have January 1, whereas Spanish might have

1 Enero.

另见 DATE_FORMAT , DATETIME_FORMAT , TIME_FORMAT , 和 YEAR_MONTH_FORMAT .

PREPEND_WWW

默认 : False

This setting indicates whether to prepend the www. subdomain to URLs that dont have it. This is used only if CommonMiddleware is installed (see the Chapter 15). See also APPEND_SLASH .

PROFANITIES_LIST

This is a tuple of profanities, as strings, that will trigger a validation error when the hasNoProfanities validator is called.

We dont list the default values here, because that might bring the MPAA ratings board down on our heads. To view the default values, see the file django/conf/global_settings.py .

ROOT_URLCONF

默认 : Not defined

This is a string representing the full Python import path to your root URLconf (e.g., "mydjangoapps.urls" ). See Chapter 3.

SECRET_KEY

默认 : (当你创建一个项目时自动生成)

This is a secret key for this particular Django installation. It is used to provide a seed in secret-key hashing algorithms. Set this to a random string the longer, the better. django-admin.py startproject creates one automatically and most of the time you wont need to change it

SEND_BROKEN_LINK_EMAILS

默认 : False

This setting indicates whether to send an email to the MANAGERS each time somebody visits a Django-powered page that is 404-ed with a nonempty referer (i.e., a broken link). This is only used if CommonMiddleware is installed (see Chapter 15). See also IGNORABLE_404_STARTS and IGNORABLE_404_ENDS .

SERIALIZATION_MODULES

默认 : Not defined.

Serialization is a feature still under heavy development. Refer to the online documentation at http://www.djangoproject.com/documentation/0.96/serialization/ for more information.

SERVER_EMAIL

默认 : 'root@localhost'

This is the email address that error messages come from, such as those sent to ADMINS and MANAGERS .

SESSION_COOKIE_AGE

默认 : 1209600 (两周，以秒计)

This is the age of session cookies, in seconds. See Chapter 12.

SESSION_COOKIE_DOMAIN

默认 : None

This is the domain to use for session cookies. Set this to a string such as ".lawrence.com" for cross-domain cookies, or use None for a standard domain cookie. See Chapter 12.

SESSION_COOKIE_NAME

默认 : 'sessionid'

This is the name of the cookie to use for sessions; it can be whatever you want. See Chapter 12.

SESSION_COOKIE_SECURE

默认 : False

This setting indicates whether to use a secure cookie for the session cookie. If this is set to True , the cookie will be marked as secure, which means browsers may ensure that the cookie is only sent under an HTTPS connection. See Chapter 12.

SESSION_EXPIRE_AT_BROWSER_CLOSE

默认 : False

This setting indicates whether to expire the session when the user closes his browser. See Chapter 12.

SESSION_SAVE_EVERY_REQUEST

默认 : False

This setting indicates whether to save the session data on every request. See Chapter 12.

SITE_ID

默认 : Not defined

这就是在“django_site”数据库表中当前网站的整数 ID。它常用于应用程序数据能够挂钩到指定的网站，或单个数据库上能管理多个网站的内容。参见第 14 章。

TEMPLATE_CONTEXT_PROCESSORS

默认 :

("django.core.context_processors.auth", "django.core.context_processors.debug", "django.core.context_processors.i18n")

This is a tuple of callables that are used to populate the context in RequestContext . These callables take a request object as their argument and return a dictionary of items to be merged into the context. See Chapter 10.

TEMPLATE_DEBUG

默认 : False

This Boolean turns template debug mode on and off. If it is True , the fancy error page will display a detailed report for any TemplateSyntaxError . This report contains the relevant snippet of the template, with the appropriate line highlighted.

Note that Django only displays fancy error pages if DEBUG is True , so youll want to set that to take advantage of this setting.

另见 DEBUG .

TEMPLATE_DIRS

默认 : () (empty tuple)

This is a list of locations of the template source files, in search order. Note that these paths should use Unix-style forward slashes, even on Windows. See Chapters 4 and 10.

TEMPLATE_LOADERS

默认 : ('django.template.loaders.filesystem.load_template_source',)

This is a tuple of callables (as strings) that know how to import templates from various sources. See Chapter 10.

TEMPLATE_STRING_IF_INVALID

默认 : '' (Empty string)

This is output, as a string, that the template system should use for invalid (e.g., misspelled) variables. See Chapter 10.

TEST_RUNNER

默认 : 'django.test.simple.run_tests'

This is the name of the method to use for starting the test suite. It is used by Djangos testing framework, which is covered online at http://www.djangoproject.com/documentation/0.96/testing/.

TEST_DATABASE_NAME

默认 : None

This is the name of database to use when running the test suite. If a value of None is specified, the test database will use the name 'test_' + settings.DATABASE_NAME . See the documentation for Djangos testing framework, which is covered online at http://www.djangoproject.com/documentation/0.96/testing/.

TIME_FORMAT

默认 : 'P' (e.g., 4 p.m. )

This is the default formatting to use for time fields on Django admin change-list pages and, possibly, by other parts of the system. It accepts the same format as the now tag (see Appendix F, Table F-2).

另见 DATE_FORMAT , DATETIME_FORMAT , TIME_FORMAT , YEAR_MONTH_FORMAT , 和 MONTH_DAY_FORMAT .

TIME_ZONE

默认 : 'America/Chicago'

此字符串表示安装的时区。时区为 Unix 标准的 zic 格式。在 http://www.postgresql.org/docs/8.1/static/dateime-

keywords.html#DATETIME-TIMEZONE-SET-TABLE 上有一个相对完整的时区字符串列表。

This is the time zone to which Django will convert all dates/times not necessarily the time zone of the server. For example, one server may serve multiple Django-powered sites, each with a separate time-zone setting.

Normally, Django sets the os.environ['TZ'] variable to the time zone you specify in the TIME_ZONE setting. Thus, all your views and models will automatically operate in the correct time zone. However, if youre using the manually configuring settings (described above in the section titled Using Settings Without Setting

DJANGO_SETTINGS_MODULE), Django will not touch the TZ environment variable, and it will be up to you to ensure your processes are running in the correct environment.

注意

Django cannot reliably use alternate time zones in a Windows environment. If youre running Django on Windows, this variable must be set to match the system time zone.

URL_VALIDATOR_USER_AGENT

默认 : Django/<version> (http://www.djangoproject.com/)

This is the string to use as the User-Agent header when checking to see if URLs exist (see the verify_exists option on URLField ; see Appendix B).

USE_ETAGS

默认 : False

This Boolean specifies whether to output the ETag header. It saves bandwidth but slows down performance. This is only used if CommonMiddleware is installed (see Chapter 15).

USE_I18N

默认 : True

This Boolean specifies whether Djangos internationalization system (see Chapter 18) should be enabled. It provides an easy way to turn off internationalization, for performance. If this is set to False , Django will make some optimizations so as not to load the internationalization machinery.

YEAR_MONTH_FORMAT

默认 : 'F Y'

This is the default formatting to use for date fields on Django admin change-list pages and, possibly, by other parts of the system in cases when only the year and month are displayed. It accepts the same format as the now tag (see Appendix F).

For example, when a Django admin change-list page is being filtered by a date drill-down, the header for a given month displays the month and the year. Different

locales have different formats. For example, U.S. English would use January 2006, whereas another locale might use 2006/January.

另见 DATE_FORMAT , DATETIME_FORMAT , TIME_FORMAT , 和 MONTH_DAY_FORMAT .