===============
Django settings
===============

:作者: Django 团队
:译者: weizhong2004@gmail.com
:翻译开始日期: 2006-04-04
:翻译完成日期: 2006-04-04
:修订日期: 2006-05-06
:原文版本: 2789

Django settings 文件包含你的 Django 安装的所有配置信息．本文档解释了 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 文件中导入值.

设置
=======

使用 Django 时, 你必须告诉它你使用的是哪个 settings . 要做到这一点，使用环境变量 ``DJANGO_SETTINGS_MODULE``.

``DJANGO_SETTINGS_MODULE`` 的值是一个 Python 路径, 举例来说 ``"mysite.settings"``. 注意 settings 模块应该在 Python `import 搜索路径`_ 中.

.. _import 搜索路径: http://diveintopython.org/getting_to_know_python/everything_is_an_object.html

django-admin.py 应用程序
---------------------------

使用 `django-admin.py`_ 时, 你可以一次性设定环境变量, 也可以在运行该程序时每次显式的将 settings 模块显式的传递给它.

例子 (Unix Bash shell)::

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

例子 (Windows shell)::

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

使用 ``--settings`` 命令行参数手工指定 settings ::

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

.. _django-admin.py: http://www.djangoproject.com/documentation/django_admin/

服务器环境 (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 文档`_ 以得到更多信息.

.. _Django mod_python 文档: http://www.djangoproject.com/documentation/modpython/

默认 settings
================

如果不需要, Django settings 文件可以不必定义任何 settings. 因为每个设置都有默认值. 这些默认值定义在 ``django/conf/global_settings.py``.

下面是 Django 使用 settings 的法则:

    * 从 ``global_settings.py`` 载入默认设置.
    * 从指定的 settings 文件载入用户设置, 需要时覆盖掉默认设置.

注意一个用户 settings 文件 *不必t* 导入 ``global_settings``, 这是多余的.

查看你改变了哪些设置
------------------------------------

有一个简单的办法可以查看你修改了哪些设置.命令 ``python manage.py diffsettings`` 显示当前 settings 文件与 Django 默认设置的不同之处.

参阅 `diffsettings documentation`_.

.. _diffsettings documentation: http://www.djangoproject.com/documentation/django_admin/#diffsettings


在你的代码中使用 settings 
=============================

通过从模块 ``django.conf.settings`` 导入你需要的变量, 你的代码可以访问这个变量. 例子::

    from django.conf.settings import DEBUG

    if DEBUG:
        # Do something

注意一定 *不要* 从 ``global_settings`` 或你自己的 settings 模块导入设置变量到你的代码. ``django.conf.settings`` 概括了默认设置和站点自定义设置的概念,它提供了一个统一的接口用于用户代码访问, 也降低了用户代码与用户设置的耦合程度.

在运行时修改 settings
============================

不应该在程序运行时修改 settings. 举例来说, 不要在一个 view 中做这样的事::

    from django.conf.settings import DEBUG

    DEBUG = True   # Don't do this!

你只应该在你的 settings 文件中设置 settings, 记住,这是原则.

安全性
========

由于 settings 文件包含敏感信息,象数据库密码等.你应该非常小心的设置它的访问权限. 举例来说,
你可以只允许你和 WEB 服务器用户阅读该文件.在一个共享主机环境时,这一点格外重要.

可用选项
===========

下面是所有可用选项的列表及它们的默认值(按字母顺序排列).

ABSOLUTE_URL_OVERRIDES
----------------------

默认值: ``{}`` (空字典)

一个字典映射 ``"app_label.module_name"`` 字符串到一个函数, 该函数接受一个model对象作为参数并返回它的 URL. 这是在一个安装上覆盖 ``get_absolute_url()`` 方法的一种方式. 例子::

    ABSOLUTE_URL_OVERRIDES = {
        'blogs.blogs': lambda o: "/blogs/%s/" % o.slug,
        'news.stories': lambda o: "/stories/%s/%s/" % (o.pub_year, o.slug),
    }

ADMIN_FOR
---------

默认值: ``()`` (空的tuple)

用于 admin-site settings 模块, 若当前站点是 admin ,它则是一个由 settings 模块组成的 tuple (类似 ``'foo.bar.baz'`` 这样的格式).

admin 站点在 models, views,及 template tags 的自动内省的文档中使用该设置.

ADMIN_MEDIA_PREFIX
------------------

默认值: ``'/media/'``

The URL prefix for admin media -- CSS, JavaScript and images. Make sure to use
a trailing slash.

ADMINS
------

默认值: ``()`` (空的 tuple)

一个2-元素tuple的 tuple. 列出了有权接收代码错误提示的人. 当 ``DEBUG=False`` 时,一个 view 引发了异常, Django 会将详细异常信息用电子邮件的方式发送给这些人. 该tuple的每个成员应该是这种格式: (Full name, e-mail address). 例子::

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

ALLOWED_INCLUDE_ROOTS
---------------------

默认值: ``()`` (空的 tuple)

一个字符串tuple, 只有以列表中的元素为前缀的模板Django才可以以``{% ssi %}`` 形式访问 . 出于安全考虑, 在不应该访问时,即使是模板的作者也不能访问这些文件.

举例来说, 若 ``ALLOWED_INCLUDE_ROOTS`` 是 ``('/home/html', '/var/www')``,
那么 ``{% ssi /home/html/foo.txt %}`` 可以正常工作, 不过 ``{% ssi /etc/passwd %}`` 却不能.

APPEND_SLASH
------------

默认值: ``True``

是否给URL添加一个结尾的斜线. 只有安装了 ``CommonMiddleware`` 之后,该选项才起作用. (参阅 `middleware 文档`_). 参阅
``PREPEND_WWW``.

CACHE_BACKEND
-------------

默认值: ``'simple://'``

后端使用的 cache . 参阅 `cache docs`_.

CACHE_MIDDLEWARE_KEY_PREFIX

默认值: ``''`` (空的字符串)

cache 中间件使用的cache key 前缀. 参阅 `cache docs`_.

DATABASE_ENGINE
---------------

默认值: ``'postgresql'``

后端使用的数据库引擎:  ``'postgresql'``, ``'mysql'``,
``'sqlite3'`` 或 ``'ado_mssql'`` 中的任意一个.

DATABASE_HOST
-------------

默认值: ``''`` (空的字符串)

数据库所在的主机. 空的字符串意味着 localhost. SQLite 不需要该项.
如果你使用 MySQL 并且该选项的值以一个斜线 (``'/'``) 开始, MySQL 则通过一个 Unix socket 连接到指定的 socket. 比如::

    DATABASE_HOST = '/var/run/mysql'

如果你使用 MySQL 并且该选项的值 *不是* 以斜线开始, 那么该选项的值就是主机的名字.

DATABASE_NAME
-------------

默认值: ``''`` (空的字符串)

要使用的数据库名字. 对 SQLite, 它必须是一个数据库文件的全路径名字.

DATABASE_PASSWORD
-----------------

默认值: ``''`` (空的字符串)

连接数据库需要的密码. SQLite 不需要该项.

DATABASE_PORT
-------------

默认值: ``''`` (空的字符串)

连接数据库所需的数据库端口. 空的字符串表示默认端口. SQLite 不需要该项.

DATABASE_USER
-------------

默认值: ``''`` (空的字符串)

连接数据库时所需要的用户名. SQLite 不需要该项.

DATE_FORMAT
-----------

默认值: ``'N j, Y'`` (举例来说 ``Feb. 4, 2003``)

在 Django admin change-list 页对日期字段使用的默认日期格式, 系统中的其它部分也可能使用该格式. 参阅 `allowed date format strings`_.

参阅 DATETIME_FORMAT 和 TIME_FORMAT.

.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now

DATETIME_FORMAT
---------------

默认值: ``'N j, Y, P'`` (举例来说 ``Feb. 4, 2003, 4 p.m.``)

在 Django admin change-list 页对日期时间字段使用的默认日期时间格式, 系统中的其它部分也可能使用该格式. 参阅 `allowed date format strings`_.

参阅 DATE_FORMAT 和 TIME_FORMAT.

.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now

DEBUG
-----

默认值: ``False``

一个开关调试模式的逻辑值

DEFAULT_CHARSET
---------------

默认值: ``'utf-8'``

如果一个 MIME 类型没有人为指定, 对所有 ``HttpResponse`` 对象将应用该默认字符集. 使用 ``DEFAULT_CONTENT_TYPE`` 来构建 ``Content-Type`` 头.

DEFAULT_CONTENT_TYPE
--------------------

默认值: ``'text/html'``

如果一个 MIME 类型没有人为指定, 对所有 ``HttpResponse`` 对象将应用该默认 content type. 使用 ``DEFAULT_CHARSET`` 来构建 ``Content-Type`` 头.

DEFAULT_FROM_EMAIL
------------------

默认值: ``'webmaster@localhost'``

用于发送(站点自动生成的)管理邮件的默认 e-mail 邮箱.

DISALLOWED_USER_AGENTS
----------------------

默认值: ``()`` (空的 tuple)

一个编译的正则表达式对象列表,用于表示一些用户代理字符串.这些用户代理将被禁止访问系统中的任何页面.
使用这个对付页面机器人或网络爬虫.只有安装 ``CommonMiddleware`` 后这个选项才有用(参阅 `middleware 文档`_).

EMAIL_HOST
----------

默认值: ``'localhost'``

用来发送 e-mail 的主机. 参阅 ``EMAIL_PORT``.

EMAIL_HOST_PASSWORD
-------------------

默认值: ``''`` (空的字符串)

``EMAIL_HOST`` 中定义的 SMTP 服务器使用的密码. 如果为空, Django 不会尝试进行认证.

参阅 ``EMAIL_HOST_USER``.

EMAIL_HOST_USER
---------------

默认值: ``''`` (空的字符串)

``EMAIL_HOST`` 中定义的 SMTP 服务器使用的用户名. 如果为空, Django 不会尝试进行认证.

参阅 ``EMAIL_HOST_PASSWORD``.

EMAIL_PORT
----------

默认值: ``25``

``EMAIL_HOST`` 中指定的SMTP 服务器所使用的端口号.

EMAIL_SUBJECT_PREFIX
--------------------

默认值: ``'[Django] '``

``django.core.mail.mail_admins`` 或 ``django.core.mail.mail_managers`` 发送的邮件的主题前缀. 

ENABLE_PSYCO
------------

默认值: ``False``

如果允许 Psyco, 将使用Pscyo优化 Python 代码. 需要 Psyco_ 模块.

.. _Psyco: http://psyco.sourceforge.net/

IGNORABLE_404_ENDS
------------------

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

参阅 ``IGNORABLE_404_STARTS``.

IGNORABLE_404_STARTS
--------------------

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

一个字符串 tuple . 以该tuple中元素为开头的 URL 应该被 404 e-mailer 忽略. 参阅 ``SEND_BROKEN_LINK_EMAILS`` 和 ``IGNORABLE_404_ENDS``.

INSTALLED_APPS
--------------

默认值: ``()`` (空的 tuple)

一个字符串tuple ,内容是本 Django 安装中的所有应用. 每个字符串应该是一个包含Django应用程序的Python包的路径全称, `django-admin.py startapp`_ 会自动往其中添加内容.

.. _django-admin.py startapp: http://www.djangoproject.com/documentation/django_admin/#startapp-appname

INTERNAL_IPS
------------

默认值: ``()`` (空的 tuple)

一个 ip 地址的 tuple(字符串形式), 它:

    * 当 ``DEBUG`` 为 ``True`` 时,参阅调试务注解
    * 接收 X 头(若 ``XViewMiddleware`` 已安装), (参阅 `middleware 文档`_)

JING_PATH
---------

默认值: ``'/usr/bin/jing'``

"Jing" 执行文件路径全名. Jing 是一个 RELAX NG 校验器, Django 使用它对你的 model 的 ``XMLField`` 进行验证.
参阅 http://www.thaiopensource.com/relaxng/jing.html .

LANGUAGE_CODE
-------------

默认值: ``'en-us'``

表示默认语言的一个字符串. 必须是标准语言格式. 举例来说, U.S. English 就是 ``"en-us"``. 参阅
`internationalization docs`_.

.. _internationalization docs: http://www.djangoproject.com/documentation/i18n/

LANGUAGES
---------

默认值: 一个 tuple (内容为所有可用语言). 目前它的值是::

    LANGUAGES = (
        ('bn', _('Bengali')),
        ('cs', _('Czech')),
        ('cy', _('Welsh')),
        ('da', _('Danish')),
        ('de', _('German')),
        ('en', _('English')),
        ('es', _('Spanish')),
        ('fr', _('French')),
        ('gl', _('Galician')),
        ('is', _('Icelandic')),
        ('it', _('Italian')),
        ('no', _('Norwegian')),
        ('pt-br', _('Brazilian')),
        ('ro', _('Romanian')),
        ('ru', _('Russian')),
        ('sk', _('Slovak')),
        ('sr', _('Serbian')),
        ('sv', _('Swedish')),
        ('zh-cn', _('Simplified Chinese')),
    )

一个2-元素tuple<格式为 (语言代码, 语言名称)>的 tuple. 该设置用于选择可用语言.参阅
`internationalization docs`_ 了解细节.

通常这个默认值就足够了.除非你打算减少提供的语言数目,否则没必要修改这个设置.

MANAGERS
--------

默认值: ``ADMINS`` (不论 ``ADMINS`` 是否已经设置)

一个和 ``ADMINS`` 同样格式的 tuple , 当 ``SEND_BROKEN_LINK_EMAILS=True`` 时, 这些人有权接收死链接通知信息.

MEDIA_ROOT
----------

默认值: ``''`` (空的字符串)

一个绝对路径, 用于保存媒体文件. 例子: ``"/home/media/media.lawrence.com/"`` 参阅 ``MEDIA_URL``.

MEDIA_URL
---------

默认值: ``''`` (空的字符串)

处理媒体服务的URL(媒体文件来自 ``MEDIA_ROOT``).
如: ``"http://media.lawrence.com"``

MIDDLEWARE_CLASSES
------------------

默认值::

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

一个django 用到的中间件 class 名称的 tuple. 参阅 `middleware 文档`_.

PREPEND_WWW
-----------

默认值: ``False``

是否为没有 "www." 前缀的域名添加 "www." 前缀. 当且仅当安装有 ``CommonMiddleware`` 后该选项才有效. (参阅 `middleware 文档`_).参阅 ``APPEND_SLASH``.

ROOT_URLCONF
------------

默认值: Not defined

一个字符串,表示你的根 URLconf 的模块名. 举例来说:``"mydjangoapps.urls"``. 参阅 `Django如何处理一个请求`_.

.. _Django如何处理一个请求: http://www.djangoproject.com/documentation/url_dispatch/#how-django-processes-a-request

SECRET_KEY
----------

默认值: ``''`` (空的字符串)

一个密码. 用于为密码哈希算法提供一个种子.将其设置为一个随机字符串 -- 越长越好. ``django-admin.py startproject`` 会自动给你创建一个.

SEND_BROKEN_LINK_EMAILS
-----------------------

默认值: ``False``

当有人从一个有效Django-powered页面访问另一个Django-powered页面时发现404错误(也就是发现一个死链接)时, 是否发送一封邮件给 ``MANAGERS``. 当且仅当 安装有 ``CommonMiddleware`` 时该选项才有效(参阅`middleware 文档`_). 参阅 ``IGNORABLE_404_STARTS `` 和`` IGNORABLE_404_ENDS``.

SERVER_EMAIL
------------

默认值: ``'root@localhost'``

用来发送错误信息的邮件地址, 比如发送给 ``ADMINS`` 和 ``MANAGERS`` 的邮件.

SESSION_COOKIE_AGE
------------------

默认值: ``1209600`` (2周, 以秒计)

session cookies 的生命周期, 以秒计. 参阅 `session docs`_.

SESSION_COOKIE_DOMAIN
---------------------

默认值: ``None``

session cookies 有效的域. 将其值设置为类似 ``".lawrence.com"`` 这样 cookie 就可以跨域生效, 或者使用 ``None`` 作为一个标准的域 cookie. 参阅 `session docs`_.

SESSION_COOKIE_NAME
-------------------

默认值: ``'sessionid'``

session 使用的cookie 名字. 参阅 `session docs`_.

SESSION_SAVE_EVERY_REQUEST
--------------------------

默认值: ``False``

是否每次请求都保存session. 参阅 `session docs`_.

SITE_ID
-------

默认值: Not defined

是一个整数, 表示 ``django_site`` 表中的当前站点. 当一个数据包含多个站点数据时，你的程序可以据此 ID 访问特定站点的数据．

TEMPLATE_CONTEXT_PROCESSORS
---------------------------

默认值::

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

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.

TEMPLATE_DEBUG
--------------

默认值: ``False``

一个布尔值,用来开关模板调试模式.若设置为 ``True``, 如果有任何 ``TemplateSyntaxError``,一个详细的错误报告信息页将被显示给你.这个报告包括有关的模板片断,相应的行会自动高亮.

注意 Django 仅在 ``DEBUG`` 为 ``True`` 时显示这个信息页面. 

参阅 DEBUG.

TEMPLATE_DIRS
-------------

默认值: ``()`` (空的 tuple)

模板源文件目录列表,按搜索顺序. 注意要使用 Unix-风格的前置斜线(即'/'), 即便是在 Windows 上.

参阅 `template documentation`_.

TEMPLATE_LOADERS
----------------

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

一个元素为可调用对象(字符串形式的)的 tuple. 这些对象知道如何导入 templates 从各种源中. 参阅 `template documentation`_.

TEMPLATE_STRING_IF_INVALID
--------------------------

默认值: ``''`` (空的字符串)

输出文本, 作为一个字符串. 模板系统将会在出错 (比如说拼错了) 时使用该变量. 参阅 `How invalid variables are handled`_.

.. _How invalid variables are handled: http://www.djangoproject.com/documentation/templates_python/#how-invalid-variables-are-handled

TIME_FORMAT
-----------

默认值: ``'P'`` (举例来说 ``4 p.m.``)

Django admin change-list 使用的默认时间格式. 有可能系统的其它部分也使用该格式. 参阅 `allowed date format strings`_.

参阅 DATE_FORMAT 和 DATETIME_FORMAT.

.. _allowed date format strings: http://www.djangoproject.com/documentation/templates/#now

TIME_ZONE
---------

默认值: ``'America/Chicago'`` (我们可以用 ``'Asia/Shanghai PRC'`` )

一个表示当前时区的字符串. 参阅 `选择项列表`_.

Django 据此设置转换所有的日期/时间 -- 并不考虑服务器的时区设置. 举例来说, 一台服务器可以服务多个 Django-powered 站点,每个站点使用一个独立的时区设置.

USE_ETAGS
---------

默认值: ``False``

一个布尔值.指定是否输出 "Etag" 头. 这个选项可以节省网络带宽,但损失性能. 只有安装 ``CommonMiddleware`` 后这个选项才有用(参阅 `middleware 文档`_)

.. _cache docs: http://www.djangoproject.com/documentation/cache/
.. _middleware 文档: http://www.djangoproject.com/documentation/middleware/
.. _session docs: http://www.djangoproject.com/documentation/sessions/
.. _选择项列表: http://www.postgresql.org/docs/current/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
.. _template documentation: http://www.djangoproject.com/documentation/templates_python/

创建你自己的 settings
==========================

你可以为自己的Django 应用程序创建自定义 settings. 只需要你遵守以下惯例:

    * 设置名称全部大写.
    * 如果某项设置是一个序列,优先使用 tuple.这完全是基于性能考虑.
    * 不要为已经存的一个设置重新发明一个名字.