Managers¶

class socketio.Manager¶

Manage client connections.

This class keeps track of all the clients and the rooms they are in, to support the broadcasting of messages. The data used by this class is stored in a memory structure, making it appropriate only for single process services. More sophisticated storage backends can be implemented by subclasses.

close_room(room, namespace)¶: Remove all participants from a room.

connect(eio_sid, namespace)¶: Register a client connection to a namespace.

disconnect(sid, namespace, **kwargs)¶: Register a client disconnect from a namespace.

emit(event, data, namespace, room=None, skip_sid=None, callback=None, to=None, **kwargs)¶: Emit a message to a single client, a room, or all the clients connected to the namespace.

enter_room(sid, namespace, room, eio_sid=None)¶: Add a client to a room.

get_namespaces()¶: Return an iterable with the active namespace names.

get_participants(namespace, room)¶

Return an iterable with the active participants in a room.

Note that in a multi-server scenario this method only returns the participants connect to the server in which the method is called. There is currently no functionality to assemble a complete list of users across multiple servers.

get_rooms(sid, namespace)¶: Return the rooms a client is in.

initialize()¶: Invoked before the first request is received. Subclasses can add their initialization code here.

leave_room(sid, namespace, room)¶: Remove a client from a room.

pre_disconnect(sid, namespace)¶

Put the client in the to-be-disconnected list.

This allows the client data structures to be present while the disconnect handler is invoked, but still recognize the fact that the client is soon going away.

trigger_callback(sid, id, data)¶: Invoke an application callback.

class socketio.PubSubManager(channel='socketio', write_only=False, logger=None, json=None)¶

Manage a client list attached to a pub/sub backend.

This is a base class that enables multiple servers to share the list of clients, with the servers communicating events through a pub/sub backend. The use of a pub/sub backend also allows any client connected to the backend to emit events addressed to Socket.IO clients.

The actual backends must be implemented by subclasses, this class only provides a pub/sub generic framework.

Parameters:

channel – The channel name on which the server sends and receives notifications.
write_only – If set to True, only initialize to emit events. The default of False initializes the class for emitting and receiving. A write-only instance can be used independently of the server to emit to clients from an external process.
logger – a custom logger to log it. If not given, the server logger is used.
json – An alternative JSON module to use for encoding and decoding packets. Custom json modules must have dumps and loads functions that are compatible with the standard library versions. This setting is only used when write_only is set to True. Otherwise the JSON module configured in the server is used.

close_room(room, namespace=None)¶: Remove all participants from a room.

connect(eio_sid, namespace)¶: Register a client connection to a namespace.

disconnect(sid, namespace=None, **kwargs)¶: Register a client disconnect from a namespace.

emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)¶

Emit a message to a single client, a room, or all the clients connected to the namespace.

This method takes care or propagating the message to all the servers that are connected through the message queue.

The parameters are the same as in Server.emit().

enter_room(sid, namespace, room, eio_sid=None)¶: Add a client to a room.

get_namespaces()¶: Return an iterable with the active namespace names.

get_participants(namespace, room)¶

Return an iterable with the active participants in a room.

get_rooms(sid, namespace)¶: Return the rooms a client is in.

initialize()¶: Invoked before the first request is received. Subclasses can add their initialization code here.

leave_room(sid, namespace, room)¶: Remove a client from a room.

pre_disconnect(sid, namespace)¶

Put the client in the to-be-disconnected list.

This allows the client data structures to be present while the disconnect handler is invoked, but still recognize the fact that the client is soon going away.

trigger_callback(sid, id, data)¶: Invoke an application callback.

class socketio.KombuManager(url='amqp://guest:guest@localhost:5672//', channel='socketio', write_only=False, logger=None, json=None, connection_options=None, exchange_options=None, queue_options=None, producer_options=None)¶

Client manager that uses kombu for inter-process messaging.

This class implements a client manager backend for event sharing across multiple processes, using RabbitMQ, Redis or any other messaging mechanism supported by kombu.

To use a kombu backend, initialize the Server instance as follows:

url = 'amqp://user:password@hostname:port//'
server = socketio.Server(client_manager=socketio.KombuManager(url))

