The Engine.IO Client

This package contains two Engine.IO clients:

The methods in the two clients are the same, with the only difference that in the asyncio client most methods are implemented as coroutines.

Installation

To install the standard Python client along with its dependencies, use the following command:

pip install "python-engineio[client]"

If instead you plan on using the asyncio client, then use this:

pip install "python-engineio[asyncio_client]"

Creating a Client Instance

To instantiate an Engine.IO client, simply create an instance of the appropriate client class:

import engineio

# standard Python
eio = engineio.Client()

# asyncio
eio = engineio.AsyncClient()

Defining Event Handlers

To responds to events triggered by the connection or the server, event Handler functions must be defined using the on decorator:

@eio.on('connect')
def on_connect():
    print('I'm connected!')

@eio.on('message')
def on_message(data):
    print('I received a message!')

@eio.on('disconnect')
def on_disconnect():
    print('I'm disconnected!')

For the asyncio server, event handlers can be regular functions as above, or can also be coroutines:

@eio.on('message')
async def on_message(data):
    print('I received a message!')

The argument given to the on decorator is the event name. The events that are supported are connect, message and disconnect. Note that the disconnect handler is invoked for application initiated disconnects, server initiated disconnects, or accidental disconnects, for example due to networking failures.

The data argument passed to the 'message' event handler contains application-specific data provided by the server with the event.

Connecting to a Server

The connection to a server is established by calling the connect() method:

eio.connect('http://localhost:5000')

In the case of the asyncio client, the method is a coroutine:

await eio.connect('http://localhost:5000')

Upon connection, the server assigns the client a unique session identifier. The applicaction can find this identifier in the sid attribute:

print('my sid is', eio.sid)

Sending Messages

The client can send a message to the server using the send() method:

eio.send({'foo': 'bar'})

Or in the case of asyncio, as a coroutine:

await eio.send({'foo': 'bar'})

The single argument provided to the method is the data that is passed on to the server. The data can be of type str, bytes, dict or list. The data included inside dictionaries and lists is also constrained to these types.

The send() method can be invoked inside an event handler as a response to a server event, or in any other part of the application, including in background tasks.

Disconnecting from the Server

At any time the client can request to be disconnected from the server by invoking the disconnect() method:

eio.disconnect()

For the asyncio client this is a coroutine:

await eio.disconnect()

Managing Background Tasks

When a client connection to the server is established, a few background tasks will be spawned to keep the connection alive and handle incoming events. The application running on the main thread is free to do any work, as this is not going to prevent the functioning of the Engine.IO client.

If the application does not have anything to do in the main thread and just wants to wait until the connection ends, it can call the wait() method:

eio.wait()

Or in the asyncio version:

await eio.wait()

For the convenience of the application, a helper function is provided to start a custom background task:

def my_background_task(my_argument)
    # do some background work here!
    pass

eio.start_background_task(my_background_task, 123)

The arguments passed to this method are the background function and any positional or keyword arguments to invoke the function with.

Here is the asyncio version:

async def my_background_task(my_argument)
    # do some background work here!
    pass

eio.start_background_task(my_background_task, 123)

Note that this function is not a coroutine, since it does not wait for the background function to end, but the background function is.

The sleep() method is a second convenience function that is provided for the benefit of applications working with background tasks of their own:

eio.sleep(2)

Or for asyncio:

await eio.sleep(2)

The single argument passed to the method is the number of seconds to sleep for.

Debugging and Troubleshooting

To help you debug issues, the client can be configured to output logs to the terminal:

import engineio

# standard Python
eio = engineio.Client(logger=True)

# asyncio
eio = engineio.AsyncClient(logger=True)

The logger argument can be set to True to output logs to stderr, or to an object compatible with Python’s logging package where the logs should be emitted to. A value of False disables logging.

Logging can help identify the cause of connection problems, unexpected disconnections and other issues.