安装

你可以安装这个包在通常的使用方法 pip:

pip install flask-socketio

需求

Flask-SocketIO兼容Python 2.7和Python 3.3 +。异步服务,这个包之间的依赖可以选择三种选择:

• eventlet是最好的性能选项,支持长轮询和WebSocket传输。
• gevent支持许多不同的配置。长轮询传输与gevent包完全支持,但与eventlet,gevent没有原生WebSocket支持。添加支持WebSocket目前有两个选择。安装gevent-websocket包增加了WebSocket支持gevent或一个可以使用uWSGIweb服务器,它伴随着WebSocket功能。使用gevent也是一个性能选项,但略低于eventlet。
• 基于Werkzeug瓶开发服务器可以使用,但需要说明的是,它缺乏的表现另两个选项,那么它应该只被用来简化开发工作流程。此选项仅支持长轮询传输。

扩展自动检测异步框架使用基于安装。偏好是eventlet,gevent紧随其后。uWSGI优先,WebSocket支持gevent gevent-websocket紧随其后。如果eventlet和gevent都没有安装,那么使用瓶开发服务器。

如果使用多个进程,消息队列服务使用流程协调操作,如广播。支持队列复述,,RabbitMQ和任何其他支持的消息队列海藻包中。

在客户端,官方的插座。IO Javascript客户端库可以用来建立一个连接到服务器。也有官方的客户写在迅速、Java和c++。非官方的客户也可以工作,只要他们实现套接字。IO协议.

初始化

以下代码示例展示了如何添加Flask-SocketIO瓶应用程序:

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()标准瓶开发服务器启动。当应用程序在调试模式下Werkzeug开发服务器仍然使用和配置正确 socketio.run()。在生产模式下eventlet web服务器使用的是如果可用,其他gevent web服务器使用。如果eventlet gevent不安装,Werkzeug开发web服务器使用。

命令行接口基于点击还支持在瓶0.11中引入的。这个扩展提供了一个新版本的 flask run命令适合开始套接字。IO服务器。使用示例:

$ FLASK_APP=my_app.py flask run

应用程序必须提供一个页面加载的客户端套接字。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>

接收消息

由双方使用SocketIO时,收到消息的事件。在客户端使用Javascript回调。与Flask-SocketIO服务器需要为这些事件注册处理程序,类似于路线是如何由视图函数。

下面的示例创建一个服务器端事件处理程序为一位不愿透露姓名的事件:

@socketio.on('message')
def handle_message(message):
    print('received message: ' + message)

上面的例子中使用的字符串消息。另一种类型的未具名事件使用JSON数据:

@socketio.on('json')
def handle_json(json):
    print('received json: ' + str(json))

最灵活的一种事件使用自定义事件名称。这些事件可以是字符串的消息数据字节,int,或JSON:

@socketio.on('my event')
def handle_my_custom_event(json):
    print('received json: ' + str(json))

自定义命名事件还可以支持多个参数:

@socketio.on('my event')
def handle_my_custom_event(arg1, arg2, arg3):
    print('received args: ' + arg1 + arg2 + arg3)

命名事件是最灵活的,因为它们消除需要包含额外的元数据来描述消息类型。

Flask-SocketIO还支持SocketIO名称空间,它允许客户端多路几个同一个物理上独立的连接套接字:

@socketio.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')

客户可以请求确认消息的回调确认收到他们发送。从处理函数将返回任何值作为参数传递给客户端回调函数:

@socketio.on('my event')
def handle_my_custom_event(json):
    print('received json: ' + str(json))
    return 'one', 2

在上面的例子中,客户机将调用回调函数有两个参数, 'one'和 2。如果一个处理函数不返回任何值,客户机将调用回调函数没有参数。

发送消息

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()在默认情况下使用传入消息的名称空间。可以指定一个不同的名称空间和可选的 namespace论点:

与多个参数发送一个事件,发送一个元组:

@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客户端接收一个回调函数来调用收到的消息。后端应用程序服务器调用回调函数调用对应的服务器端回调。如果客户端调用回调参数,这些都是作为参数提供给服务器端回调。

广播

SocketIO的另一个非常有用的特性是消息的广播。Flask-SocketIO支持这个功能的 broadcast=True可选参数 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假设,不需要指定。

房间

对于许多应用程序需要用户分组成子集,可以一起解决。最好的例子是一个聊天应用程序与多个房间,用户接收消息的房间或房间,而不是从其他房间其他用户在哪里。通过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()函数接受一个可选的 room认为导致消息被发送到所有的客户都在给定的房间里。

所有客户分配一个房间连接时,命名与连接的会话ID,可以获得 request.sid。客户端可以加入任何的房间,可以给任何名字。当客户端断开它远离所有的房间。上下文无关的 socketio.send()和 socketio.emit()函数也接受 room参数广播给所有客户在一个房间里。

因为所有的客户都分配一个个人空间,解决一个消息到一个客户,客户端的会话ID可以作为房间的论点。

连接事件

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拒绝连接。这是,这样可以对客户端进行身份验证。

注意,连接和断开事件发送单独对每个名称空间使用。

基于类的命名空间

替代上述decorator-based事件处理程序,属于一个名称空间的事件处理程序可以创建为一个类的方法。的 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类,默认时适当的名称空间 namespace参数是不。

如果一个事件处理程序基于类的名称空间,并且decorator-based函数处理程序,只有装饰函数调用处理程序。

错误处理

Flask-SocketIO还可以处理异常:

@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,)

进入烧瓶的全局上下文

SocketIO事件的处理程序为路线不同的处理程序,介绍了很多困惑,能不能在SocketIO处理程序完成的。主要的区别在于,为客户生成所有SocketIO事件发生在一个长时间运行的请求的上下文。

尽管差异,Flask-SocketIO试图简化SocketIO事件处理程序处理,使环境类似于一个普通的HTTP请求。下面的列表描述了什么可行,什么不:

• 应用程序上下文被推在调用事件处理程序之前 current_app和 g可用的处理程序。
• 请求上下文也将调用处理程序之前,也 request和 session可用。但注意WebSocket事件没有单个请求相关联的,所以请求上下文连接开始推动所有的事件都派遣期间的生活连接。
• 的 request全球是增强上下文 sid成员设置为一个独特的连接会话ID。这个值被用作初始客户端添加房间里。
• 的 request上下文全球增强 namespace和 event成员包含当前名称空间和事件处理的参数。的 event成员是一个字典 message和 args钥匙。
• 的 session全球背景下的行为以不同的方式比常规请求。用户会话的一个副本SocketIO时建立连接是用于处理程序的上下文中调用连接。如果SocketIO处理程序修改,修改后的会话未来SocketIO处理程序将被保留下来,但常规的HTTP处理程序不会看到这些变化。有效,当SocketIO处理程序修改会话,会话的“叉”是专门为这些处理程序创建的。技术原因限制是保存用户会话cookie需要发送到客户端,和需要的HTTP请求和响应,这根本不存在什么SocketIO连接。当使用服务器端提供的课程如Flask-Session或Flask-KVSession扩展,在HTTP会话更改路由处理程序可以被SocketIO处理程序,只要不修改会话SocketIO处理程序。
• 的 before_request和 after_request钩子不是SocketIO调用事件处理程序。
• SocketIO处理程序可以自定义修饰符,但大多数瓶decorator不适合用于SocketIO处理程序,考虑到不存在的概念 Response在SocketIO连接对象。

身份验证

应用程序的一个常见需要验证用户的身份。传统的机制基于web表单和HTTP请求不能用于SocketIO连接,因为没有地方发送HTTP请求和响应。如果有必要,一个应用程序可以实现一个定制的登录表单,将凭证发送给服务器作为SocketIO消息时由用户提交按钮被按下。

