API Reference

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

Create a Flask-SocketIO server.

Parameters: app – The flask application instance. If the application instance isn’t known
at the time this class is instantiated, then call socketio.init_app(app) once
the application instance is available.
manage_session – If set to True, this extension manages the user session for
Socket.IO events. If set to False, Flask’s own session management is used.
When using Flask’s cookie based sessions it is recommended that you leave
this set to the default of True. When using server-side sessions, a False set-
ting enables sharing the user session between HTTP routes and Socket.IO
events.
message_queue – A connection URL for a message queue service the server
can use for multi-process communication. A message queue is not required
when using a single server process.
channel – The channel name, when using a message queue. If a channel isn’t
specified, a default channel will be used. If multiple clusters of SocketIO pro-
cesses need to use the same message queue without interfering with each
other, then each cluster should use a different channel.
path – The path where the Socket.IO server is exposed. Defaults to
'socket.io'. Leave this as is unless you know what you are doing.
resource – Alias to path.
kwargs – Socket.IO and Engine.IO server options.

The Socket.IO server options are detailed below:

Parameters: client_manager – The client manager instance that will manage the client
list. When this is omitted, the client list is stored in an in-memory structure,
so the use of multiple connected servers is not possible. In most cases, this ar-
gument does not need to be set explicitly.
logger – To enable logging set to True or pass a logger object to use. To dis-
able logging set to False. The default is False. Note that fatal errors will be
logged even when logger is False.
json – An alternative json module to use for encoding and decoding packets.
Custom json modules must have dumps and loads functions that are compati-
ble with the standard library versions. To use the same json encoder and de-
coder as a Flask application, use flask.json.
async_handlers – If set to True, event handlers for a client are executed in
separate threads. To run handlers for a client synchronously, set to False.
The default is True.
always_connect – When set to False, new connections are provisory until
the connect handler returns something other than False, at which point they
are accepted. When set to True, connections are immediately accepted, and
then if the connect handler returns False a disconnect is issued. Set to True if
you need to emit events from the connect handler and your client is con-
fused when it receives events before the connection acceptance. In any other
case use the default of False.

The Engine.IO server configuration supports the following settings:

Parameters: async_mode – The asynchronous model to use. See the Deployment section
in the documentation for a description of the available options. Valid async
modes are threading, eventlet, gevent and gevent_uwsgi. If this argument is
not given, eventlet is tried first, then gevent_uwsgi, then gevent, and finally
 threading. The first async mode that has all its dependencies installed is then
one that is chosen.
ping_interval – The interval in seconds at which the server pings the client.
The default is 25 seconds. For advanced control, a two element tuple can be
given, where the first number is the ping interval and the second is a grace
period added by the server.
ping_timeout – The time in seconds that the client waits for the server to re-
spond before disconnecting. The default is 5 seconds.
max_http_buffer_size – The maximum size of a message when using the
polling transport. The default is 1,000,000 bytes.
allow_upgrades – Whether to allow transport upgrades or not. The default is
True.
http_compression – Whether to compress packages when using the polling
transport. The default is True.
compression_threshold – Only compress messages when their byte size is
greater than this value. The default is 1024 bytes.
cookie – If set to a string, it is the name of the HTTP cookie the server sends
back to the client containing the client session id. If set to a dictionary, the
'name' key contains the cookie name and other keys define cookie attributes,
where the value of each attribute can be a string, a callable with no argu-
ments, or a boolean. If set to None (the default), a cookie is not sent to the
client.
cors_allowed_origins – Origin or list of origins that are allowed to connect
to this server. Only the same origin is allowed by default. Set this argument
to '*' to allow all origins, or to [] to disable CORS handling.
cors_credentials – Whether credentials (cookies, authentication) are al-
lowed in requests to this server. The default is True.
monitor_clients – If set to True, a background task will ensure inactive
clients are closed. Set to False to disable the monitoring task (not recom-
mended). The default is True.
engineio_logger – To enable Engine.IO logging set to True or pass a logger
object to use. To disable logging set to False. The default is False. Note that
fatal errors are logged even when engineio_logger is False.

