flask-socketio：API 参考

flask-socketio

API 参考

类flask_socketio.SocketIO( app=None , **kwargs ) 

创建一个 Flask-SocketIO 服务器。

参数：

app - flask应用程序实例。如果在实例化此类时不知道应用程序实例，则 socketio.init_app(app)在应用程序实例可用时调用。 manage_session – 如果设置为True，此扩展管理 Socket.IO 事件的用户会话。如果设置为False，则使用 Flask 自己的会话管理。使用 Flask 的基于 cookie 的会话时，建议您将此设置保留为默认值True. 使用服务器端会话时，False设置允许在 HTTP 路由和 Socket.IO 事件之间共享用户会话。 message_queue – 服务器可用于多进程通信的消息队列服务的连接 URL。使用单个服务器进程时不需要消息队列。 channel – 使用消息队列时的通道名称。如果未指定通道，则将使用默认通道。如果多个 SocketIO 进程集群需要使用同一个消息队列而不互相干扰，那么每个集群应该使用不同的通道。 path – 公开 Socket.IO 服务器的路径。默认为 'socket.io'. 保持原样，除非您知道自己在做什么。 资源– 的别名path。 kwargs – Socket.IO 和 Engine.IO 服务器选项。

Socket.IO 服务器选项详述如下：

参数：

client_manager – 将管理客户端列表的客户端管理器实例。省略时，客户端列表存储在内存结构中，因此无法使用多个连接的服务器。在大多数情况下，不需要显式设置此参数。 logger – 启用日志记录集True或传递一个 logger 对象以使用。禁用日志记录设置为False. 默认值为 False. 请注意，即使 logger是，也会记录致命错误False。 json - 用于编码和解码数据包的替代 json 模块。自定义 json 模块必须具有dumps与loads 标准库版本兼容的功能。要使用与 Flask 应用程序相同的 json 编码器和解码器，请使用flask.json. async_handlers – 如果设置为True，客户端的事件处理程序将在单独的线程中执行。要同步运行客户端的处理程序，请设置为False. 默认值为True. always_connect – 当设置为 时False，新连接是临时的，直到连接处理程序返回除 之外的东西False，此时它们被接受。当设置为 时True，立即接受连接，然后如果连接处理程序返回False，则发出断开连接。True如果您需要从连接处理程序发出事件并且您的客户端在连接接受之前接收到事件时感到困惑，请设置为。在任何其他情况下，使用默认值False。

Engine.IO 服务器配置支持以下设置：

参数：

async_mode – 要使用的异步模型。有关可用选项的描述，请参阅文档中的部署部分。有效的异步模式是threading、 eventlet和。如果没有给出这个参数，首先尝试，然后 ，然后，最后 。然后选择第一个安装了所有依赖项的异步模式。geventgevent_uwsgieventletgevent_uwsgigeventthreading ping_interval – 服务器 ping 客户端的时间间隔（以秒为单位）。默认值为 25 秒。对于高级控制，可以给出一个双元素元组，其中第一个数字是 ping 间隔，第二个是服务器添加的宽限期。 ping_timeout – 客户端在断开连接之前等待服务器响应的时间（以秒为单位）。默认值为 5 秒。 max_http_buffer_size – 使用轮询传输时消息的最大大小。默认值为 1,000,000 字节。 allow_upgrades – 是否允许传输升级。默认值为True. http_compression – 使用轮询传输时是否压缩包。默认值为True. compression_threshold – 仅当消息的字节大小大于此值时才压缩消息。默认值为 1024 字节。 cookie – 如果设置为字符串，则它是服务器发送回客户端的 HTTP cookie 的名称，其中包含客户端会话 ID。如果设置为字典，则'name'键包含 cookie 名称，其他键定义 cookie 属性，其中每个属性的值可以是字符串、不带参数的可调用对象或布尔值。如果设置为None（默认值），则不会向客户端发送 cookie。 cors_allowed_origins – 允许连接到此服务器的来源或来源列表。默认情况下只允许相同的来源。将此参数设置 '*'为允许所有来源，或[]禁用 CORS 处理。 cors_credentials – 向该服务器发出的请求中是否允许凭据（cookies、身份验证）。默认值为 True. monitor_clients – 如果设置为True，后台任务将确保关闭非活动客户端。设置为False禁用监控任务（不推荐）。默认值为True. engineio_logger – 启用 Engine.IO 日志记录设置True或传递一个记录器对象以使用。禁用日志记录设置为 False. 默认值为False. 请注意，即使在 engineio_loggeris时也会记录致命错误False。