Parameters:

url – The connection URL for the backend messaging queue. Example connection URLs are 'amqp://guest:guest@localhost:5672//' and 'redis://localhost:6379/' for RabbitMQ and Redis respectively. Consult the kombu documentation for more on how to construct connection URLs.
channel – The channel name on which the server sends and receives notifications. Must be the same in all the servers.
write_only – If set to True, only initialize to emit events. The default of False initializes the class for emitting and receiving. A write-only instance can be used independently of the server to emit to clients from an external process.
logger – a custom logger to log it. If not given, the server logger is used.
json – An alternative JSON module to use for encoding and decoding packets. Custom json modules must have dumps and loads functions that are compatible with the standard library versions. This setting is only used when write_only is set to True. Otherwise the JSON module configured in the server is used.
connection_options – additional keyword arguments to be passed to kombu.Connection().
exchange_options – additional keyword arguments to be passed to kombu.Exchange().
queue_options – additional keyword arguments to be passed to kombu.Queue().
producer_options – additional keyword arguments to be passed to kombu.Producer().

close_room(room, namespace=None)¶: Remove all participants from a room.

connect(eio_sid, namespace)¶: Register a client connection to a namespace.

disconnect(sid, namespace=None, **kwargs)¶: Register a client disconnect from a namespace.

emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)¶

Emit a message to a single client, a room, or all the clients connected to the namespace.

This method takes care or propagating the message to all the servers that are connected through the message queue.

The parameters are the same as in Server.emit().

enter_room(sid, namespace, room, eio_sid=None)¶: Add a client to a room.

get_namespaces()¶: Return an iterable with the active namespace names.

get_participants(namespace, room)¶

Return an iterable with the active participants in a room.

get_rooms(sid, namespace)¶: Return the rooms a client is in.

initialize()¶: Invoked before the first request is received. Subclasses can add their initialization code here.

leave_room(sid, namespace, room)¶: Remove a client from a room.

pre_disconnect(sid, namespace)¶

Put the client in the to-be-disconnected list.

This allows the client data structures to be present while the disconnect handler is invoked, but still recognize the fact that the client is soon going away.

trigger_callback(sid, id, data)¶: Invoke an application callback.

class socketio.RedisManager(url='redis://localhost:6379/0', channel='socketio', write_only=False, logger=None, json=None, redis_options=None)¶

Redis based client manager.

This class implements a Redis backend for event sharing across multiple processes. Only kept here as one more example of how to build a custom backend, since the kombu backend is perfectly adequate to support a Redis message queue.

To use a Redis backend, initialize the Server instance as follows:

url = 'redis://hostname:port/0'
server = socketio.Server(client_manager=socketio.RedisManager(url))

Parameters:

url – The connection URL for the Redis server. For a default Redis store running on the same host, use redis://. To use a TLS connection, use rediss://. To use Redis Sentinel, use redis+sentinel:// with a comma-separated list of hosts and the service name after the db in the URL path. Example: redis+sentinel://user:pw@host1:1234,host2:2345/0/myredis.
channel – The channel name on which the server sends and receives notifications. Must be the same in all the servers.
write_only – If set to True, only initialize to emit events. The default of False initializes the class for emitting and receiving. A write-only instance can be used independently of the server to emit to clients from an external process.
logger – a custom logger to log it. If not given, the server logger is used.
json – An alternative JSON module to use for encoding and decoding packets. Custom json modules must have dumps and loads functions that are compatible with the standard library versions. This setting is only used when write_only is set to True. Otherwise the JSON module configured in the server is used.
redis_options – additional keyword arguments to be passed to Redis.from_url() or Sentinel().

close_room(room, namespace=None)¶: Remove all participants from a room.

connect(eio_sid, namespace)¶: Register a client connection to a namespace.

disconnect(sid, namespace=None, **kwargs)¶: Register a client disconnect from a namespace.

emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)¶

Emit a message to a single client, a room, or all the clients connected to the namespace.

This method takes care or propagating the message to all the servers that are connected through the message queue.

The parameters are the same as in Server.emit().