class reason
Disconnection reasons.

CLIENT_DISCONNECT = 'client disconnect'

Client-initiated disconnection.

PING_TIMEOUT = 'ping timeout'

Ping timeout.

SERVER_DISCONNECT = 'server disconnect'

Server-initiated disconnection.

TRANSPORT_CLOSE = 'transport close'

Transport close.

TRANSPORT_ERROR = 'transport error'

Transport error.

on(message, namespace=None)
Decorator to register a SocketIO event handler.

This decorator must be applied to SocketIO event handlers. Example:

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

Parameters: message – The name of the event. This is normally a user defined string,
but a few event names are already defined. Use 'message' to define a
handler that takes a string payload, 'json' to define a handler that takes
a JSON blob payload, 'connect' or 'disconnect' to create handlers for
connection and disconnection events.
namespace – The namespace on which the handler is to be registered.
Defaults to the global namespace.

on_error(namespace=None)
Decorator to define a custom error handler for SocketIO events.

This decorator can be applied to a function that acts as an error handler for a namespace.
This handler will be invoked when a SocketIO event handler raises an exception. The han-
dler function must accept one argument, which is the exception raised. Example:

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

Parameters: namespace – The namespace for which to register the error handler.
Defaults to the global namespace.

on_error_default(exception_handler)
Decorator to define a default error handler for SocketIO events.

This decorator can be applied to a function that acts as a default error handler for any
namespaces that do not have a specific handler. Example:

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

on_event(message, handler, namespace=None)

Register a SocketIO event handler.

on_event is the non-decorator version of 'on'.

Example:

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

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

Parameters: message – The name of the event. This is normally a user defined string,
but a few event names are already defined. Use 'message' to define a
handler that takes a string payload, 'json' to define a handler that takes
a JSON blob payload, 'connect' or 'disconnect' to create handlers for
connection and disconnection events.
handler – The function that handles the event.
namespace – The namespace on which the handler is to be registered.
Defaults to the global namespace.

event(*args, **kwargs)
Decorator to register an event handler.
 This is a simplified version of the on() method that takes the event name from the deco-
rated function.

Example usage:

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

The above example is equivalent to:

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

A custom namespace can be given as an argument to the decorator:

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

emit(event, *args, **kwargs)

Emit a server generated SocketIO event.

This function emits a SocketIO event to one or more connected clients. A JSON blob can be
attached to the event as payload. This function can be used outside of a SocketIO event con-
text, so it is appropriate to use when the server is the originator of an event, outside of any
client context, such as in a regular HTTP request handler or a background task. Example:

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

Parameters: event – The name of the user event to emit.

args – A dictionary with the JSON data to send as payload.
namespace – The namespace under which the message is to be sent.
Defaults to the global namespace.
to – Send the message to all the users in the given room, or to the user
with the given session ID. If this parameter is not included, the event is
sent to all connected users.
include_self – True to include the sender when broadcasting or address-
ing a room, or False to send to everyone but the sender.
skip_sid – The session id of a client to ignore when broadcasting or ad-
dressing a room. This is typically set to the originator of the message, so
that everyone except that client receive the message. To skip multiple
sids pass a list.
callback – If given, this function will be called to acknowledge that the
client has received the message. The arguments that will be passed to the
function are those provided by the client. Callback functions can only be
used when addressing an individual client.

call(event, *args, **kwargs)

Emit a SocketIO event and wait for the response.

This method issues an emit with a callback and waits for the callback to be invoked by the
client before returning. If the callback isn’t invoked before the timeout, then a
TimeoutError exception is raised. If the Socket.IO connection drops during the wait, this
method still waits until the specified timeout. Example:
 def get_status(client, data):
status = call('status', {'data': data}, to=client)

Parameters: event – The name of the user event to emit.

