class engineio.Client(logger=False, json=None, request_timeout=5, http_session=None, ssl_verify=True, handle_sigint=True, websocket_extra_options=None, timestamp_requests=True)

An Engine.IO client.

This class implements a fully compliant Engine.IO web client with support for websocket and long-polling transports.

Parameters:

  • logger – To enable 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 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 compatible with the standard library versions. This is a process-wide setting, all instantiated servers and clients must use the same JSON module.

  • request_timeout – A timeout in seconds for requests. The default is 5 seconds.

  • http_session – an initialized requests.Session object to be used when sending requests to the server. Use it if you need to add special client options such as proxy servers, SSL certificates, custom CA bundle, etc.

  • ssl_verify – True to verify SSL certificates, or False to skip SSL certificate verification, allowing connections to servers with self signed certificates. The default is True.

  • handle_sigint – Set to True to automatically handle disconnection when the process is interrupted, or to False to leave interrupt handling to the calling application. Interrupt handling can only be enabled when the client instance is created in the main thread.

  • websocket_extra_options – Dictionary containing additional keyword arguments passed to websocket.create_connection().

  • timestamp_requests – If True a timestamp is added to the query string of Socket.IO requests as a cache-busting measure. Set to False to disable.

connect(url, headers=None, transports=None, engineio_path='engine.io')

Connect to an Engine.IO server.

Parameters:

  • url – The URL of the Engine.IO server. It can include custom query string parameters if required by the server.

  • headers – A dictionary with custom headers to send with the connection request.

  • transports – The list of allowed transports. Valid transports are 'polling' and 'websocket'. If not given, the polling transport is connected first, then an upgrade to websocket is attempted.

  • engineio_path – The endpoint where the Engine.IO server is installed. The default value is appropriate for most cases.

Example usage:

eio = engineio.Client()
eio.connect('http://localhost:5000')
wait()

Wait until the connection with the server ends.

Client applications can use this function to block the main thread during the life of the connection.

send(data)

Send a message to the server.

Parameters:

data – The data to send to the server. Data can be of type str, bytes, list or dict. If a list or dict, the data will be serialized as JSON.

disconnect(abort=False, reason=None)

Disconnect from the server.

Parameters:

abort – If set to True, do not wait for background tasks associated with the connection to end.

start_background_task(target, *args, **kwargs)

Start a background task.

This is a utility function that applications can use to start a background task.

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.

create_queue(*args, **kwargs)

Create a queue object.

get_queue_empty_exception()

Return the queue empty exception raised by queues created by the create_queue() method.

create_event(*args, **kwargs)

Create an event object.

on(event, handler=None)

Register an event handler.

Parameters:

  • event – The event name. Can be 'connect', 'message' or 'disconnect'.

  • handler – The function that should be invoked to handle the event. When this parameter is not given, the method acts as a decorator for the handler function.

Example usage:

# as a decorator:
@eio.on('connect')
def connect_handler():
    print('Connection request')

# as a method:
def message_handler(msg):
    print('Received message: ', msg)
    eio.send('response')
eio.on('message', message_handler)
class reason

Disconnection reasons.

CLIENT_DISCONNECT = 'client disconnect'

Client-initiated disconnection.

SERVER_DISCONNECT = 'server disconnect'

Server-initiated disconnection.

TRANSPORT_ERROR = 'transport error'

Transport error.

transport()

Return the name of the transport currently in use.

The possible values returned by this function are 'polling' and 'websocket'.