一、class 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’. 除非你知道自己在做什么，否则保持原样。
• resource – 别名path。
• kwargs – Socket.IO 和 Engine.IO 服务器选项。

对于Socket.IO，kwargs选项详述如下：

参数：

• 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，kwargs选项详述如下：

参数：

• async_mode – 要使用的异步模型。有关可用选项的说明，请参阅文档中的部署部分。有效的异步模式threading， eventlet，gevent和gevent_uwsgi。如果未给出此参数，eventlet则首先尝试，然后是 gevent_uwsgi，然后是gevent，最后是 threading。然后选择第一个安装了所有依赖项的异步模式。
• 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 – 如果设置为字符串，则它是服务器发送回包含客户端会话 ID 的客户端的 HTTP cookie 的名称。如果设置为字典，则’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_logger设置为True ，也会记录致命错误 False。

1. close_room(room,namespace=None)

关闭一个房间。

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

参数：

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

2. emit(event, *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- 如果给定，将调用此函数以确认客户端已收到消息。将传递给函数的参数是客户端提供的参数。回调函数只能在寻址单个客户端时使用。

3. 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)

4. on( message , namespace=None )

用于注册 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– 要在其上注册处理程序的命名空间。默认为全局命名空间。

5. on_error(namespace=None)

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

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

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

**参数： **

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

6. on_error_default(异常处理程序)

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

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

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

7. on_event( message , handler , namespace=None )

注册一个 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– 要在其上注册处理程序的命名空间。默认为全局命名空间。

8. 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 -甲字典与被传递到该烧瓶中reloader选项，例如extra_files， reloader_type等
• extra_files – Flask 重新加载器应该监视的附加文件列表。默认为None. 已弃用，请reloader_options改用。
• log_output – 如果True，则服务器记录所有传入连接。如果False日志被禁用。默认为True在调试模式下，False 在正常模式下。使用线程异步模式时未使用。
• kwargs – 额外的网络服务器选项。Web 服务器选项特定于每种支持的异步模式中使用的服务器。请注意，在使用外部 Web 服务器（例如 gunicorn）时，将看不到此处提供的选项，因为在这种情况下不会调用此方法。

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

10. sleep(seconds=0 )

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

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

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

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

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

参数：

• target – 要执行的目标函数。
• args – 传递给函数的参数。
• kwargs – 传递给函数的关键字参数。
  该函数返回一个代表后台任务的对象，在该对象上join()可以调用方法等待任务完成。

12. stop()

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

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

13. 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(event, *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 – 使用客户端确认调用的回调函数。
• broadcast- 如果为True则会将消息发送给所有客户端，如果为False则仅回复原始事件的发送者。
• to – 向给定房间中的所有用户发送消息。如果此参数未设置且broadcast为False，则消息仅发送给原始用户。
• include_self –如果为True则在广播或房间时会包括发件人，如果为False发送给除发件人之外的所有人。
• skip_sid – 在广播或房间时要忽略的客户端的会话 ID。这通常设置为消息的发起者，以便除该客户端之外的每个人都收到消息。要跳过多个 sid，请传递一个列表。
• ignore_queue – 仅在配置消息队列时使用。如果设置为True，则事件将直接发送到客户端，而无需通过队列。这更有效，但仅在使用单个服务器进程或只有一个收件人时才有效。建议始终保留此参数的默认值False。

三、flask_socketio.send(message, **kwargs )

发送 SocketIO 消息。

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

参数：

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

四、flask_socketio.join_room( room , sid=None , namespace=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( room , sid=None , namespace=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=None)

关闭一个房间。

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

参数：

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

七、flask_socketio.rooms( sid=None , namespace=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– 房间的命名空间。如果未提供，则从请求上下文中获取命名空间。
• silent- 此选项已弃用。

九、class flask_socketio.Namespace(namespace=None)

close_room(room,namespace=None)
关闭一个房间。

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

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

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

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

3. trigger_event(event, *args )

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

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

十、class flask_socketio.SocketIOTestClient(app, socketio, namespace=None, QUERY_STRING=None, title=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 事件访问，则这是必要的。

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

连接客户端。

参数：

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

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

2. disconnect(namespace=None)

断开客户端。

参数：

• namespace– 要断开连接的命名空间。如果未提供此参数，则假定为全局命名空间。

3. emit(event, *args , **kwargs )

向服务器发出事件。

参数：

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

4. get_received(namespace=None)

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

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

参数：

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

5. is_connected(namespace=None)

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

参数：

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

6. send( data , json=False , callback=False , namespace=None )

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

参数：

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