args – A dictionary with the JSON data to send as payload.
namespace – The namespace under which the message is to be sent.
Defaults to the global namespace.
to – The session ID of the recipient client.
timeout – The waiting timeout. If the timeout is reached before the client
acknowledges the event, then a TimeoutError exception is raised. The de-
fault is 60 seconds.
ignore_queue – Only used when a message queue is configured. If set to
True, the event is emitted to the client directly, without going through the
queue. This is more efficient, but only works when a single server
process is used, or when there is a single addressee. It is recommended to
always leave this parameter with its default value of False.

send(data, json=False, namespace=None, to=None, callback=None,

include_self=True, skip_sid=None, **kwargs)
Send a server-generated SocketIO message.

This function sends a simple SocketIO message to one or more connected clients. The mes-
sage can be a string or a JSON blob. This is a simpler version of emit(), which should be
preferred. This function can be used outside of a SocketIO event context, so it is appropri-
ate to use when the server is the originator of an event.

Parameters: data – The message to send, either a string or a JSON blob.

json – True if message is a JSON blob, False otherwise.
namespace – The namespace under which the message is to be sent.
Defaults to the global namespace.
to – Send the message to all the users in the given room, or to the user
with the given session ID. If this parameter is not included, the event is
sent to all connected users.
include_self – True to include the sender when broadcasting or address-
ing a room, or False to send to everyone but the sender.
skip_sid – The session id of a client to ignore when broadcasting or ad-
dressing a room. This is typically set to the originator of the message, so
that everyone except that client receive the message. To skip multiple
sids pass a list.
callback – If given, this function will be called to acknowledge that the
client has received the message. The arguments that will be passed to the
function are those provided by the client. Callback functions can only be
used when addressing an individual client.

close_room(room, namespace=None)
Close a room.

This function removes any users that are in the given room and then deletes the room from
the server. This function can be used outside of a SocketIO event context.

Parameters: room – The name of the room to close.

namespace – The namespace under which the room exists. Defaults to
the global namespace.

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

Run the SocketIO web server.
 Parameters: app – The Flask application instance.
host – The hostname or IP address for the server to listen on. Defaults to
127.0.0.1.
port – The port number for the server to listen on. Defaults to 5000.
debug – True to start the server in debug mode, False to start in normal
mode.
use_reloader – True to enable the Flask reloader, False to disable it.
reloader_options – A dictionary with options that are passed to the Flask
reloader, such as extra_files, reloader_type, etc.
extra_files – A list of additional files that the Flask reloader should
watch. Defaults to None. Deprecated, use reloader_options instead.
log_output – If True, the server logs all incoming connections. If False
logging is disabled. Defaults to True in debug mode, False in normal
mode. Unused when the threading async mode is used.
allow_unsafe_werkzeug – Set to True to allow the use of the Werkzeug
web server in a production setting. Default is False. Set to True at your
own risk.
kwargs – Additional web server options. The web server options are spe-
cific to the server used in each of the supported async modes. Note that
options provided here will not be seen when using an external web
server such as gunicorn, since this method is not called in that case.

stop()
Stop a running SocketIO web server.

This method must be called from a HTTP or SocketIO handler function.

start_background_task(target, *args, **kwargs)

Start a background task using the appropriate async model.

This is a utility function that applications can use to start a background task using the
method that is compatible with the selected async mode.

Parameters: target – the target function to execute.

args – arguments to pass to the function.
kwargs – keyword arguments to pass to the function.

This function returns an object that represents the background task, on which the join()
method can be invoked to wait for the task to complete.

sleep(seconds=0)
Sleep for the requested amount of time using the appropriate async model.

This is a utility function that applications can use to put a task to sleep without having to
worry about using the correct call for the selected async mode.

test_client(app, namespace=None, query_string=None, headers=None,

auth=None, flask_test_client=None)
The Socket.IO test client is useful for testing a Flask-SocketIO server. It works in a similar
way to the Flask Test Client, but adapted to the Socket.IO server.

Parameters: app – The Flask application instance.

