Server

class socketio.Server(client_manager=None, logger=False, serializer='default', json=None, async_handlers=True, always_connect=False, namespaces=None, **kwargs)

一个 Socket.IO 服务器。

该类实现了一个完全兼容的 Socket.IO Web 服务器，支持 WebSocket 和长轮询传输。

参数

  • client_manager：管理客户端列表的客户端管理器实例。若省略此参数，客户端列表将存储在内存结构中，因此无法使用多个连接的服务器。
  • logger：若要启用日志记录，可将其设为 True 或传入一个日志记录器对象；若要禁用日志记录，可将其设为 False。默认值为 False。请注意，即使 logger 为 False，严重错误仍会被记录。
  • serializer：传输数据包时使用的序列化方法。有效值为 'default'、'pickle'、'msgpack' 和 'cbor'。或者，也可以提供 Packet 类的子类，并自定义实现 encode() 和 decode() 方法。客户端和服务器必须使用兼容的序列化器。
  • json：用于对数据包进行编码和解码的替代 JSON 模块。自定义 JSON 模块必须具备与标准库版本兼容的 dumps 和 loads 函数。
  • async_handlers：若设为 True，客户端的事件处理程序将在单独的线程中执行。若要同步运行客户端的处理程序，可将其设为 False。默认值为 True。
  • always_connect：若设为 False，新连接在 connect 处理程序返回非 False 的值之前是临时的，此时连接才会被接受。若设为 True，连接将立即被接受，然后如果 connect 处理程序返回 False，则会发起断开连接操作。如果需要从 connect 处理程序中发出事件，并且客户端在连接接受之前收到事件时会产生混淆，可将其设为 True。在其他情况下，使用默认值 False。
  • namespaces：除已定义处理程序的命名空间外，允许的命名空间列表。默认值为 ['/']，即始终允许连接到默认命名空间。将其设为 '*' 可允许所有命名空间。
  • kwargs：底层 Engine.IO 服务器的连接参数。

Engine.IO 配置支持以下设置

  • async_mode：要使用的异步模型。请参阅文档中的 “部署” 部分以了解可用选项的描述。有效的异步模式包括 'threading'、'eventlet'、'gevent' 和 'gevent_uwsgi'。如果未提供此参数，服务器将首先尝试使用 'eventlet'，然后是 'gevent_uwsgi'，接着是 'gevent'，最后是 'threading'。选择第一个已安装所有依赖项的异步模式。
  • ping_interval：服务器向客户端发送心跳包的时间间隔（秒）。默认值为 25 秒。若需要更精细的控制，可提供一个包含两个元素的元组，其中第一个数字是心跳间隔，第二个数字是服务器添加的宽限期。
  • ping_timeout：客户端在断开连接之前等待服务器响应的时间（秒）。默认值为 20 秒。
  • max_http_buffer_size：接受的传入消息的最大大小。默认值为 1000000 字节。尽管名称如此，但此参数设置的值对 HTTP 长轮询和 WebSocket 连接均有效。
  • allow_upgrades：是否允许传输升级。默认值为 True。
  • http_compression：使用长轮询传输时是否压缩数据包。默认值为 True。
  • compression_threshold：仅当消息的字节大小大于此值时才进行压缩。默认值为 1024 字节。
  • cookie：若设置为字符串，则为服务器发送回客户端的包含客户端会话 ID 的 HTTP cookie 名称。若设置为字典，'name' 键包含 cookie 名称，其他键定义 cookie 属性，每个属性的值可以是字符串、无参数的可调用对象或布尔值。若设置为 None（默认值），则不向客户端发送 cookie。
  • cors_allowed_origins：允许连接到此服务器的源或源列表。默认情况下，仅允许同源连接。将此参数设置为 '*' 以允许所有源，或设置为 [] 以禁用 CORS 处理。
  • cors_credentials：是否允许在向此服务器的请求中携带凭证（cookie、身份验证）。默认值为 True。
  • monitor_clients：若设置为 True，后台任务将确保关闭不活跃的客户端。将其设置为 False 可禁用监控任务（不建议）。默认值为 True。
  • transports：允许的传输列表。有效的传输方式有 'polling' 和 'websocket'。默认值为 ['polling', 'websocket']。
  • engineio_logger：若要启用 Engine.IO 日志记录，可将其设为 True 或传入一个日志记录器对象；若要禁用日志记录，可将其设为 False。默认值为 False。请注意，即使 engineio_logger 为 False，严重错误仍会被记录。