close_room（房间，命名空间=无）

关闭一个房间。

此功能删除给定房间中的所有用户，然后从服务器中删除房间。此函数可以在 SocketIO 事件上下文之外使用。

参数：	room – 要关闭的房间的名称。 namespace – 房间所在的命名空间。默认为全局命名空间。

emit(事件, *args , **kwargs ) 

发出服务器生成的 SocketIO 事件。

此函数向一个或多个连接的客户端发出 SocketIO 事件。JSON blob 可以作为有效负载附加到事件。此函数可以在 SocketIO 事件上下文之外使用，因此当服务器是事件的发起者时使用它是合适的，在任何客户端上下文之外，例如在常规 HTTP 请求处理程序或后台任务中。例子：

@app.route('/ping')
def ping():
    socketio.emit('ping event', {'data': 42}, namespace='/chat')

参数：	event – 要发出的用户事件的名称。 args – 包含要作为有效负载发送的 JSON 数据的字典。 namespace – 消息将在其下发送的命名空间。默认为全局命名空间。 to - 将消息发送给给定房间中的所有用户。如果不包含此参数，则将事件发送给所有连接的用户。 include_self –True在广播或寻址房间时包含发送者，或False发送给除发送者之外的所有人。 skip_sid – 广播或寻址房间时要忽略的客户端会话 ID。这通常设置为消息的发起者，以便除该客户端之外的每个人都接收消息。要跳过多个 sid，请传递一个列表。 callback – 如果给定，将调用此函数以确认客户端已收到消息。将传递给函数的参数是客户端提供的参数。回调函数只能在寻址单个客户端时使用。

event( *args , **kwargs ) 

装饰器注册一个事件处理程序。

on()这是从装饰函数中获取事件名称的方法的简化版本。

示例用法：

@socketio.event
def my_event(data):
    print('Received data: ', data)

上面的例子等价于：

@socketio.on('my_event')
def my_event(data):
    print('Received data: ', data)

自定义命名空间可以作为装饰器的参数给出：

@socketio.event(namespace='/test')
def my_event(data):
    print('Received data: ', data)

on（消息，命名空间=无）

装饰器注册一个 SocketIO 事件处理程序。

此装饰器必须应用于 SocketIO 事件处理程序。例子：

@socketio.on('my event', namespace='/chat')
def handle_my_custom_event(json):
    print('received json: ' + str(json))

参数：	message – 事件的名称。这通常是用户定义的字符串，但已经定义了一些事件名称。用于 'message'定义接受字符串有效负载'json'的处理程序、定义接受 JSON blob 有效负载的处理程序，'connect'或'disconnect' 为连接和断开事件创建处理程序。 namespace – 要在其上注册处理程序的命名空间。默认为全局命名空间。

on_error（命名空间=无）

装饰器为 SocketIO 事件定义自定义错误处理程序。

此装饰器可以应用于充当命名空间错误处理程序的函数。当 SocketIO 事件处理程序引发异常时，将调用此处理程序。处理函数必须接受一个参数，即引发的异常。例子：

@socketio.on_error(namespace='/chat')
def chat_error_handler(e):
    print('An error has occurred: ' + str(e))

参数：	namespace – 为其注册错误处理程序的命名空间。默认为全局命名空间。

on_error_default(异常处理程序) 

装饰器为 SocketIO 事件定义默认错误处理程序。

此装饰器可以应用于一个函数，该函数充当任何没有特定处理程序的命名空间的默认错误处理程序。例子：

@socketio.on_error_default
def error_handler(e):
    print('An error has occurred: ' + str(e))

on_event（消息，处理程序，命名空间=无）

注册一个 SocketIO 事件处理程序。

on_event是'on'.

例子：

def on_foo_event(json):
    print('received json: ' + str(json))

socketio.on_event('my event', on_foo_event, namespace='/chat')

参数：	message – 事件的名称。这通常是用户定义的字符串，但已经定义了一些事件名称。用于 'message'定义接受字符串有效负载'json'的处理程序、定义接受 JSON blob 有效负载的处理程序，'connect'或'disconnect' 为连接和断开事件创建处理程序。 handler – 处理事件的函数。 namespace – 要在其上注册处理程序的命名空间。默认为全局命名空间。