namespace – The namespace for the client. If not provided, the client
connects to the server on the global namespace.
query_string – A string with custom query string arguments.
headers – A dictionary with custom HTTP headers.
auth – Optional authentication data, given as a dictionary.
 flask_test_client – The instance of the Flask test client currently in use.
Passing the Flask test client is optional, but is necessary if you want the
Flask user session and any other cookies set in HTTP routes accessible
from Socket.IO events.

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

Emit a SocketIO event.

This function emits a SocketIO event to one or more connected clients. A JSON blob can be at-
tached to the event as payload. This is a function that can only be called from a SocketIO event
handler, as in obtains some information from the current client context. Example:

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

Parameters: event – The name of the user event to emit.

args – A dictionary with the JSON data to send as payload.
namespace – The namespace under which the message is to be sent. Defaults
to the namespace used by the originating event. A '/' can be used to explic-
itly specify the global namespace.
callback – Callback function to invoke with the client’s acknowledgement.
broadcast – True to send the message to all clients, or False to only reply to
the sender of the originating event.
to – Send the message to all the users in the given room, or to the user with
the given session ID. If this argument is not set and broadcast is False, then
the message is sent only to the originating user.
include_self – True to include the sender when broadcasting or addressing a
room, or False to send to everyone but the sender.
skip_sid – The session id of a client to ignore when broadcasting or address-
ing a room. This is typically set to the originator of the message, so that ev-
eryone except that client receive the message. To skip multiple sids pass a
list.
ignore_queue – Only used when a message queue is configured. If set to
True, the event is emitted to the clients directly, without going through the
queue. This is more efficient, but only works when a single server process is
used, or when there is a single addressee. It is recommended to always leave
this parameter with its default value of False.

flask_socketio.send(message, **kwargs)
Send a SocketIO message.

This function sends a simple SocketIO message to one or more connected clients. The message
can be a string or a JSON blob. This is a simpler version of emit(), which should be preferred.
This is a function that can only be called from a SocketIO event handler.

Parameters: message – The message to send, either a string or a JSON blob.

json – True if message is a JSON blob, False otherwise.
namespace – The namespace under which the message is to be sent. Defaults
to the namespace used by the originating event. An empty string can be used
to use the global namespace.
callback – Callback function to invoke with the client’s acknowledgement.
broadcast – True to send the message to all connected clients, or False to
only reply to the sender of the originating event.
to – Send the message to all the users in the given room, or to the user with
the given session ID. If this argument is not set and broadcast is False, then
the message is sent only to the originating user.
 include_self – True to include the sender when broadcasting or addressing a
room, or False to send to everyone but the sender.
skip_sid – The session id of a client to ignore when broadcasting or address-
ing a room. This is typically set to the originator of the message, so that ev-
eryone except that client receive the message. To skip multiple sids pass a
list.
ignore_queue – Only used when a message queue is configured. If set to
True, the event is emitted to the clients directly, without going through the
queue. This is more efficient, but only works when a single server process is
used, or when there is a single addressee. It is recommended to always leave
this parameter with its default value of False.

flask_socketio.join_room(room, sid=None, namespace=None)

Join a room.

This function puts the user in a room, under the current namespace. The user and the name-
space are obtained from the event context. This is a function that can only be called from a
SocketIO event handler. Example:

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

Parameters: room – The name of the room to join.

sid – The session id of the client. If not provided, the client is obtained from
the request context.
namespace – The namespace for the room. If not provided, the namespace is
obtained from the request context.

flask_socketio.leave_room(room, sid=None, namespace=None)

Leave a room.

This function removes the user from a room, under the current namespace. The user and the
namespace are obtained from the event context. Example:

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

Parameters: room – The name of the room to leave.

sid – The session id of the client. If not provided, the client is obtained from
the request context.
namespace – The namespace for the room. If not provided, the namespace is
obtained from the request context.

flask_socketio.close_room(room, namespace=None)
Close a room.

This function removes any users that are in the given room and then deletes the room from
the server.

