Bottle 中文文件

更新日期: 2009-09-25

原文地址: http://bottle.paws.de/page/docs （已失效）

譯文地址: http://pynotes.appspot.com/static/bottle/docs.htm （需翻牆）

這份文件會不斷更新。

假設在文件裡沒有找到答案。請在版本號跟蹤中提出 issue。

基本對映

對映使用在依據不同 URLs 請求來產生相相應的返回內容。

Bottle 使用 route() 修飾器來實現對映。

from bottle import route, run

@route('/hello')

def hello():

    return "Hello World!"

run() # This starts the HTTP server

執行這個程式。訪問 http://localhost:8080/hello 將會在瀏覽器裡看到 "Hello World!"。

GET, POST, HEAD, ...

這個對映裝飾器有可選的keyword method 預設是 method='GET'。還有可能是 POST，PUT。DELETE，HEAD 或者監聽其它的 HTTP 請求方法。

from bottle import route, request

@route('/form/submit', method='POST')

def form_submit():

    form_data = request.POST

    do_something(form_data)

    return "Done"

動態對映

你能夠提取 URL 的部分來建立動態變數名的對映。

@route('/hello/:name')

def hello(name):

    return "Hello %s!" % name

預設情況下，一個 :placeholder 會一直匹配到下一個斜線。須要改動的話，能夠把正則字元增加到 #s 之間：

@route('/get_object/:id#[0-9]+#')

def get(id):

    return "Object ID: %d" % int(id)

或者使用完整的正則匹配組來實現：

@route('/get_object/(?P<id>[0-9]+)')

def get(id):

    return "Object ID: %d" % int(id)

正如你看到的，URL 引數仍然是字串。即使你正則裡面是數字。你必須顯式的進行型別強制轉換。

@validate() 裝飾器

Bottle 提供一個方便的裝飾器 validate() 來校驗多個引數。

它能夠通過keyword和過濾器來對每個 URL 引數進行處理然後返回請求。

from bottle import route, validate

# /test/validate/1/2.3/4,5,6,7

@route('/test/validate/:i/:f/:csv')

@validate(i=int, f=float, csv=lambda x: map(int, x.split(',')))

def validate_test(i, f, csv):

    return "Int: %d, Float:%f, List:%s" % (i, f, repr(csv))

你可能須要在校驗引數失敗時丟擲 ValueError。

返回檔案流和 JSON

WSGI 規範不能處理檔案物件或字串。 Bottle 自己主動轉換字串型別為 iter 物件。

以下的樣例能夠在 Bottle 下執行，可是不能執行在純 WSGI 環境下。

@route('/get_string')

def get_string():

    return "This is not a list of strings, but a single string"

@route('/file')

def get_file():

    return open('some/file.txt','r')

字典型別也是同意的。會轉換成 json 格式。自己主動返回 Content-Type: application/json。

@route('/api/status')

def api_status():

    return {'status':'online', 'servertime':time.time()}

你能夠關閉這個特性 :bottle.default_app().autojson = False

Cookies

Bottle 是把 cookie 儲存在 request.COOKIES 變數中。新建 cookie 的方法是 response.set_cookie(name, value[, **params])。它能夠接受額外的引數。屬於 SimpleCookie 的有有效引數。

from bottle import response

response.set_cookie('key','value', path='/', domain='example.com', secure=True, expires=+500, ...)

設定 max-age 屬性(它不是個有效的 Python 引數名) 你能夠在例項中改動 cookie.SimpleCookie in response.COOKIES。

from bottle import response

response.COOKIES['key'] = 'value'

response.COOKIES['key']['max-age'] = 500

模板

Bottle 使用自帶的小巧的模板。你能夠使用呼叫 template(template_name, **template_arguments) 並返回結果。

@route('/hello/:name')

def hello(name):

    return template('hello_template', username=name)

這樣就會載入 hello_template.tpl，並提取 URL:name 到變數 username，返回請求。

hello_template.tpl 大致這樣:

<h1>Hello </h1>

<p>How are you?</p>

模板搜尋路徑

模板是依據 bottle.TEMPLATE_PATH 列表變數去搜索。預設路徑包括 ['./%s.tpl', './views/%s.tpl']。

模板快取

模板在編譯後在記憶體中快取。

改動模板不會更新快取。直到你清除快取。

呼叫 bottle.TEMPLATES.clear()。

模板語法

模板語法是環繞 Python 非常薄的一層。

主要目的就是確保正確的縮排塊。以下是一些模板語法的列子:

%...Python 程式碼開始。不必處理縮排問題。Bottle 會為你做這些。
%end 關閉一些語句 %if ...。%for ... 或者其它。

關閉塊是必須的。
`` 打印出 Python 語句的結果。
%include template_name optional_arguments 包含其它模板。
每一行返回為文字。

Example:

%header = 'Test Template'

%items = [1,2,3,'fly']

%include http_header title=header, use_js=['jquery.js', 'default.js']

<h1></h1>

<ul>

%for item in items:

  <li>

    %if isinstance(item, int):

      Zahl:

    %else:

      %try:

        Other type: ()

      %except:

        Error: Item has no string representation.

      %end try-block (yes, you may add comments here)

    %end

    </li>

  %end

</ul>

%include http_footer

Key/Value資料庫