run( app , host=None , port=None , **kwargs ) 

运行 SocketIO Web 服务器。

参数：

app – Flask 应用程序实例。 host – 要侦听的服务器的主机名或 IP 地址。默认为 127.0.0.1。 port - 服务器要侦听的端口号。默认为 5000。 debug –True以调试模式启动服务器，False以正常模式启动。 use_reloader –True启用 Flask 重新加载器，False 禁用它。 reloader_options - 带有选项的字典，这些选项传递给 Flask 重新加载器，例如extra_files, reloader_type等。 extra_files – Flask 重新加载器应查看的附加文件列表。默认为None. 已弃用，请reloader_options改用。 log_output – 如果True是，则服务器记录所有传入连接。如果False日志记录被禁用。默认为True调试模式，False 正常模式。使用线程异步模式时未使用。 kwargs – 额外的网络服务器选项。Web 服务器选项特定于在每种支持的异步模式中使用的服务器。请注意，在使用诸如 gunicorn 之类的外部 Web 服务器时，将不会看到此处提供的选项，因为在这种情况下不会调用此方法。

send（数据，json=False，namespace=None，to=None，callback=None，include_self=True，skip_sid=None，**kwargs ）

发送服务器生成的 SocketIO 消息。

该函数向一个或多个连接的客户端发送一个简单的 SocketIO 消息。消息可以是字符串或 JSON blob。这是一个更简单的版本emit()，应该是首选。此函数可以在 SocketIO 事件上下文之外使用，因此当服务器是事件的发起者时使用它是合适的。

参数：	data – 要发送的消息，可以是字符串或 JSON blob。 json –True如果message是 JSON blob，False 否则。 namespace – 消息将在其下发送的命名空间。默认为全局命名空间。 to - 仅将消息发送给给定房间中的用户。如果不包含此参数，则将消息发送给所有连接的用户。 include_self –True在广播或寻址房间时包含发送者，或False发送给除发送者之外的所有人。 skip_sid – 广播或寻址房间时要忽略的客户端会话 ID。这通常设置为消息的发起者，以便除该客户端之外的每个人都接收消息。要跳过多个 sid，请传递一个列表。 callback – 如果给定，将调用此函数以确认客户端已收到消息。将传递给函数的参数是客户端提供的参数。回调函数只能在寻址单个客户端时使用。

sleep(秒=0 ) 

使用适当的异步模型休眠请求的时间。

这是一个实用功能，应用程序可以使用它来使任务进入睡眠状态，而不必担心对所选异步模式使用正确的调用。

start_background_task(目标, *args , **kwargs ) 

使用适当的异步模型启动后台任务。

这是一个实用功能，应用程序可以使用与所选异步模式兼容的方法来启动后台任务。

参数：	target -- 要执行的目标函数。 args - 传递给函数的参数。 kwargs – 传递给函数的关键字参数。

此函数返回一个代表后台任务的对象，join()可以在该对象上调用方法以等待任务完成。

stop( ) 

停止正在运行的 SocketIO Web 服务器。

必须从 HTTP 或 SocketIO 处理程序函数调用此方法。

test_client( app , namespace=None , query_string= None , headers=None , auth=None , flask_test_client=None ) 

Socket.IO 测试客户端对于测试 Flask-SocketIO 服务器很有用。它的工作方式与 Flask 测试客户端类似，但适用于 Socket.IO 服务器。

参数：	app – Flask 应用程序实例。 namespace – 客户端的命名空间。如果未提供，客户端将连接到全局命名空间上的服务器。 query_string – 带有自定义查询字符串参数的字符串。 headers – 带有自定义 HTTP 标头的字典。 auth – 可选的身份验证数据，以字典形式给出。 flask_test_client – 当前使用的 Flask 测试客户端的实例。通过 Flask 测试客户端是可选的，但如果您希望 Flask 用户会话和在 HTTP 路由中设置的任何其他 cookie 可从 Socket.IO 事件访问，则这是必需的。

flask_socketio.emit(事件, *args , **kwargs ) 

发出一个 SocketIO 事件。

此函数向一个或多个连接的客户端发出 SocketIO 事件。JSON blob 可以作为有效负载附加到事件。这是一个只能从 SocketIO 事件处理程序调用的函数，就像从当前客户端上下文中获取一些信息一样。例子：