call(event, data=None, to=None, sid=None, namespace=None, timeout=60, ignore_queue=False)

向客户端发出自定义事件并等待响应。

此方法会发出一个带有回调的事件，并在回调被调用后才返回。若在超时前回调未被调用，则会引发 TimeoutError 异常。若在等待期间 Socket.IO 连接断开，此方法仍会等待至指定的超时时间。

参数

  • event：事件名称，可以是任意字符串。'connect'、'message' 和 'disconnect' 这些事件名称是保留名称，不应使用。
  • data：要发送给客户端的数据。数据类型可以是 str、bytes、list 或 dict。若要发送多个参数，可使用元组，其中每个元素的类型应为上述类型之一。
  • to：接收客户端的会话 ID。
  • sid：to 参数的别名。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，则事件将发送到默认命名空间。
  • timeout：等待超时时间。若在客户端确认事件之前超时，则会引发 TimeoutError 异常。
  • ignore_queue：仅在配置了消息队列时使用。若设置为 True，事件将直接发送给客户端，而不经过队列。这样更高效，但仅在使用单个服务器进程时有效。建议始终将此参数保留为默认值 False。

注意：此方法不是线程安全的。若多个线程同时向同一个客户端发出事件，则由多个数据包组成的消息可能会以错误的顺序发送。可使用标准的并发解决方案（如 Lock 对象）来避免这种情况。

close_room(room, namespace=None)

        关闭一个房间。

此函数会将给定房间中的所有客户端移除。

参数

  • room：房间名称。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，则使用默认命名空间。

disconnect(sid, namespace=None, ignore_queue=False)

        断开客户端的连接。

参数

  • sid：客户端的会话 ID。
  • namespace：要断开连接的 Socket.IO 命名空间。若省略此参数，则使用默认命名空间。
  • ignore_queue：仅在配置了消息队列时使用。若设置为 True，断开连接操作将在本地处理，而不在队列上广播。建议始终将此参数保留为默认值 False。

emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)

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

参数

  • event：事件名称，可以是任意字符串。'connect'、'message' 和 'disconnect' 这些事件名称是保留名称，不应使用。
  • data：要发送给客户端的数据。数据类型可以是 str、bytes、list 或 dict。若要发送多个参数，可使用元组，其中每个元素的类型应为上述类型之一。
  • to：消息的接收方。可以设置为客户端的会话 ID 以仅向该客户端发送消息，也可以设置为应用程序创建的任何自定义房间名称以向该房间中的所有客户端发送消息，或者设置为自定义房间名称列表。若省略此参数，则事件将广播给所有已连接的客户端。
  • room：to 参数的别名。
  • skip_sid：在向房间或所有客户端广播时要跳过的客户端会话 ID。这可用于防止消息发送给发送者。若要跳过多个会话 ID，可传递一个列表。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，则事件将发送到默认命名空间。
  • callback：若提供此参数，则在客户端确认收到消息时会调用此函数。传递给该函数的参数由客户端提供。回调函数仅在向单个客户端发送消息时可用。
  • ignore_queue：仅在配置了消息队列时使用。若设置为 True，事件将直接发送给客户端，而不经过队列。这样更高效，但仅在使用单个服务器进程时有效。建议始终将此参数保留为默认值 False。

注意：此方法不是线程安全的。若多个线程同时向同一个客户端发出事件，则由多个数据包组成的消息可能会以错误的顺序发送。可使用标准的并发解决方案（如 Lock 对象）来避免这种情况。

enter_room(sid, room, namespace=None)

        加入一个房间。

此函数会将客户端添加到一个房间中。emit() 和 send() 函数可以选择将事件广播给房间中的所有客户端。

参数

  • sid：客户端的会话 ID。
  • room：房间名称。若房间不存在，则会创建该房间。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，则使用默认命名空间。

event(*args, **kwargs)

        用于注册事件处理程序的装饰器。

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

示例用法

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

上述示例等同于：

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

可以将自定义命名空间作为参数传递给装饰器：

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

get_environ(sid, namespace=None)

        返回客户端的 WSGI 环境字典。

参数

  • sid：客户端的会话 ID。
  • namespace：Socket.IO 命名空间。若省略此参数，则使用默认命名空间。

get_session(sid, namespace=None)

        返回客户端的用户会话。