Bottle(>0.4.6) 通過 bottle.db 模組變數提供一個 key/value 資料庫。

你能夠使用 key 或者屬性來來存取一個數據庫物件。呼叫 bottle.db.bucket_name.key_name 和 bottle.db[bucket_name][key_name]。

僅僅要確保使用正確的名字就能夠使用，而無論他們是否已經存在。

儲存的物件類似 dict 字典，keys 和 values 必須是字串。

不支援 items() 和 values() 這些方法。

找不到將會丟擲 KeyError。

持久化

對於請求，全部變化都是快取在本地記憶體池中。在請求結束時，自己主動儲存已改動部分，以便下一次請求返回更新的值。資料儲存在 bottle.DB_PATH 檔案中。

要確保檔案能訪問此檔案。

Race conditions

一般來說不須要考慮鎖問題，可是在多執行緒或者交叉環境裡仍是個問題。你能夠呼叫 bottle.db.save() 或者botle.db.bucket_name.save() 去重新整理快取，可是沒有辦法檢測到其它環境對資料庫的操作，直到呼叫bottle.db.save() 或者離開當前請求。

Example

from bottle import route, db

@route('/db/counter')

def db_counter():

    if 'hits' not in db.counter:

        db.counter.hits = 0

    db['counter']['hits'] += 1

    return "Total hits: %d!" % db.counter.hits

使用 WSGI 和中介軟體

bottle.default_app() 返回一個 WSGI 應用。

假設喜歡 WSGI 中介軟體模組的話，你僅僅須要宣告bottle.run() 去包裝應用。而不是使用預設的。

from bottle import default_app, run

app = default_app()

newapp = YourMiddleware(app)

run(app=newapp)

預設 default_app() 工作

Bottle 建立一個 bottle.Bottle() 物件和裝飾器，呼叫 bottle.run() 執行。 bottle.default_app()是預設。當然你能夠建立自己的 bottle.Bottle() 例項。

from bottle import Bottle, run

mybottle = Bottle()

@mybottle.route('/')

def index():

  return 'default_app'

run(app=mybottle)

公佈

Bottle 預設使用 wsgiref.SimpleServer 公佈。這個預設單執行緒server是用來早期開發和測試，可是後期可能會成為效能瓶頸。

有三種方法能夠去改動:

使用多執行緒的介面卡
負載多個 Bottle 例項應用
或者兩者

多執行緒server

最簡單的方法是安裝一個多執行緒和 WSGI 規範的 HTTP server比方 Paste, flup, cherrypy or fapws3 並使用對應的介面卡。

from bottle import PasteServer, FlupServer, FapwsServer, CherryPyServer

bottle.run(server=PasteServer) # Example

假設缺少你喜歡的server和介面卡。你能夠手動改動 HTTP server並設定 bottle.default_app() 來訪問你的 WSGI 應用。

def run_custom_paste_server(self, host, port):

    myapp = bottle.default_app()

    from paste import httpserver

    httpserver.serve(myapp, host=host, port=port)

多server程序

一個 Python 程式僅僅能使用一次一個 CPU，即使有很多其它的 CPU。

關鍵是要利用 CPU 資源來負載平衡多個獨立的 Python 程式。

單例項 Bottle 應用，你能夠通過不同的port來啟動(localhost:8080, 8081, 8082, ...)。

高效能負載作為反向代理和遠期每個隨機瓶程序的新要求。平衡器的行為，傳播全部可用的支援與server例項的負載。這樣。您就能夠使用全部的 CPU 核心。甚至分散在不同的物理server之間的負載。

但也有點缺點:

多個 Python 程序裡不能共享資料。
同一時間可能須要大量記憶體來執行 Python 和 Bottle 應用和副本。
最快的一個負載是 pound 當然其它一些 HTTP server相同能夠做的非常好。

不久我會增加 lighttpd 和 Apache 使用。

Apache mod_wsgi

公佈你的應用當然不是用 Bottle 自帶的方法，你能夠再 Apache server 使用 mod_wsgi 模板和 Bottles WSGI 介面。

你須要建立 app.wsgi 檔案並提供 application 物件。

這個物件是用使用 mod_wsgi 啟動你的程式並遵循 WSGI 規範可呼叫。

# /var/www/yourapp/app.wsgi

import bottle

# ... add or import your bottle app code here ...

# import myapp

application = bottle.default_app()

# Do NOT use bottle.run() with mod_wsgi

Apache 配置可能例如以下:

<VirtualHost *>

    ServerName example.com

    WSGIDaemonProcess yourapp user=www-data group=www-data processes=1 threads=5

    WSGIScriptAlias / /var/www/yourapp/app.wsgi

    <Directory /var/www/yourapp>

        WSGIProcessGroup yourapp

        WSGIApplicationGroup %{GLOBAL}

        Order deny,allow

        Allow from all

    </Directory>

</VirtualHost>

Google AppEngine

import bottle

from google.appengine.ext.webapp import util

# ... add or import your bottle app code here ...

# import myapp

# Do NOT use bottle.run() with AppEngine

util.run_wsgi_app(bottle.default_app())

CGI模式

執行緩緩，但能夠正常工作。

import bottle

# ... add or import your bottle app code here ...

bottle.run(server=bottle.CGIServe

Bottle 中文文件