enter_room(sid, namespace, room, eio_sid=None)¶: Add a client to a room.

get_namespaces()¶: Return an iterable with the active namespace names.

get_participants(namespace, room)¶

Return an iterable with the active participants in a room.

get_rooms(sid, namespace)¶: Return the rooms a client is in.

initialize()¶: Invoked before the first request is received. Subclasses can add their initialization code here.

leave_room(sid, namespace, room)¶: Remove a client from a room.

pre_disconnect(sid, namespace)¶

Put the client in the to-be-disconnected list.

This allows the client data structures to be present while the disconnect handler is invoked, but still recognize the fact that the client is soon going away.

trigger_callback(sid, id, data)¶: Invoke an application callback.

class socketio.KafkaManager(url='kafka://localhost:9092', channel='socketio', write_only=False, logger=None, json=None)¶

Kafka based client manager.

This class implements a Kafka backend for event sharing across multiple processes.

To use a Kafka backend, initialize the Server instance as follows:

url = 'kafka://hostname:port'
server = socketio.Server(client_manager=socketio.KafkaManager(url))

Parameters:

url – The connection URL for the Kafka server. For a default Kafka store running on the same host, use kafka://. For a highly available deployment of Kafka, pass a list with all the connection URLs available in your cluster.
channel – The channel name (topic) on which the server sends and receives notifications. Must be the same in all the servers.
write_only – If set to True, only initialize to emit events. The default of False initializes the class for emitting and receiving. A write-only instance can be used independently of the server to emit to clients from an external process.
logger – a custom logger to log it. If not given, the server logger is used.
json – An alternative JSON module to use for encoding and decoding packets. Custom json modules must have dumps and loads functions that are compatible with the standard library versions. This setting is only used when write_only is set to True. Otherwise the JSON module configured in the server is used.

close_room(room, namespace=None)¶: Remove all participants from a room.

connect(eio_sid, namespace)¶: Register a client connection to a namespace.

disconnect(sid, namespace=None, **kwargs)¶: Register a client disconnect from a namespace.

emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)¶

Emit a message to a single client, a room, or all the clients connected to the namespace.

This method takes care or propagating the message to all the servers that are connected through the message queue.

The parameters are the same as in Server.emit().

enter_room(sid, namespace, room, eio_sid=None)¶: Add a client to a room.

get_namespaces()¶: Return an iterable with the active namespace names.

get_participants(namespace, room)¶

Return an iterable with the active participants in a room.

get_rooms(sid, namespace)¶: Return the rooms a client is in.

initialize()¶: Invoked before the first request is received. Subclasses can add their initialization code here.

leave_room(sid, namespace, room)¶: Remove a client from a room.

pre_disconnect(sid, namespace)¶

Put the client in the to-be-disconnected list.

This allows the client data structures to be present while the disconnect handler is invoked, but still recognize the fact that the client is soon going away.

trigger_callback(sid, id, data)¶: Invoke an application callback.

class socketio.ZmqManager(url='zmq+tcp://localhost:5555+5556', channel='socketio', write_only=False, logger=None, json=None)¶

zmq based client manager.

NOTE: this zmq implementation should be considered experimental at this time. At this time, eventlet is required to use zmq.

This class implements a zmq backend for event sharing across multiple processes. To use a zmq backend, initialize the Server instance as follows:

url = 'zmq+tcp://hostname:port1+port2'
server = socketio.Server(client_manager=socketio.ZmqManager(url))

Parameters:

url – The connection URL for the zmq message broker, which will need to be provided and running.
channel – The channel name on which the server sends and receives notifications. Must be the same in all the servers.
write_only – If set to True, only initialize to emit events. The default of False initializes the class for emitting and receiving. A write-only instance can be used independently of the server to emit to clients from an external process.
logger – a custom logger to log it. If not given, the server logger is used.
json – An alternative JSON module to use for encoding and decoding packets. Custom json modules must have dumps and loads functions that are compatible with the standard library versions. This setting is only used when write_only is set to True. Otherwise the JSON module configured in the server is used.

