Django settings

 

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 搜索路徑 中.

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
服務器環境 (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 文檔 以獲得更多信息.

默認 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.

在你的代碼中使用 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.

DATETIME_FORMAT
默認值: 'N j, Y, P' (舉例來講 Feb. 4, 2003, 4 p.m.)

在 Django admin change-list 頁對日期時間字段使用的默認日期時間格式, 系統中的其它部分也可能使用該格式. 參閱 allowed date format strings.

參閱 DATE_FORMAT 和 TIME_FORMAT.

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 模塊.

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 會自動往其中添加內容.

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.

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如何處理一個請求.

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.

TIME_FORMAT
默認值: 'P' (舉例來講 4 p.m.)

Django admin change-list 使用的默認時間格式. 有可能系統的其它部分也使用該格式. 參閱 allowed date format strings.

參閱 DATE_FORMAT 和 DATETIME_FORMAT.

TIME_ZONE
默認值: 'America/Chicago' (咱們能夠用 'Asia/Shanghai PRC' )

一個表示當前時區的字符串. 參閱 選擇項列表.

Django 據此設置轉換全部的日期/時間 -- 並不考慮服務器的時區設置. 舉例來講, 一臺服務器能夠服務多個 Django-powered 站點,每一個站點使用一個獨立的時區設置.

USE_ETAGS
默認值: False

一個布爾值.指定是否輸出 "Etag" 頭. 這個選項能夠節省網絡帶寬,但損失性能. 只有安裝 CommonMiddleware 後這個選項纔有用(參閱 middleware 文檔)

建立你本身的 settings
你能夠爲本身的Django 應用程序建立自定義 settings. 只須要你遵照如下慣例:

設置名稱所有大寫. 若是某項設置是一個序列,優先使用 tuple.這徹底是基於性能考慮. 不要爲已經存的一個設置從新發明一個名字.