Getting Started

What is Engine.IO?

Engine.IO is a lightweight transport protocol that enables real-time bidirectional event-based communication between clients (typically, though not always, web browsers) and a server. The official implementations of the client and server components are written in JavaScript. This package provides Python implementations of both, each with standard and asyncio variants.

The Engine.IO protocol is extremely simple. Once a connection between a client and a server is established, either side can send “messages” to the other side. Event handlers provided by the applications on both ends are invoked when a message is received, or when a connection is established or dropped.

Client Examples

The example that follows shows a simple Python client:

import engineio

eio = engineio.Client()

@eio.on('connect')
def on_connect():
    print('connection established')

@eio.on('message')
def on_message(data):
    print('message received with ', data)
    eio.send({'response': 'my response'})

@eio.on('disconnect')
def on_disconnect():
    print('disconnected from server')

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

And here is a similar client written using the official Engine.IO Javascript client:

<script src="/path/to/engine.io.js"></script>
<script>
    var socket = eio('http://localhost:5000');
    socket.on('open', function() { console.log('connection established'); });
    socket.on('message', function(data) {
        console.log('message received with ' + data);
        socket.send({response: 'my response'});
    });
    socket.on('close', function() { console.log('disconnected from server'); });
</script>

Client Features

• Can connect to other Engine.IO complaint servers besides the one in this package.

• Compatible with Python 3.6+.

• Two versions of the client, one for standard Python and another for asyncio.

• Uses an event-based architecture implemented with decorators that hides the details of the protocol.

• Implements HTTP long-polling and WebSocket transports.

Server Examples

The following application is a basic example that uses the Eventlet asynchronous server:

import engineio
import eventlet

eio = engineio.Server()
app = engineio.WSGIApp(eio, static_files={
    '/': {'content_type': 'text/html', 'filename': 'index.html'}
})

@eio.on('connect')
def connect(sid, environ):
    print("connect ", sid)

@eio.on('message')
def message(sid, data):
    print("message ", data)
    eio.send(sid, 'reply')

@eio.on('disconnect')
def disconnect(sid):
    print('disconnect ', sid)

if __name__ == '__main__':
    eventlet.wsgi.server(eventlet.listen(('', 5000)), app)

Below is a similar application, coded for asyncio and the Uvicorn web server:

import engineio
import uvicorn

eio = engineio.AsyncServer()
app = engineio.ASGIApp(eio, static_files={
    '/': {'content_type': 'text/html', 'filename': 'index.html'}
})

@eio.on('connect')
def connect(sid, environ):
    print("connect ", sid)

@eio.on('message')
async def message(sid, data):
    print("message ", data)
    await eio.send(sid, 'reply')

@eio.on('disconnect')
def disconnect(sid):
    print('disconnect ', sid)

if __name__ == '__main__':
    uvicorn.run('127.0.0.1', 5000)

Server Features

• Can accept clients running other complaint Engine.IO clients besides the one in this package.

• Compatible with Python 3.6+.

• Two versions of the server, one for standard Python and another for asyncio.

• Supports large number of clients even on modest hardware due to being asynchronous.

• Can be hosted on any WSGI and ASGI web servers includind Gunicorn, Uvicorn, eventlet and gevent.

• Can be integrated with WSGI applications written in frameworks such as Flask, Django, etc.

• Can be integrated with aiohttp, sanic and tornado asyncio applications.

• Uses an event-based architecture implemented with decorators that hides the details of the protocol.

• Implements HTTP long-polling and WebSocket transports.

• Supports XHR2 and XHR browsers as clients.

• Supports text and binary messages.

• Supports gzip and deflate HTTP compression.

• Configurable CORS responses to avoid cross-origin problems with browsers.