@socketio.on('my event')
def handle_my_custom_event(json):
    emit('my response', {'data': 42})

参数：

event – 要发出的用户事件的名称。 args – 包含要作为有效负载发送的 JSON 数据的字典。 namespace – 消息将在其下发送的命名空间。默认为原始事件使用的命名空间。A'/'可用于显式指定全局命名空间。 callback – 使用客户端确认调用的回调函数。 广播-True将消息发送给所有客户端，或False 仅回复原始事件的发送者。 to - 将消息发送给给定房间中的所有用户。如果此参数未设置且broadcast为False，则消息仅发送给始发用户。 include_self –True在广播或寻址房间时包含发送者，或False发送给除发送者之外的所有人。 skip_sid – 广播或寻址房间时要忽略的客户端会话 ID。这通常设置为消息的发起者，以便除该客户端之外的每个人都接收消息。要跳过多个 sid，请传递一个列表。 ignore_queue – 仅在配置消息队列时使用。如果设置为True，则事件直接发送给客户端，而不经过队列。这更有效，但仅在使用单个服务器进程或只有一个收件人时才有效。建议始终将此参数保留为默认值False。

flask_socketio.send（消息，**kwargs ）

发送 SocketIO 消息。

该函数向一个或多个连接的客户端发送一个简单的 SocketIO 消息。消息可以是字符串或 JSON blob。这是一个更简单的版本emit()，应该是首选。这是一个只能从 SocketIO 事件处理程序调用的函数。

参数：

message – 要发送的消息，可以是字符串或 JSON blob。 json –True如果message是 JSON blob，False 否则。 namespace – 消息将在其下发送的命名空间。默认为原始事件使用的命名空间。空字符串可用于使用全局命名空间。 callback – 使用客户端确认调用的回调函数。 广播——True将消息发送给所有连接的客户端，或者 False只回复原始事件的发送者。 to - 将消息发送给给定房间中的所有用户。如果此参数未设置且broadcast为False，则消息仅发送给始发用户。 include_self –True在广播或寻址房间时包含发送者，或False发送给除发送者之外的所有人。 skip_sid – 广播或寻址房间时要忽略的客户端会话 ID。这通常设置为消息的发起者，以便除该客户端之外的每个人都接收消息。要跳过多个 sid，请传递一个列表。 ignore_queue – 仅在配置消息队列时使用。如果设置为True，则事件直接发送给客户端，而不经过队列。这更有效，但仅在使用单个服务器进程或只有一个收件人时才有效。建议始终将此参数保留为默认值False。

flask_socketio.join_room（房间，sid=None，命名空间=None ）

加入一个房间。

此函数将用户置于当前命名空间下的房间中。用户和命名空间是从事件上下文中获得的。这是一个只能从 SocketIO 事件处理程序调用的函数。例子：

@socketio.on('join')
def on_join(data):
    username = session['username']
    room = data['room']
    join_room(room)
    send(username + ' has entered the room.', to=room)

参数：	room – 要加入的房间的名称。 sid – 客户端的会话 ID。如果未提供，则从请求上下文中获取客户端。 namespace – 房间的命名空间。如果未提供，则从请求上下文中获取命名空间。

flask_socketio.leave_room（房间，sid=None，命名空间=None ）

留个房间。

此函数将用户从当前命名空间下的房间中删除。用户和命名空间是从事件上下文中获得的。例子：

@socketio.on('leave')
def on_leave(data):
    username = session['username']
    room = data['room']
    leave_room(room)
    send(username + ' has left the room.', to=room)

参数：	room – 要离开的房间的名称。 sid – 客户端的会话 ID。如果未提供，则从请求上下文中获取客户端。 namespace – 房间的命名空间。如果未提供，则从请求上下文中获取命名空间。

flask_socketio.close_room（房间，命名空间=无）

关闭一个房间。

此功能删除给定房间中的所有用户，然后从服务器中删除房间。

参数：	room – 要关闭的房间的名称。 namespace – 房间的命名空间。如果未提供，则从请求上下文中获取命名空间。

flask_socketio.rooms( sid=None ,命名空间=None ) 

返回客户所在房间的列表。

该函数返回客户端进入的所有房间，包括自己的房间，由 Socket.IO 服务器分配。

参数：	sid – 客户端的会话 ID。如果未提供，则从请求上下文中获取客户端。 namespace – 房间的命名空间。如果未提供，则从请求上下文中获取命名空间。

