Flask-SocketIO使Flask应用程序可以访问客户端和服务器之间的低延迟双向通信。 客户端应用程序可以使用Javascript，C ++，Java和Swift中的任何SocketIO官方客户端库，或任何兼容的客户端来建立与服务器的永久连接。
1,安装
pip install flask-socketio
2，依赖
Flask-SocketIO兼容Python 2.7和Python 3.3+。这个软件包所依赖的异步服务可以从以下三种选择中选择：
eventlet是最好的高性能选项，支持长轮询和WebSocket传输。
gevent支持多种不同的配置。 long-polling传输完全由gevent包支持，但与eventlet不同，gevent没有原生的WebSocket支持。为了添加对WebSocket的支持，目前有两种选择。安装gevent-websocket软件包会将WebSocket支持添加到gevent中，或者可以使用随WebSocket功能一起提供的uWSGI Web服务器。 gevent的使用也是一个性能选项，但比eventlet略低。
也可以使用基于Werkzeug的Flask开发服务器，但缺少其他两个选项的性能，因此只能用于简化开发流程。该选项仅支持长轮询传输。
扩展程序根据安装的内容自动检测使用哪个异步框架。优先考虑eventlet，接着是gevent。对于gevent中的WebSocket支持，首选uWSGI，然后是gevent-websocket。如果既没有安装eventlet也没有安装gevent，则使用Flask开发服务器。
如果使用多个进程，则进程使用消息队列服务来协调诸如广播的操作。受支持的队列是Redis，RabbitMQ和Kombu软件包支持的任何其他消息队列。
在客户端，官方的Socket.IO Javascript客户端库可以用来建立到服务器的连接。还有用Swift，Java和C ++编写的官方客户端。只要他们实现Socket.IO协议，非官方客户端也可以工作。
3，初始化
简单的代码例子：
from flask import Flask, render_template from flask_socketio import SocketIO app = Flask(__name__) app.config['SECRET_KEY'] = 'secret!' socketio = SocketIO(app) if __name__ == '__main__': socketio.run(app)
初始化的init_app（）样式也被支持。 请注意Web服务器的启动方式。 socketio.run（）函数封装了Web服务器的启动，代替了app.run（）标准的Flask开发服务器启动。 当应用程序处于调试模式时，Werkzeug开发服务器仍在socketio.run（）中使用和正确配置。 在生产模式下首选使用eventlet Web服务器，否则使用gevent Web服务器。 如果没有安装eventlet和gevent，则使用Werkzeug开发Web服务器。
还支持基于Flask 0.11中引入的点击命令行界面。 该扩展提供了适用于启动Socket.IO服务器的flask run命令的新版本。 用法示例：
$ FLASK_APP=my_app.py flask run
应用程序必须向加载Socket.IO库的客户端提供一个页面，并建立一个连接：
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/socket.io/1.3.6/socket.io.min.js"></script>
<script type="text/javascript" charset="utf-8">
var socket = io.connect('http://' + document.domain + ':' + location.port);
socket.on('connect', function() {
socket.emit('my event', {data: 'I\'m connected!'});
});
</script>
4，接收信息：
1）当使用SocketIO时，消息被双方作为事件接收。 在客户端使用Javascript回调。 使用Flask-SocketIO，服务器需要为这些事件注册处理程序，类似于视图函数处理路由的方式。
以下示例为未命名的事件创建一个服务器端事件处理程序：
@socketio.on('message')
def handle_message(message):
print('received message: ' + message)
2）上面的例子使用字符串消息。 另一种未命名事件使用JSON数据：
@socketio.on('json')
def handle_json(json):
print('received json: ' + str(json))
3）最灵活的事件类型使用自定义事件名称。 这些事件的消息数据可以是字符串，字节，整数或JSON：
@socketio.on('my event')
def handle_my_custom_event(json):
print('received json: ' + str(json))
4）自定义命名事件也可以支持多个参数：
@socketio.on('my event')
def handle_my_custom_event(arg1, arg2, arg3):
print('received args: ' + arg1 + arg2 + arg3)
5）命名事件是最灵活的，因为它们不需要包含额外的元数据来描述消息类型。
Flask-SocketIO还支持SocketIO命名空间，它允许客户端在同一个物理套接字上复用几个独立的连接：
@socketio.on('my event', namespace='/test')
def handle_my_custom_namespace_event(json):
print('received json: ' + str(json))
6）当没有指定名称空间时，将使用名称为“/”的默认全局名称空间。
对于装饰器语法不方便的情况，可以使用on_event方法：
def my_function_handler(data):
pass
socketio.on_event('my event', my_function_handler, namespace='/test')
7）客户可以要求确认回复，确认收到他们发送的消息。 从处理函数返回的任何值将作为回调函数中的参数传递给客户端：
@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)
@socketio.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('my event')
def handle_my_custom_event(json):
emit('my response', json, namespace='/chat')
要发送具有多个参数的事件，请发送一个元组：
@socketio.on('my event')
def handle_my_custom_event(json):
emit('my response', ('foo', 'bar', json), namespace='/chat')
SocketIO支持确认消息被客户端接收的确认回调：
def ack():
print 'message was received!'
@socketio.on('my event')
def handle_my_custom_event(json):
emit('my response', json, callback=ack)
当使用回调函数时，Javascript客户端接收到一个回调函数来接收消息。 客户端应用程序调用回调函数后，调用相应的服务器端回调。 如果用参数调用客户端回调，则这些回调也作为参数提供给服务器端回调。
6，广播
SocketIO的另一个非常有用的功能是消息的广播。 Flask-SocketIO支持使用broadcast = True和optional（可选参数）来send（）和emit（）：
@socketio.on('my event')
def handle_my_custom_event(data):
emit('my response', data, broadcast=True)
在启用广播选项的情况下发送消息时，连接到命名空间的所有客户端都会收到它，包括发件人。 当不使用名称空间时，连接到全局名称空间的客户端将收到该消息。 请注意，广播消息不会调用回调。
在所有示例中，直到这一点，服务器都响应客户端发送的事件。 但对于某些应用程序，服务器需要成为消息的发起者。 将通知发送到服务器中发生的事件的客户端可能会很有用，例如在后台线程中。 socketio.send（）和socketio.emit（）方法可用于向所有连接的客户端广播：
def some_function():
socketio.emit('some event', {'data': 42})
请注意，socketio.send（）和socketio.emit（）与上下文感知的send（）和emit（）不同。 还要注意，在上面的用法中没有客户端上下文，所以假定broadcast = True，不需要指定。
8，聊天室
对于许多应用程序来说，有必要将用户分成可以一起处理的子集。 最好的例子是有多个房间的聊天应用程序，用户从房间或房间接收消息，而不是从其他房间的其他房间接收消息。 Flask-SocketIO通过join_room（）和leave_room（）函数来支持这个房间的概念：
from flask_socketio import join_room, leave_room
@socketio.on('join')
def on_join(data):
username = data['username']
room = data['room']
join_room(room)
send(username + ' has entered the room.', room=room)
@socketio.on('leave')
def on_leave(data):
username = data['username']
room = data['room']
leave_room(room)
send(username + ' has left the room.', room=room)
send（）和emit（）函数接受一个可选的房间参数，使得消息被发送到给定房间中的所有客户端。
所有的客户端在连接时都被分配一个空间，用连接的会话ID命名，可以从request.sid中获得。 一个给定的客户可以加入任何房间，可以给任何名字。 当一个客户端断开连接时，它将从它所在的所有房间中移除。上下文无关的socketio.send（）和socketio.emit（）函数也接受一个房间参数来广播给房间中的所有客户端。
由于所有的客户端都被分配了一个个人房间，所以为了向一个客户端发送消息，客户端的会话ID可以被用作房间参数。
9，连接事件
Flask-SocketIO也调度连接和断开事件。 以下示例显示如何为其注册处理程序：
@socketio.on('connect', namespace='/chat')
def test_connect():
emit('my response', {'data': 'Connected'})
@socketio.on('disconnect', namespace='/chat')
def test_disconnect():
print('Client disconnected')
连接事件处理程序可以选择返回False来拒绝连接。 这样就可以在这个时候验证客户端。
请注意，连接和断开连接事件在每个使用的名称空间上单独发送。
10，基于类的命名空间
作为上述基于装饰器的事件处理程序的替代方法，属于名称空间的事件处理程序可以把类的方法名映射到命名空间。 flask_socketio.Namespace作为基类提供，以创建基于类的命名空间：
from flask_socketio import Namespace, emit
class MyCustomNamespace(Namespace):
def on_connect(self):
pass
def on_disconnect(self):
pass
def on_my_event(self, data):
emit('my_response', data)
socketio.on_namespace(MyCustomNamespace('/test'))
当使用基于类的命名空间时，服务器收到的任何事件都会被分配到一个名为带有on_前缀的事件名称的方法。 例如，事件my_event将由名为on_my_event的方法处理。 如果收到一个没有在命名空间类中定义的相应方法的事件，则该事件被忽略。 在基于类的命名空间中使用的所有事件名称必须使用方法名称中合法的字符。
为了方便在基于类的命名空间中定义的方法，命名空间实例包含了flask_socketio.SocketIO类中的几个方法的版本，当没有给出命名空间参数时，默认为适当的命名空间。
如果事件在基于类的名称空间中有一个处理程序，并且还有基于装饰器的函数处理程序，则只调用装饰的函数处理程序。
11，处理错误
处理错误的例子：
@socketio.on_error() # Handles the default namespace
def error_handler(e):
pass
@socketio.on_error('/chat') # handles the '/chat' namespace
def error_handler_chat(e):
pass
@socketio.on_error_default # handles all namespaces without an explicit error handler
def default_error_handler(e):
pass
错误处理函数将异常对象作为参数。
当前请求的消息和数据参数也可以使用request.event变量进行检查，这对于事件处理程序之外的错误日志记录和调试很有用：
from flask import request
@socketio.on("my error event")
def on_my_event(data):
raise RuntimeError()
@socketio.on_error_default
def default_error_handler(e):
print(request.event["message"]) # "my error event"
print(request.event["args"]) # (data,)
12，访问flask全局内容
SocketIO事件的处理程序与路由处理程序的处理程序不同，这引起了有关在一个SocketIO处理程序中可以和不可以完成什么的困惑。主要区别在于，为客户端生成的所有SocketIO事件都发生在单个长时间运行请求的上下文中。
尽管有所不同，但Flask-SocketIO试图通过使环境类似于普通的HTTP请求，来使得SocketIO事件处理程序更容易工作。以下列表描述了什么可行，什么不可行：
在调用事件处理程序之前推送应用程序上下文，使得处理程序可以使用current_app和g。
在调用处理程序之前，还会推送请求上下文，同时也使请求和会话可用。但是请注意，WebSocket事件没有与它们关联的单个请求，所以启动连接的请求上下文被推送到连接生命期间分派的所有事件。
全局请求上下文使用sid成员进行了增强，该成员被设置为连接的唯一会话ID。此值用作添加客户端的初始空间。
通过包含当前处理的名称空间和事件参数的名称空间和事件成员来增强请求上下文全局。事件成员是一个带有消息和参数键的字典。
会话上下文全局的行为方式与常规请求不同。在建立SocketIO连接时用户会话的副本可用于该连接上下文中调用的处理程序。如果一个SocketIO处理程序修改会话，修改的会话将被保留以供将来的SocketIO处理程序使用，但常规的HTTP路由处理程序将不会看到这些更改。实际上，当SocketIO处理程序修改会话时，将为这些处理程序专门创建会话的“分支”。这种限制的技术原因是为了保存用户会话，需要将cookie发送到客户端，并且需要HTTP请求和响应，这在SocketIO连接中不存在。在使用服务器端会话（如Flask-Session或Flask-KVSession扩展提供的会话）时，只要会话在SocketIO处理程序中未修改，则可以通过SocketIO处理程序查看HTTP路由处理程序中对会话所做的更改。
对于SocketIO事件处理程序，不会调用before_request和after_request挂钩。
SocketIO处理程序可以使用自定义装饰器，但是大多数Flask装饰器将不适合用于SocketIO处理程序，因为在SocketIO连接期间没有关于Response对象的概念。
13 授权
应用程序的共同需求是验证用户的身份。 基于Web表单和HTTP请求的传统机制不能用于SocketIO连接，因为没有地方发送HTTP请求和响应。 如果需要，应用程序可以实现一个定制的登录表单，当用户按下提交按钮时，该表单将证书作为SocketIO消息发送到服务器。
但是，在大多数情况下，在SocketIO连接建立之前执行传统的认证过程会更方便。 然后可以将用户的标识记录在用户会话中或cookie中，稍后在建立SocketIO连接时，可以通过SocketIO事件处理程序访问该信息。
14 ，用flask-login 作为例子讲解flask-socketIO
Flask-SocketIO可以访问由Flask-Login维护的登录信息。 在执行常规Flask-Login身份验证并调用login_user（）函数以在用户会话中记录用户之后，任何SocketIO连接都将有权访问current_user上下文变量：
@socketio.on('connect')
def connect_handler():
if current_user.is_authenticated:
emit('my response',
{'message': '{0} has joined'.format(current_user.name)},
broadcast=True)
else:
return False # not allowed here
请注意，login_required装饰器不能与SocketIO事件处理程序一起使用，但可以创建断开未经认证用户的自定义装饰器，如下所示：
import functools
from flask import request
from flask_login import current_user
from flask_socketio import disconnect
def authenticated_only(f):
@functools.wraps(f)
def wrapped(*args, **kwargs):
if not current_user.is_authenticated:
disconnect()
else:
return f(*args, **kwargs)
return wrapped
@socketio.on('my event')
@authenticated_only
def handle_my_custom_event(data):
emit('my response', {'message': '{0} has joined'.format(current_user.name)},
broadcast=True)
15 发布
部署Flask-SocketIO服务器有多种选择，从简单到复杂。 在本节中，将介绍最常用的选项。
1）嵌入式服务
最简单的部署策略是安装eventlet或gevent，并通过调用socketio.run（app）来启动Web服务器，如上例所示。 这将在eventlet或gevent web服务器上运行应用程序，以安装的为准。
请注意，当安装eventlet或gevent时，socketio.run（app）会运行一个生产准备服务器。 如果这两个都没有安装，那么应用程序将在Flask的开发Web服务器上运行，这不适合于生产使用。
不幸的是，在uWSGI中使用gevent时，这个选项是不可用的。 有关此选项的信息，请参阅下面的uWSGI部分。
2）gunicorn web 服务
socketio.run（app）的替代方法是使用gunicorn作为web服务器，使用eventlet或gevent工作。 对于这个选项，除了gunicorn之外，还需要安装eventlet或gevent。 通过gunicorn启动eventlet服务器的命令行是：
gunicorn --worker-class eventlet -w 1 module:app
如果您更喜欢使用gevent，则启动服务器的命令是：
gunicorn -k gevent -w 1 module:app
当gevent worker使用gunicorn和gevent-websocket提供的WebSocket支持时，必须更改启动服务器的命令以选择支持WebSocket协议的自定义gevent Web服务器。 修改后的命令是：
```gunicorn -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker -w 1 module:app```
在所有这些命令中，module是定义应用程序实例的Python模块或包，app是应用程序实例本身。
Gunicorn版本18.0是Flask-SocketIO推荐的版本。 已知19.x版本在包含WebSocket的某些部署方案中具有不兼容性。
由于gunicorn使用有限的负载均衡算法，因此使用此Web服务器时不可能使用多个工作进程。 出于这个原因，上面的所有例子都包含-w 1选项。
3） uWSGI web服务
将uWSGI服务器与gevent结合使用时，Socket.IO服务器可以利用uWSGI的原生WebSocket支持。
有关uWSGI服务器的配置和使用的完整说明超出了本文档的范围。 uWSGI服务器是一个相当复杂的软件包，提供了大量全面的选项。 必须使用WebSocket和SSL支持来编译WebSocket传输才能使用。 作为介绍的一种方式，以下命令在端口5000上为示例应用程序app.py启动一个uWSGI服务器：
```$ uwsgi --http :5000 --gevent 1000 --http-websockets --master --wsgi-file app.py --callable app```
16 ngnix 做反向代理
可以使用nginx作为将请求传递给应用程序的前端反向代理。 但是，只有nginx 1.4和更新版本支持WebSocket协议的代理。 以下是代理HTTP和WebSocket请求的基本nginx配置：
server {
listen 80;
server_name _;
location / {
include proxy_params;
proxy_pass http://127.0.0.1:5000;
}
location /socket.io {
include proxy_params;
proxy_http_version 1.1;
proxy_buffering off;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_pass http://127.0.0.1:5000/socket.io;
}
}
下一个示例添加了对多个Socket.IO服务器的负载平衡的支持：
upstream socketio_nodes {
ip_hash;
server 127.0.0.1:5000;
server 127.0.0.1:5001;
server 127.0.0.1:5002;
# to scale the app, just add more nodes here!
}
server {
listen 80;
server_name _;
location / {
include proxy_params;
proxy_pass http://127.0.0.1:5000;
}
location /socket.io {
include proxy_params;
proxy_http_version 1.1;
proxy_buffering off;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_pass http://socketio_nodes/socket.io;
}
}
尽管上述示例可以作为初始配置工作，但请注意，nginx的生产安装将需要更完整的配置，涵盖其他部署方面，如提供静态文件资产和SSL支持。
17，使用多进程
Flask-SocketIO支持从2.0版本开始的负载均衡器之后的多个工作者。 部署多个工作者使得使用Flask-SocketIO的应用程序能够在多个进程和主机之间传播客户端连接，并以这种方式进行扩展以支持大量的并发客户端。
有两个要求使用多个Flask-SocketIO工作者：
负载均衡器必须配置为将来自给定客户端的所有HTTP请求始终转发给同一个工作者。这有时被称为“粘性会话”。对于nginx，使用ip_hash指令来实现这一点。 Gunicorn不能用于多个工作者，因为它的负载平衡器算法不支持粘性会话。
由于每个服务器只拥有客户端连接的一部分，因此服务器使用Redis或RabbitMQ等消息队列来协调诸如广播和房间之类的复杂操作。
使用消息队列时，还需要安装其他依赖项：
对于Redis，必须安装软件包redis（pip install redis）。
对于RabbitMQ，必须安装包kombu（pip install kombu）。
对于Kombu支持的其他消息队列，请参阅Kombu文档以了解需要什么依赖关系。
如果使用eventlet或gevent，那么通常需要修补Python标准库来强制消息队列包使用协程友好的函数和类。
要启动多个Flask-SocketIO服务器，必须首先确保您有消息队列服务正在运行。要启动Socket.IO服务器并将其连接到消息队列，请将message_queue参数添加到SocketIO构造函数中：
```socketio = SocketIO(app, message_queue='redis://')```
message_queue参数的值是使用的队列服务的连接URL。 对于在与服务器相同的主机上运行的redis队列，可以使用“redis：//”URL。 同样，对于默认的RabbitMQ队列，可以使用“amqp：//”URL。 Kombu软件包有一个文档部分，描述所有支持的队列的URL的格式。
对于许多类型的应用程序，有必要从不是SocketIO服务器的进程发出事件，例如一个Celery进程。 如果将SocketIO服务器或服务器配置为按照上一节所述在消息队列中进行侦听，则其他任何进程都可以创建自己的SocketIO实例，并使用该实例以与服务器相同的方式发出事件。
例如，对于在eventlet Web服务器上运行并使用Redis消息队列的应用程序，以下Python脚本向所有客户端广播一个事件：
socketio = SocketIO(message_queue='redis://')
socketio.emit('my event', {'data': 'foo'}, namespace='/test')
以这种方式使用SocketIO实例时，Flask应用程序实例不会传递给构造函数。
SocketIO的通道参数可用于通过消息队列选择特定的通信通道。当有多个独立的SocketIO服务共享相同的队列时，使用自定义通道名是必要的。
当使用eventlet或gevent时，Flask-SocketIO不适用猴子补丁。但是，当使用消息队列时，如果Python标准库没有被修补，与消息队列服务对话的Python包很可能会挂起。
需要注意的是，要连接到SocketIO服务器的外部进程不需要像主服务器那样使用eventlet或gevent。让服务器使用协程框架，而外部进程不是问题。例如，芹菜工作人员不需要配置为仅仅因为主服务器而使用eventlet或gevent。但是如果你的外部进程不管用什么理由使用协程框架，那么可能需要猴子补丁，这样消息队列就可以访问协程友好的函数和类。