参数

  • sid：客户端的会话 ID。
  • namespace：Socket.IO 命名空间。若省略此参数，则使用默认命名空间。

返回值是一个字典。除非调用 save_session() 方法或使用会话上下文管理器，否则对该字典所做的修改不一定会被保留。

handle_request(environ, start_response)

        处理客户端的 HTTP 请求。

这是 Socket.IO 应用程序的入口点，使用与 WSGI 应用程序相同的接口。在典型用法中，此函数由中间件实例调用，但在不使用中间件时也可以直接调用。

参数

  • environ：WSGI 环境。
  • start_response：WSGI 的 start_response 函数。

此函数返回要作为字节序列传递给客户端的 HTTP 响应体。

instrument(auth=None, mode='development', read_only=False, server_id=None, namespace='/admin', server_stats_interval=2)

为 Socket.IO 服务器配置监控功能，以便通过 Socket.IO 管理界面进行监控。

参数

  • auth：访问管理界面的认证凭证。可设置为包含预期登录信息（通常是用户名和密码）的字典，若需要多个凭证集，可设置为字典列表。对于更复杂的认证方法，可设置为一个可调用对象，该对象接收认证字典作为参数，若用户被允许则返回 True，否则返回 False。若要禁用认证，可将此参数设置为 False（不建议在生产服务器上这样做）。
  • mode：报告模式。默认值为 'development'，此模式最适合调试时使用，因为它可能会对性能产生显著影响。将其设置为 'production' 可减少报告给管理界面的信息量。
  • read_only：若设置为 True，管理界面将为只读模式，无法修改房间分配或断开客户端连接。默认值为 False。
  • server_id：此服务器使用的服务器名称。若省略此参数，服务器将自行生成名称。
  • namespace：管理界面使用的 Socket.IO 命名空间。默认值为 /admin。
  • server_stats_interval：服务器向所有已连接的管理员发送统计信息摘要的时间间隔（秒）。

leave_room(sid, room, namespace=None)

        离开一个房间。

此函数会将客户端从房间中移除。

参数

  • sid：客户端的会话 ID。
  • room：房间名称。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，则使用默认命名空间。

on(event, handler=None, namespace=None)

        注册事件处理程序。

参数

  • event：事件名称，可以是任意字符串。'connect'、'message' 和 'disconnect' 这些事件名称是保留名称，不应使用。'*' 事件名称可用于定义一个通用事件处理程序。
  • handler：处理事件时应调用的函数。若未提供此参数，则该方法将作为处理函数的装饰器。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，则处理程序将与默认命名空间关联。可以通过传递 '*' 作为命名空间来定义一个通用命名空间。

示例用法

# 作为装饰器：
@sio.on('connect', namespace='/chat')
def connect_handler(sid, environ):
    print('Connection request')
    if environ['REMOTE_ADDR'] in blacklisted:
        return False  # 拒绝连接

# 作为方法：
def message_handler(sid, msg):
    print('Received message: ', msg)
    sio.send(sid, 'response')
socket_io.on('message', namespace='/chat', handler=message_handler)

传递给处理函数的参数取决于事件类型：

  • 'connect' 事件处理程序接收客户端的 sid（会话 ID）和 WSGI 环境字典作为参数。
  • 'disconnect' 处理程序仅接收客户端的 sid 作为参数。
  • 'message' 处理程序和自定义事件名称的处理程序接收客户端的 sid 和消息负载作为参数。若消息处理程序返回任何值，则会将其传递给客户端的确认回调函数（若存在）。
  • 通用事件处理程序会将事件名称作为第一个参数，后跟特定于该事件的任何参数。
  • 通用命名空间事件处理程序会将命名空间作为第一个参数，后跟特定于该事件的任何参数。
  • 通用命名空间和通用事件处理程序会将事件名称作为第一个参数，命名空间作为第二个参数，后跟特定于该事件的任何参数。

class reason

        断开连接的原因。

  • CLIENT_DISCONNECT = 'client disconnect'：客户端发起的断开连接。
  • PING_TIMEOUT = 'ping timeout'：心跳超时。
  • SERVER_DISCONNECT = 'server disconnect'：服务器发起的断开连接。
  • TRANSPORT_CLOSE = 'transport close'：传输关闭。
  • TRANSPORT_ERROR = 'transport error'：传输错误。

register_namespace(namespace_handler)

        注册命名空间处理程序对象。