Parameters: room – The name of the room to close.

 namespace – The namespace for the room. If not provided, the namespace is
obtained from the request context.

flask_socketio.rooms(sid=None, namespace=None)
Return a list of the rooms the client is in.

This function returns all the rooms the client has entered, including its own room, assigned by
the Socket.IO server.

Parameters: sid – The session id of the client. If not provided, the client is obtained from
the request context.
namespace – The namespace for the room. If not provided, the namespace is
obtained from the request context.

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

Disconnect the client.

This function terminates the connection with the client. As a result of this call the client will re-
ceive a disconnect event. Example:

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

Parameters: sid – The session id of the client. If not provided, the client is obtained from
the request context.
namespace – The namespace for the room. If not provided, the namespace is
obtained from the request context.
silent – this option is deprecated.

class flask_socketio.Namespace(namespace=None)
trigger_event(event, *args)
Dispatch an event to the proper handler method.

In the most common usage, this method is not overloaded by subclasses, as it performs the
routing of events to methods. However, this method can be overridden if special dispatch-
ing rules are needed, or if having a single method that catches all events is desired.

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

callback=None)
Emit a custom event to one or more connected clients.

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

Send a message to one or more connected clients.

close_room(room, namespace=None)
Close a room.

class flask_socketio.SocketIOTestClient(app, socketio, namespace=None,

query_string=None, headers=None, auth=None, flask_test_client=None)
This class is useful for testing a Flask-SocketIO server. It works in a similar way to the Flask
Test Client, but adapted to the Socket.IO server.

Parameters: app – The Flask application instance.

socketio – The application’s SocketIO instance.
 namespace – The namespace for the client. If not provided, the client con-
nects to the server on the global namespace.
query_string – A string with custom query string arguments.
headers – A dictionary with custom HTTP headers.
auth – Optional authentication data, given as a dictionary.
flask_test_client – The instance of the Flask test client currently in use.
Passing the Flask test client is optional, but is necessary if you want the Flask
user session and any other cookies set in HTTP routes accessible from
Socket.IO events.

is_connected(namespace=None)
Check if a namespace is connected.

Parameters: namespace – The namespace to check. The global namespace is assumed if

this argument is not provided.

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

Connect the client.

Parameters: namespace – The namespace for the client. If not provided, the client
connects to the server on the global namespace.
query_string – A string with custom query string arguments.
headers – A dictionary with custom HTTP headers.
auth – Optional authentication data, given as a dictionary.

Note that it is usually not necessary to explicitly call this method, since a connection is au-
tomatically established when an instance of this class is created. An example where it this
method would be useful is when the application accepts multiple namespace connections.

disconnect(namespace=None)
Disconnect the client.

Parameters: namespace – The namespace to disconnect. The global namespace is as-

sumed if this argument is not provided.

emit(event, *args, **kwargs)

Emit an event to the server.

Parameters: event – The event name.

*args –
The event arguments.
callback – True if the client requests a callback, False if not. Note that
client-side callbacks are not implemented, a callback request will just tell
the server to provide the arguments to invoke the callback, but no call-
back is invoked. Instead, the arguments that the server provided for the
callback are returned by this function.
namespace – The namespace of the event. The global namespace is as-
sumed if this argument is not provided.

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

Send a text or JSON message to the server.

Parameters: data – A string, dictionary or list to send to the server.

json – True to send a JSON message, False to send a text message.
callback – True if the client requests a callback, False if not. Note that
client-side callbacks are not implemented, a callback request will just tell
the server to provide the arguments to invoke the callback, but no call-
 back is invoked. Instead, the arguments that the server provided for the
callback are returned by this function.
namespace – The namespace of the event. The global namespace is as-
sumed if this argument is not provided.

get_received(namespace=None)
Return the list of messages received from the server.

Since this is not a real client, any time the server emits an event, the event is simply stored.
The test code can invoke this method to obtain the list of events that were received since
the last call.

Parameters: namespace – The namespace to get events from. The global namespace is
assumed if this argument is not provided.