然而,在大多数情况下它是更方便执行前的传统身份验证过程SocketIO建立连接。用户的身份可以被记录在用户会话或饼干,后来当SocketIO建立连接,信息将访问SocketIO事件处理程序。

@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

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)

部署

有许多选项Flask-SocketIO服务器部署,从简单的错综复杂。在本节中,最常用的选项。

gunicorn --worker-class eventlet -w 1 module:app

gunicorn -k gevent -w 1 module:app

gunicorn -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker -w 1 module:app

$ uwsgi --http :5000 --gevent 1000 --http-websockets --master --wsgi-file app.py --callable app

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;
    }
}

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;
    }
}

socketio=SocketIO(app,message_queue='redis://')

socketio = SocketIO(message_queue='redis://')
socketio.emit('my event', {'data': 'foo'}, namespace='/test')

API参考

类 flask_socketio.SocketIO(应用=没有* * kwargs)

创建一个Flask-SocketIO服务器。

参数:

应用程序——瓶应用程序实例。如果应用程序实例并不知道当时这个类被实例化,然后调用 socketio.init_app(app)一旦应用程序实例。 manage_session——如果设置 True套接字,这个扩展管理用户会话。IO事件。如果设置为 False使用,烧瓶的会话管理。当使用烧瓶的cookie会话建议您离开这个设置为默认的 True。使用服务器端会话时, False设置允许HTTP路线和插座之间共享用户会话。IO事件。 message_queue——连接URL为消息队列服务的服务器可以使用多进程通信。消息队列时不需要使用一个服务器进程。 通道-通道名称,当使用一个消息队列。如果通道不指定,将使用默认的通道。如果多个集群SocketIO过程需要使用相同的消息队列不互相干扰,那么每个集群应该使用一个不同的频道。 路径,路径的插座。IO服务器暴露。默认为 'socket.io'。离开这个除非你知道你在做什么。 资源——别名 path. kwargs——插座。IO和引擎。IO服务器选项。

套接字。IO服务器选项详细如下:

参数:	client_manager——客户机管理器实例,将管理客户名单。这是省略时,客户名单是存储在内存中的结构,所以使用多个连接服务器是不可能的。在大多数情况下,这个观点不需要显式地设置。 日志程序—启用日志记录设置为 True或通过日志记录器对象使用。设置为禁用日志记录 False。默认值是 False. 二进制, True支持二进制有效载荷, False对所有有效载荷为文本。在Python 2,如果它被设置 True, unicode值被视为文本 str和 bytes被视为二进制值。这个选项对Python 3没有影响,文本和二进制负载总是自动发现。 json -另一个json模块用于编码和解码数据包。自定义json模块必须有 dumps和 loads函数与标准库版本兼容。使用相同的json编码器和解码器瓶应用程序中,使用 flask.json.

引擎。IO服务器配置支持以下设置:

参数:

async_mode——使用异步模型。请参见部署部分在文档中描述的可用选项。有效的异步模式 threading, eventlet, gevent和 gevent_uwsgi。如果这个论点是不给, eventlet首先是尝试,然后呢 gevent_uwsgi,然后 gevent,最后 threading。第一个异步模式,它的所有依赖项安装然后选择。 ping_timeout——的时间间隔,以秒为单位客户端断开之前等待服务器响应。默认值为60秒。 ping_interval——的间隔秒数客户机ping服务器。默认是25秒。 max_http_buffer_size——消息的最大大小当使用轮询传输。缺省值是100000000个字节。 allow_upgrades——是否允许传输升级。默认值是 True. http_compression——无论是当使用轮询传输压缩包。默认值是 True. compression_threshold——只有压缩消息当字节大小大于这个值。缺省值是1024个字节。 饼干,HTTP cookie的名称包含客户端会话id。如果设置<span