参数

  • namespace_handler：Namespace 子类的实例，用于处理命名空间的所有事件流量。

rooms(sid, namespace=None)

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

参数

  • sid：客户端的会话 ID。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，则使用默认命名空间。

save_session(sid, session, namespace=None)

存储客户端的用户会话。

参数

  • sid：客户端的会话 ID。
  • session：会话字典。
  • namespace：Socket.IO 命名空间。若省略此参数，则使用默认命名空间。

send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)

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

此函数会发出一个名为 'message' 的事件。若要发出自定义事件名称，请使用 emit()。

参数

  • data：要发送给客户端的数据。数据类型可以是 str、bytes、list 或 dict。若要发送多个参数，可使用元组，其中每个元素的类型应为上述类型之一。
  • to：消息的接收方。可以设置为客户端的会话 ID 以仅向该客户端发送消息，也可以设置为应用程序创建的任何自定义房间名称以向该房间中的所有客户端发送消息，或者设置为自定义房间名称列表。若省略此参数，则事件将广播给所有已连接的客户端。
  • room：to 参数的别名。
  • skip_sid：在向房间或所有客户端广播时要跳过的客户端会话 ID。这可用于防止消息发送给发送者。若要跳过多个会话 ID，可传递一个列表。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，则事件将发送到默认命名空间。
  • callback：若提供此参数，则在客户端确认收到消息时会调用此函数。传递给该函数的参数由客户端提供。回调函数仅在向单个客户端发送消息时可用。
  • ignore_queue：仅在配置了消息队列时使用。若设置为 True，事件将直接发送给客户端，而不经过队列。这样更高效，但仅在使用单个服务器进程时有效。建议始终将此参数保留为默认值 False。

session(sid, namespace=None)

        使用上下文管理器语法返回客户端的用户会话。

参数

  • sid：客户端的会话 ID。

这是一个上下文管理器，它返回客户端的用户会话字典。在上下文管理器块内对该字典所做的任何更改都会保存回会话中。

示例用法

@sio.on('connect')
def on_connect(sid, environ):
    username = authenticate_user(environ)
    if not username:
        return False
    with sio.session(sid) as session:
        session['username'] = username

@sio.on('message')
def on_message(sid, msg):
    with sio.session(sid) as session:
        print('received message from ', session['username'])

shutdown()

        停止 Socket.IO 后台任务。

此方法会停止 Socket.IO 服务器启动的所有后台活动。在关闭 Web 服务器之前必须调用此方法。

sleep(seconds=0)

        使用适当的异步模型休眠指定的时间。

这是一个实用函数，应用程序可以使用它来使任务休眠，而无需担心为所选的异步模式使用正确的调用。

start_background_task(target, *args, **kwargs)

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

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

参数

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

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

transport(sid, namespace=None)

        返回客户端使用的传输名称。

此函数返回的两个可能值为 'polling' 和 'websocket'。

参数

  • sid：客户端的会话 ID。
  • namespace：Socket.IO 命名空间。若省略此参数，则使用默认命名空间。

AsyncServer

class socketio.AsyncServer(client_manager=None, logger=False, json=None, async_handlers=True, namespaces=None, **kwargs) 

        适用于 asyncio 的 Socket.IO 服务器。

该类实现了一个完全兼容的 Socket.IO Web 服务器，支持 WebSocket 和长轮询传输方式，与 asyncio 框架兼容。

参数

  • client_manager：管理客户端列表的客户端管理器实例。若省略此参数，客户端列表将存储在内存结构中，此时无法使用多个连接的服务器。
  • logger：若要启用日志记录，可将其设为 True，或传入一个日志记录器对象。若要禁用日志记录，设为 False。需注意，即便 logger 为 False，严重错误仍会被记录。
  • json：用于对数据包进行编码和解码的替代 JSON 模块。自定义 JSON 模块必须具备与标准库版本兼容的 dumps 和 loads 函数。
  • async_handlers：若设为 True，客户端的事件处理程序将在单独的线程中执行。若要同步运行客户端的处理程序，设为 False。默认值为 True。
  • always_connect：设为 False 时，新连接处于临时状态，直至连接处理程序返回非 False 的值，此时连接才会被接受。设为 True 时，连接会立即被接受，若连接处理程序返回 False，则会发出断开连接的指令。若你需要从连接处理程序中发出事件，且客户端在连接接受前收到事件会产生混淆，可将其设为 True。在其他情况下，使用默认值 False 即可。
  • namespaces：除已定义处理程序的命名空间外，允许的命名空间列表。默认值为 ['/']，即始终接受对默认命名空间的连接。设为 '*' 可接受所有命名空间。
  • kwargs：底层 Engine.IO 服务器的连接参数。