A zmq message broker must be running for the zmq_manager to work. you can write your own or adapt one from the following simple broker below:

import zmq

receiver = zmq.Context().socket(zmq.PULL)
receiver.bind("tcp://*:5555")

publisher = zmq.Context().socket(zmq.PUB)
publisher.bind("tcp://*:5556")

while True:
    publisher.send(receiver.recv())

close_room(room, namespace=None)¶: Remove all participants from a room.

connect(eio_sid, namespace)¶: Register a client connection to a namespace.

disconnect(sid, namespace=None, **kwargs)¶: Register a client disconnect from a namespace.

emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)¶

Emit a message to a single client, a room, or all the clients connected to the namespace.

This method takes care or propagating the message to all the servers that are connected through the message queue.

The parameters are the same as in Server.emit().

enter_room(sid, namespace, room, eio_sid=None)¶: Add a client to a room.

get_namespaces()¶: Return an iterable with the active namespace names.

get_participants(namespace, room)¶

Return an iterable with the active participants in a room.

get_rooms(sid, namespace)¶: Return the rooms a client is in.

initialize()¶: Invoked before the first request is received. Subclasses can add their initialization code here.

leave_room(sid, namespace, room)¶: Remove a client from a room.

pre_disconnect(sid, namespace)¶

Put the client in the to-be-disconnected list.

This allows the client data structures to be present while the disconnect handler is invoked, but still recognize the fact that the client is soon going away.

trigger_callback(sid, id, data)¶: Invoke an application callback.

class socketio.AsyncManager¶

Manage a client list for an asyncio server.

async close_room(room, namespace)¶

Remove all participants from a room.

Note: this method is a coroutine.

async connect(eio_sid, namespace)¶

Note: this method is a coroutine.

async disconnect(sid, namespace, **kwargs)¶

Disconnect a client.

Note: this method is a coroutine.

async emit(event, data, namespace, room=None, skip_sid=None, callback=None, to=None, **kwargs)¶

Emit a message to a single client, a room, or all the clients connected to the namespace.

Note: this method is a coroutine.

async enter_room(sid, namespace, room, eio_sid=None)¶

Add a client to a room.

Note: this method is a coroutine.

get_namespaces()¶: Return an iterable with the active namespace names.

get_participants(namespace, room)¶

Return an iterable with the active participants in a room.

get_rooms(sid, namespace)¶: Return the rooms a client is in.

initialize()¶: Invoked before the first request is received. Subclasses can add their initialization code here.

async leave_room(sid, namespace, room)¶

Remove a client from a room.

Note: this method is a coroutine.

pre_disconnect(sid, namespace)¶

Put the client in the to-be-disconnected list.

This allows the client data structures to be present while the disconnect handler is invoked, but still recognize the fact that the client is soon going away.

async trigger_callback(sid, id, data)¶

Invoke an application callback.

Note: this method is a coroutine.

class socketio.AsyncRedisManager(url='redis://localhost:6379/0', channel='socketio', write_only=False, logger=None, json=None, redis_options=None)¶

Redis based client manager for asyncio servers.

This class implements a Redis backend for event sharing across multiple processes.

To use a Redis backend, initialize the AsyncServer instance as follows:

url = 'redis://hostname:port/0'
server = socketio.AsyncServer(
    client_manager=socketio.AsyncRedisManager(url))

Parameters:

url – The connection URL for the Redis server. For a default Redis store running on the same host, use redis://. To use a TLS connection, use rediss://. To use Redis Sentinel, use redis+sentinel:// with a comma-separated list of hosts and the service name after the db in the URL path. Example: redis+sentinel://user:pw@host1:1234,host2:2345/0/myredis.
channel – The channel name on which the server sends and receives notifications. Must be the same in all the servers.
write_only – If set to True, only initialize to emit events. The default of False initializes the class for emitting and receiving. A write-only instance can be used independently of the server to emit to clients from an external process.
logger – a custom logger to log it. If not given, the server logger is used.
json – An alternative JSON module to use for encoding and decoding packets. Custom json modules must have dumps and loads functions that are compatible with the standard library versions. This setting is only used when write_only is set to True. Otherwise the JSON module configured in the server is used.
redis_options – additional keyword arguments to be passed to Redis.from_url() or Sentinel().

