筆者最近在學習flask-SocketIO，由于找不到中文文檔，就選擇了自己翻譯官方的英文文檔，并分享給大家，希望感興趣的朋友可以一起學習。筆者水平有限，難以做到盡善盡美。如有錯漏懇，請各位不吝賜教。
flask-SocketIO 給flask應用一個客戶端和服務器之間低延遲的雙向通信。客戶端應用可以用Javascript,C++,Java,Swift或者其它任意的編程語言的socketio官方庫的客戶端，去和服務端創建一個永久的連接。
1.安裝
你可以使用pip這樣常規的方式來安裝這個包
> pip install flask-socketio
2.依賴
Flask-SocketIO兼容python2.7和python3.3+。這個異步的服務的包的依賴可以有三個選擇：
- eventlet：這是最好的選擇，支持長連接(long-polling)和websocket傳輸。
- gevent: 支持許多不同的配置，長連接傳輸是完全支持的，但是不同于eventlet，gevent并沒有原生支持websocket。有兩個辦法去添加websocket。gevent-websocket包為gevent添加了websocket支持，但是不幸的是，這個包只能用于python2。至于另外一個選擇，是用uWSGI網絡服務器，這個能夠在功能上支持websocket。gevent依然是可操作的選擇，但是優先級輕微地低于eventlet。
- 基于Werkzeug開發的flask服務器也是可行的，使用缺乏可操作性的caveat，它僅可以被用于簡化workflow的開發。這個方案僅支持長連接方式傳輸。
這個擴展自動尋找已安裝的異步框架來使用。最優先的是eventlet，其次是gevent。在gevent中，對于websocket的支持，uWSGI是優先考慮的，其次是gevent-websocket。如果eventlet和gevent都沒有被安裝，那么flask-development將會被啟用。
如果使用多進程，一個消息隊列服務將會被進程用來協調操作，例如廣播。支持這個隊列的有Redis,RabbitMQ,還有其他由Kombu支持的包。
在客戶端，Javascript官方的SOcket.IO可以用來創建一個與服務端通信的連接。這里有許多用Swift,Java,C++編寫的官方客戶端。非官方的客戶端也是可以工作的，只要他們支持了Socket.IO協議。
3.初始化
接下來的代碼例子揭示了，怎樣去把Flask-SocketIO引入到Flask應用：
from flask import Flask, render_template
from flask_socketio import SocketIO
app = Flask(__name__)
app.configp['SECRET_KEY'] = 'secret!'
socketio = SocketIO(app)
if __name__ == '__main__':
socketio.run(app)
init_app()風格的初始化也是支持的。注意網絡服務器的啟動。函數socketio.run()封裝了網絡服務器的啟動部分，并且代替了flask開發服務器的標準啟動語句app.run()。當應用在debug模式下，Werkzeug開發服務器也是在socketio.run()中被合理地應用和配置。如果可用的話，在生產模式下eventlet網絡服務器也是被應用的，否則，gevent網絡服務器將會被啟用。如果eventlet和gevent都沒有被安裝，那么將會使用Werkzeug開發網絡服務器。
在flask 0.11中被引入的可點擊命令行界面也是被支持的。這個擴展提供了一個新版的flask run命令，適合啟動一個Socket.IO服務器。用法示例：
FLASK_APP = my_app flask run
這個應用只能為那種連接到客戶端的頁面服務，這個客戶端引用了Socket.IO庫并且建立一個連接：
<script type="text/javascript" scr="http://cdn.cloudflare.com/ajax/libs/socket.io/1.3.6/socket.io.min.js"></scritp>
<script type="text/javascript" charset="utf-8">
var socket = io.connect(location.protocol + '//' + document.domain + ':' + location.port);
socket.on('connect', function() {
socket.emit('my event', {data: 'I\'m connected!'});
});
</script>
4.接收消息
在使用SocketIO的時候，消息將被作為活動(event)的兩端接收。在客戶端使用JavaScript回叫信號。使用Flask-SocketIO服務器，需要為這些活動注冊處理器(handler)，類似于視圖函數怎樣處理路由。
下面的例子是為一個未命名的活動創建了一個服務端的活動處理器(event handler)：
@socketio.on('message')
def handle_message(message):
print('received message: ' + message)
在上面的例子中，使用了字符串消息。此外，另一種未命名的活動使用了JSON數據：
@socketio.on('json')
def handle_json(json):
print('received json: '+ str(json))
最靈活的一種活動使用了自定義的活動名稱。這些活動的消息數據類型可以是字符串，字節，整型，或者JSON：
@socketio.on('my event')
def handle_my_custom_event(json):
print('received json: ' + str(json))
自定義名稱的活動可以支持多參數：
@socketio.on('my event')
def handle_my_sustom_event(arg1, arg2, arg3):
print('received args: ' + arg1 + arg2 + arg3)
命名活動是極度復雜的，在其消除了額外的元數據(metadata)來描述消息類型的時候。
Flask-SocketIO同樣支持命名空間(namespace)，這個功能允許客戶端在一個相同的物理socket上多路復用幾個獨立的連接：
@scoketio.on('my event', namespace='/test')
def handle_my_custom_namespace_event(json):
print('received json: ' + str(json))
當一個命名空間沒有具體指出，一個全局的命名空間'/'將會被啟用
有時，裝飾器的語法并不方便，on_event()方法可以作為替代
def my_function_handler(data):
pass
socketio.on_event('my event', my_function_handler, namespace='/test')
客戶端要求一個確認回復，來確認消息的接收。任何一個從處理函數(handler function)中返回的值都會在回調函數中作為一個參數返回給客戶端。
@socketio.on('my event')
def handle_my_custom_event(json):
print('received json: ' + str(json))
return('one', 2)
在上面的例子中，客戶端回調函數將會回調兩個參數，'one'和'2'。如果處理函數沒有返回值，這個客戶端回調函數將以沒有參數的情況返回。
5.發送消息
之前章節定義的SocketIO活動處理函數可以憑借send()函數和emit()函數來連接客戶端
接下來的例子是將接收到的消息退回到發送它們的客戶端：
from flask_socketio import send, emit
@socketio.on('message')
def handle_message(message):
send(message)
@socketio.on('json')
def handle_json(json):
send(json, json=True)
@socket.on('my event')
def handle_my_custom_event(json):
emit('my response', json)
注釋一下，send()和emit()是怎樣用在已命名和未命名的活動上的
當運作在有命名空間的活動中時，send()和emit()默認用在接下來的消息中。不同的命名空間可以被具體化到可選擇的可選擇的命名空間參數上：
@socketio.on('message')
def handle_message(message):
send(message, namespace='/chat')
@socketio.on('message')
def handle_my_sustom_event(json):
emit('my response', json, namespace='/chat')
為了實現發送一個多參數的活動，發送一個元組：
def ack():
print('message was received!')
@socketio.on('my event')
def handle_my_custom_event(json):
emit('my response', json, callback=ack)
使用回調時，JavaScript客戶端使用回調函數在接收到的信息時回調。在客戶端應用啟用回調函數時，服務器會啟用服務端相匹配的函數去響應。如果客戶端沒有回調任何值，這些將會作為服務端的響應被提供。
客戶端的應用同樣要求一個來自服務端的確認信息。如果服務端想為一次響應提供一個參數，它必須要在活動處理函數中被返回。
@socketio.on('my event')
def handle_my_custom_event(json):
# ... handle the event
return 'foo', 'bar', 123 # client callback will receive these 3 arguments