Engine.IO 配置支持以下设置

参数

  • async_mode：要使用的异步模式。有关可用选项的描述，请参阅文档中的 “部署” 部分。有效的异步模式包括 “aiohttp”、“sanic”、“tornado” 和 “asgi”。若未提供此参数，会先尝试 “aiohttp”，接着是 “sanic”、“tornado”，最后是 “asgi”。选择首个已安装所有依赖项的异步模式。
  • ping_interval：服务器向客户端发送心跳包的时间间隔（秒）。默认值为 25 秒。若需要更高级的控制，可传入一个二元元组，第一个数字为心跳间隔，第二个数字为服务器添加的宽限期。
  • ping_timeout：客户端在断开连接前等待服务器响应的时间（秒）。默认值为 20 秒。
  • max_http_buffer_size：接受的传入消息的最大大小。默认值为 1000000 字节。尽管名称如此，但此参数设置的值对 HTTP 长轮询和 WebSocket 连接均有效。
  • allow_upgrades：是否允许传输升级。默认值为 True。
  • http_compression：使用轮询传输时是否压缩数据包。默认值为 True。
  • compression_threshold：仅当消息字节大小大于此值时才进行压缩。默认值为 1024 字节。
  • cookie：若设为字符串，它是服务器发送回客户端的包含客户端会话 ID 的 HTTP cookie 名称。若设为字典，name 键包含 cookie 名称，其他键定义 cookie 属性，每个属性的值可以是字符串、无参数的可调用对象或布尔值。若设为 None（默认值），则不会向客户端发送 cookie。
  • cors_allowed_origins：允许连接到该服务器的源或源列表。默认情况下，仅允许同源。将此参数设为 '*' 可允许所有源，设为 [] 可禁用 CORS 处理。
  • cors_credentials：请求此服务器时是否允许携带凭证（cookie、身份验证）。默认值为 True。
  • monitor_clients：若设为 True，后台任务将确保关闭不活跃的客户端。设为 False 可禁用监控任务（不建议）。默认值为 True。
  • transports：允许的传输方式列表。有效的传输方式为 'polling' 和 'websocket'。默认值为 ['polling', 'websocket']。
  • engineio_logger：若要启用 Engine.IO 日志记录，可将其设为 True，或传入一个日志记录器对象。若要禁用日志记录，设为 False。默认值为 False。需注意，即便 engineio_logger 为 False，严重错误仍会被记录。

attach(app, socketio_path='socket.io')

        将 Socket.IO 服务器附加到应用程序。

async call(event, data=None, to=None, sid=None, namespace=None, timeout=60, ignore_queue=False)

        向客户端发出自定义事件并等待响应。

此方法会发出带有回调的事件，并在返回前等待回调被调用。若回调在超时前未被调用，则会抛出 TimeoutError 异常。若在等待期间 Socket.IO 连接断开，此方法仍会等待至指定的超时时间。

参数

  • event：事件名称。可以是任意字符串。'connect'、'message' 和 'disconnect' 为保留事件名称，请勿使用。
  • data：要发送给客户端的数据。数据类型可以是 str、bytes、list 或 dict。若要发送多个参数，可使用元组，元组中的每个元素应为上述类型之一。
  • to：接收客户端的会话 ID。
  • sid：to 参数的别名。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，事件将发送到默认命名空间。
  • timeout：等待超时时间。若在客户端确认事件之前超时，则会抛出 TimeoutError 异常。
  • ignore_queue：仅在配置了消息队列时使用。若设为 True，事件将直接发送给客户端，不经过队列。这样更高效，但仅在使用单个服务器进程时有效。建议始终将此参数保留为默认值 False。

注意事项

  • 此方法并非设计用于并发使用。若多个任务同时向同一客户端连接发出事件，则由多个数据包组成的消息可能会以错误的顺序发送。可使用标准并发解决方案（如 Lock 对象）来避免这种情况。
  • 此方法是一个协程。

async close_room(room, namespace=None)

        关闭一个房间。

此函数会将所有客户端从指定房间移除。

参数

  • room：房间名称。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，将使用默认命名空间。