flask_socketio.disconnect( sid=None , namespace=None , silent=False ) 

断开客户端。

此函数终止与客户端的连接。作为此调用的结果，客户端将收到断开连接事件。例子：

@socketio.on('message')
def receive_message(msg):
    if is_banned(session['username']):
        disconnect()
    else:
        # ...

参数：	sid – 客户端的会话 ID。如果未提供，则从请求上下文中获取客户端。 namespace – 房间的命名空间。如果未提供，则从请求上下文中获取命名空间。 静默- 此选项已弃用。

类flask_socketio.Namespace（命名空间=无）

close_room（房间，命名空间=无）

关闭一个房间。

emit( event , data=None , room=None , include_self=True , namespace=None , callback=None ) 

向一个或多个连接的客户端发出自定义事件。

send( data , room=None , include_self=True , namespace=None , callback=None ) 

向一个或多个连接的客户端发送消息。

trigger_event(事件, *args ) 

将事件分派到适当的处理程序方法。

在最常见的用法中，此方法不会被子类重载，因为它执行事件到方法的路由。但是，如果需要特殊的调度规则，或者如果需要一个捕获所有事件的方法，则可以覆盖此方法。

类flask_socketio.SocketIOTestClient( app , socketio , namespace=None , query_string =None , headers=None , auth=None , flask_test_client=None ) 

此类对于测试 Flask-SocketIO 服务器很有用。它的工作方式与 Flask 测试客户端类似，但适用于 Socket.IO 服务器。

参数：	app – Flask 应用程序实例。 socketio – 应用程序的SocketIO实例。 namespace – 客户端的命名空间。如果未提供，客户端将连接到全局命名空间上的服务器。 query_string – 带有自定义查询字符串参数的字符串。 headers – 带有自定义 HTTP 标头的字典。 auth – 可选的身份验证数据，以字典形式给出。 flask_test_client – 当前使用的 Flask 测试客户端的实例。通过 Flask 测试客户端是可选的，但如果您希望 Flask 用户会话和在 HTTP 路由中设置的任何其他 cookie 可从 Socket.IO 事件访问，则这是必需的。

connect( namespace=None , query_string=None , headers=None , auth=None ) 

连接客户端。

参数：	namespace – 客户端的命名空间。如果未提供，客户端将连接到全局命名空间上的服务器。 query_string – 带有自定义查询字符串参数的字符串。 headers – 带有自定义 HTTP 标头的字典。 auth – 可选的身份验证数据，以字典形式给出。

请注意，通常不需要显式调用此方法，因为在创建此类的实例时会自动建立连接。当应用程序接受多个命名空间连接时，此方法很有用的一个示例。

disconnect（命名空间=无）

断开客户端。

参数：	namespace - 要断开连接的命名空间。如果未提供此参数，则假定使用全局命名空间。

emit(事件, *args , **kwargs ) 

向服务器发送事件。

参数：	事件- 事件名称。 *参数—— 事件参数。 callback –True如果客户端请求回调，False 如果没有。请注意，客户端回调未实现，回调请求只会告诉服务器提供参数以调用回调，但不会调用回调。相反，服务器为回调提供的参数由该函数返回。 namespace – 事件的命名空间。如果未提供此参数，则假定使用全局命名空间。

get_received（命名空间=无）

返回从服务器接收到的消息列表。

由于这不是一个真正的客户端，任何时候服务器发出一个事件，该事件都会被简单地存储起来。测试代码可以调用此方法来获取自上次调用以来接收到的事件列表。

参数：	namespace – 从中获取事件的命名空间。如果未提供此参数，则假定使用全局命名空间。

is_connected（命名空间=无）

检查命名空间是否已连接。

参数：	namespace – 要检查的命名空间。如果未提供此参数，则假定使用全局命名空间。

send（数据，json=False，回调=False，命名空间=None ）

向服务器发送文本或 JSON 消息。

参数：	data -- 要发送到服务器的字符串、字典或列表。 json –True发送 JSON 消息，False发送文本消息。 callback –True如果客户端请求回调，False 如果没有。请注意，客户端回调未实现，回调请求只会告诉服务器提供参数以调用回调，但不会调用回调。相反，服务器为回调提供的参数由该函数返回。 namespace – 事件的命名空间。如果未提供此参数，则假定使用全局命名空间。