async close_room(room, namespace=None)¶

Remove all participants from a room.

Note: this method is a coroutine.

async connect(eio_sid, namespace)¶

Note: this method is a coroutine.

async disconnect(sid, namespace, **kwargs)¶

Disconnect a client.

Note: this method is a coroutine.

async emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)¶

Emit a message to a single client, a room, or all the clients connected to the namespace.

This method takes care or propagating the message to all the servers that are connected through the message queue.

The parameters are the same as in Server.emit().

Note: this method is a coroutine.

async enter_room(sid, namespace, room, eio_sid=None)¶

Add a client to a room.

Note: this method is a coroutine.

get_namespaces()¶: Return an iterable with the active namespace names.

get_participants(namespace, room)¶

Return an iterable with the active participants in a room.

get_rooms(sid, namespace)¶: Return the rooms a client is in.

initialize()¶: Invoked before the first request is received. Subclasses can add their initialization code here.

async leave_room(sid, namespace, room)¶

Remove a client from a room.

Note: this method is a coroutine.

pre_disconnect(sid, namespace)¶

Put the client in the to-be-disconnected list.

This allows the client data structures to be present while the disconnect handler is invoked, but still recognize the fact that the client is soon going away.

async trigger_callback(sid, id, data)¶

Invoke an application callback.

Note: this method is a coroutine.

class socketio.AsyncAioPikaManager(url='amqp://guest:guest@localhost:5672//', channel='socketio', write_only=False, logger=None, json=None)¶

Client manager that uses aio_pika for inter-process messaging under asyncio.

This class implements a client manager backend for event sharing across multiple processes, using RabbitMQ

To use a aio_pika backend, initialize the Server instance as follows:

url = 'amqp://user:password@hostname:port//'
server = socketio.Server(client_manager=socketio.AsyncAioPikaManager(
    url))

Parameters:

url – The connection URL for the backend messaging queue. Example connection URLs are 'amqp://guest:guest@localhost:5672//' for RabbitMQ.
channel – The channel name on which the server sends and receives notifications. Must be the same in all the servers. With this manager, the channel name is the exchange name in rabbitmq
write_only – If set to True, only initialize to emit events. The default of False initializes the class for emitting and receiving. A write-only instance can be used independently of the server to emit to clients from an external process.
logger – a custom logger to log it. If not given, the server logger is used.
json – An alternative JSON module to use for encoding and decoding packets. Custom json modules must have dumps and loads functions that are compatible with the standard library versions. This setting is only used when write_only is set to True. Otherwise the JSON module configured in the server is used.

async close_room(room, namespace=None)¶

Remove all participants from a room.

Note: this method is a coroutine.

async connect(eio_sid, namespace)¶

Note: this method is a coroutine.

async disconnect(sid, namespace, **kwargs)¶

Disconnect a client.

Note: this method is a coroutine.

async emit(event, data, namespace=None, room=None, skip_sid=None, callback=None, to=None, **kwargs)¶

Emit a message to a single client, a room, or all the clients connected to the namespace.

This method takes care or propagating the message to all the servers that are connected through the message queue.

The parameters are the same as in Server.emit().

Note: this method is a coroutine.

async enter_room(sid, namespace, room, eio_sid=None)¶

Add a client to a room.

Note: this method is a coroutine.

get_namespaces()¶: Return an iterable with the active namespace names.

get_participants(namespace, room)¶

Return an iterable with the active participants in a room.

get_rooms(sid, namespace)¶: Return the rooms a client is in.

initialize()¶: Invoked before the first request is received. Subclasses can add their initialization code here.

async leave_room(sid, namespace, room)¶

Remove a client from a room.

Note: this method is a coroutine.

pre_disconnect(sid, namespace)¶

Put the client in the to-be-disconnected list.

This allows the client data structures to be present while the disconnect handler is invoked, but still recognize the fact that the client is soon going away.

async trigger_callback(sid, id, data)¶

Invoke an application callback.

Note: this method is a coroutine.