注意事项

        此方法是一个协程。

async disconnect(sid, namespace=None, ignore_queue=False)

        断开客户端连接。

参数

  • sid：客户端的会话 ID。
  • namespace：要断开连接的 Socket.IO 命名空间。若省略此参数，将使用默认命名空间。
  • ignore_queue：仅在配置了消息队列时使用。若设为 True，断开连接操作将在本地处理，不通过队列广播。建议始终将此参数保留为默认值 False。

注意事项：此方法是一个协程。

async emit(event, data=None, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)

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

参数

  • event：事件名称。可以是任意字符串。'connect'、'message' 和 'disconnect' 为保留事件名称，请勿使用。
  • data：要发送给客户端的数据。数据类型可以是 str、bytes、list 或 dict。若要发送多个参数，可使用元组，元组中的每个元素应为上述类型之一。
  • to：消息的接收者。可以设置为客户端的会话 ID 以仅向该客户端发送消息，也可以设置为应用程序创建的任何自定义房间，以向该房间中的所有客户端发送消息，还可以设置为自定义房间名称列表。若省略此参数，事件将广播给所有连接的客户端。
  • room：to 参数的别名。
  • skip_sid：广播到房间或所有客户端时要跳过的客户端会话 ID。可用于防止消息发送给发送者。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，事件将发送到默认命名空间。
  • callback：若提供此参数，此函数将在客户端确认收到消息时被调用。传递给该函数的参数由客户端提供。回调函数仅在针对单个客户端时可用。
  • ignore_queue：仅在配置了消息队列时使用。若设为 True，事件将直接发送给客户端，不经过队列。这样更高效，但仅在使用单个服务器进程时有效。建议始终将此参数保留为默认值 False。

注意事项

  • 此方法并非设计用于并发使用。若多个任务同时向同一客户端连接发出事件，则由多个数据包组成的消息可能会以错误的顺序发送。可使用标准并发解决方案（如 Lock 对象）来避免这种情况。
  • 此方法是一个协程。

async enter_room(sid, room, namespace=None)

        进入一个房间。

此函数会将客户端添加到一个房间。emit() 和 send() 函数可选择将事件广播到房间中的所有客户端。

参数

  • sid：客户端的会话 ID。
  • room：房间名称。若房间不存在，则会创建该房间。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，将使用默认命名空间。

注意事项

此方法是一个协程。

event(*args, **kwargs)

        用于注册事件处理程序的装饰器。

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

示例用法

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

上述示例等同于：

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

可以将自定义命名空间作为参数传递给装饰器：

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

get_environ(sid, namespace=None)

        返回客户端的 WSGI 环境字典。

参数

  • sid：客户端的会话 ID。
  • namespace：Socket.IO 命名空间。若省略此参数，将使用默认命名空间。

async get_session(sid, namespace=None)

        返回客户端的用户会话。

参数

  • sid：客户端的会话 ID。
  • namespace：Socket.IO 命名空间。若省略此参数，将使用默认命名空间。

返回值为一个字典。对该字典所做的修改不一定会被保存。若要修改用户会话，请使用 session 上下文管理器。

async handle_request(*args, **kwargs)

        处理来自客户端的 HTTP 请求。

这是 Socket.IO 应用程序的入口点。此函数返回要发送给客户端的 HTTP 响应主体。

注意事项： 此方法是一个协程。

instrument(auth=None, mode='development', read_only=False, server_id=None, namespace='/admin', server_stats_interval=2)

为 Socket.IO 服务器配置监控，以便使用 Socket.IO 管理界面进行监控。

参数

  • auth：管理界面访问的身份验证凭据。可设置为包含预期登录信息（通常为用户名和密码）的字典，若需要多个凭据集，可设置为字典列表。对于更复杂的身份验证方法，可设置为一个可调用对象，该对象接收身份验证字典作为参数，若用户被允许则返回 True，否则返回 False。若要禁用身份验证，将此参数设为 False（不建议，切勿在生产服务器上这样做）。
  • mode：报告模式。默认值为 'development'，此模式最适合调试时使用，因为它可能会对性能产生显著影响。设为 'production' 可减少报告给管理界面的信息量。
  • read_only：若设为 True，管理界面将为只读模式，无法修改房间分配或断开客户端连接。默认值为 False。
  • server_id：此服务器使用的服务器名称。若省略此参数，服务器将生成自己的名称。
  • namespace：管理界面使用的 Socket.IO 命名空间。默认值为 /admin。
  • server_stats_interval：服务器向所有连接的管理员发出统计信息摘要的时间间隔（秒）。

async leave_room(sid, room, namespace=None)

        离开一个房间。

此函数会将客户端从房间中移除。

参数

  • sid：客户端的会话 ID。
  • room：房间名称。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，将使用默认命名空间。

注意事项： 此方法是一个协程。

on(event, handler=None, namespace=None)

        注册事件处理程序。

参数

  • event：事件名称。可以是任意字符串。'connect'、'message' 和 'disconnect' 为保留事件名称，请勿使用。'*' 事件名称可用于定义通用事件处理程序。
  • handler：处理事件时应调用的函数。若未提供此参数，该方法将作为处理程序函数的装饰器。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，处理程序将与默认命名空间关联。通过传递 '*' 作为命名空间，可定义通用命名空间。

示例用法

# 作为装饰器
@sio.on('connect', namespace='/chat')
def connect_handler(sid, environ):
    print('Connection request')
    if environ['REMOTE_ADDR'] in blacklisted:
        return False  # 拒绝连接

# 作为方法
def message_handler(sid, msg):
    print('Received message: ', msg)
    sio.send(sid, 'response')
socket_io.on('message', namespace='/chat', handler=message_handler)

传递给处理程序函数的参数取决于事件类型：

  • 'connect' 事件处理程序接收客户端的 sid（会话 ID）和 WSGI 环境字典作为参数。
  • 'disconnect' 处理程序仅接收客户端的 sid 作为参数。
  • 'message' 处理程序和自定义事件名称的处理程序接收客户端的 sid 和消息负载作为参数。消息处理程序返回的任何值都将传递给客户端的确认回调函数（若存在）。
  • 通用事件处理程序接收事件名称作为第一个参数，后跟事件特定的任何参数。
  • 通用命名空间事件处理程序接收命名空间作为第一个参数，后跟事件特定的任何参数。
  • 通用命名空间和通用事件处理程序接收事件名称作为第一个参数，命名空间作为第二个参数，后跟事件特定的任何参数。

class reason

        断开连接的原因。

  • CLIENT_DISCONNECT = 'client disconnect'：客户端发起的断开连接。
  • PING_TIMEOUT = 'ping timeout'：心跳超时。
  • SERVER_DISCONNECT = 'server disconnect'：服务器发起的断开连接。
  • TRANSPORT_CLOSE = 'transport close'：传输关闭。
  • TRANSPORT_ERROR = 'transport error'：传输错误。

register_namespace(namespace_handler)

注册命名空间处理程序对象。

参数

  • namespace_handler：Namespace 子类的实例，用于处理命名空间的所有事件流量。

rooms(sid, namespace=None)

返回客户端所在的房间。

参数

  • sid：客户端的会话 ID。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，将使用默认命名空间。

async save_session(sid, session, namespace=None)

        存储客户端的用户会话。

参数

  • sid：客户端的会话 ID。
  • session：会话字典。
  • namespace：Socket.IO 命名空间。若省略此参数，将使用默认命名空间。

async send(data, to=None, room=None, skip_sid=None, namespace=None, callback=None, ignore_queue=False)

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

此函数会发出名为 'message' 的事件。若要发出自定义事件名称，请使用 emit()。

参数

  • data：要发送给客户端的数据。数据类型可以是 str、bytes、list 或 dict。若要发送多个参数，可使用元组，元组中的每个元素应为上述类型之一。
  • to：消息的接收者。可以设置为客户端的会话 ID 以仅向该客户端发送消息，也可以设置为应用程序创建的任何自定义房间，以向该房间中的所有客户端发送消息，还可以设置为自定义房间名称列表。若省略此参数，事件将广播给所有连接的客户端。
  • room：to 参数的别名。
  • skip_sid：广播到房间或所有客户端时要跳过的客户端会话 ID。可用于防止消息发送给发送者。
  • namespace：事件的 Socket.IO 命名空间。若省略此参数，事件将发送到默认命名空间。
  • callback：若提供此参数，此函数将在客户端确认收到消息时被调用。传递给该函数的参数由客户端提供。回调函数仅在针对单个客户端时可用。
  • ignore_queue：仅在配置了消息队列时使用。若设为 True，事件将直接发送给客户端，不经过队列。这样更高效，但仅在使用单个服务器进程时有效。建议始终将此参数保留为默认值 False。

注意事项

  • 此方法并非设计用于并发使用。若多个任务同时向同一客户端连接发出事件，则由多个数据包组成的消息可能会以错误的顺序发送。可使用标准并发解决方案（如 Lock 对象）来避免这种情况。
  • 此方法是一个协程。

session(sid, namespace=None)

        使用上下文管理器语法返回客户端的用户会话。

参数

  • sid：客户端的会话 ID。

这是一个上下文管理器，它返回客户端的用户会话字典。在上下文管理器块内对该字典所做的任何更改都会保存回会话。

示例用法

@eio.on('connect')
def on_connect(sid, environ):
    username = authenticate_user(environ)
    if not username:
        return False
    with eio.session(sid) as session:
        session['username'] = username

@eio.on('message')
def on_message(sid, msg):
    async with eio.session(sid) as session:
        print('received message from ', session['username'])

async shutdown()

        停止 Socket.IO 后台任务。

此方法会停止 Socket.IO 服务器启动的所有后台活动。在关闭 Web 服务器之前，必须调用此方法。

async sleep(seconds=0)

        使用适当的异步模型暂停指定的时间。

这是一个实用函数，应用程序可以使用它来暂停任务，而无需担心为所选的异步模式使用正确的调用。

注意事项：此方法是一个协程。

start_background_task(target, *args, **kwargs)

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

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

参数

  • target：要执行的目标函数。必须是一个协程。
  • args：传递给函数的参数。
  • kwargs：传递给函数的关键字参数。

返回值是一个 asyncio.Task 对象。

transport(sid, namespace=None)

        返回客户端使用的传输方式名称。

此函数返回的两个可能值是 'polling' 和 'websocket'。

参数

  • sid：客户端的会话 ID。
  • namespace：Socket.IO 命名空间。若省略此参数，将使用默认命名空间。

python-socketio文档1--（简介）-CSDN博客

python-socketio文档2--（客户端）-CSDN博客

python-socketio文档3--（服务端）-CSDN博客

python-socketio文档4--（API Client）-CSDN博客

python-socketio文档5--（API Server）-CSDN博客

python-socketio文档6--（API App、Namespace）-CSDN博客

python-socketio文档7--（API Manager）-CSDN博客

已经合并成pdf，下载地址如下

https://download.csdn.net/download/jackaso/90557014?spm=1001.2014.3001.5503

# python # github # 开发语言
Logo
火山引擎 ADG 社区

火山引擎开发者社区是火山引擎打造的AI技术生态平台，聚焦Agent与大模型开发，提供豆包系列模型（图像/视频/视觉）、智能分析与会话工具，并配套评测集、动手实验室及行业案例库。社区通过技术沙龙、挑战赛等活动促进开发者成长，新用户可领50万Tokens权益，助力构建智能应用。

更多推荐

OpenClaw 本地部署完整指南（Windows + Ollama）

本文档基于实际部署经验编写，旨在帮助你在 Windows 系统上从零开始搭建 OpenClaw，并连接本地 Ollama 模型（如 Qwen2.5 或 Qwen3），使其具备完整的智能体能力。文档包含了所有关键步骤以及常见问题的解决方案。

avatar 火山引擎 ADG 社区

OpenClaw 小白安装指南（Windows版）

（类似一个能自动执行任务的AI机器人），不是游戏。API Key只保存在你本地电脑的加密文件里，不会上传到任何地方。访问：https://github.com/miaoxworld/openclaw-manager/releases。: 一键安装脚本会自动安装Node.js 22+，如果失败，手动下载安装：https://nodejs.org/：在PowerShell中，鼠标右键就是粘贴，不需要按

avatar 火山引擎 ADG 社区

飞书 × OpenClaw 接入指南：不用服务器，用长连接把机器人跑起来

这个项目存在的意义，就是把“飞书接 OpenClaw”这件事，整理成一套的配置入口，并把官方文档没覆盖到的坑集中写成排查清单。先说清楚它的角色：OpenClaw 现在已经内置官方飞书插件 @openclaw/feishu，功能更完整、维护也更及时。，说明飞书 + AI 的接入已经走通。另外，仓库也推荐了一个新项目：把 OpenClaw 变成“多 Agent 团队”，用多个 Agent 分工，Sla

avatar 火山引擎 ADG 社区