Python Engine.IO

Warnings

• breaking Engine.IO v4 introduced major breaking changes, including a reversal of the heartbeat (ping/pong) mechanism (server now pings, client responds), a new packet encoding format, and a reduced default `maxHttpBufferSize` (from 100MB to 1MB). Clients running on Engine.IO v3 will NOT be compatible with servers running on v4, and vice-versa.
  Fix: Ensure all clients and servers are upgraded to be compatible with the same Engine.IO protocol version. Review `maxHttpBufferSize` if large payloads are expected.
• gotcha The Engine.IO server library is a protocol implementation and requires an underlying asynchronous framework or WSGI/ASGI web server (e.g., `eventlet`, `gevent`, `aiohttp`, `uvicorn`, `tornado`) to function as a complete web application. It does not provide its own standalone web server.
  Fix: Always integrate the `engineio.Server` or `engineio.AsyncServer` instance with a compatible WSGIApp/ASGIApp and run it using an appropriate web server (e.g., `uvicorn`, `gunicorn` with `eventlet`/`gevent` workers). Refer to documentation for framework-specific integration examples.
• gotcha When defining event handlers (e.g., with `@eio.on('message')`), avoid using mutable objects (like lists or dictionaries) as default arguments in the handler function signature. These defaults are created once when the function is defined and shared across all calls/sessions, leading to unexpected behavior.
  Fix: Initialize mutable default arguments inside the function body if no argument is provided, typically using `None` as the default in the signature: `def my_handler(sid, data, my_list=None): my_list = my_list or []`.
• gotcha The library internally supports a single custom JSON module per process. Attempting to configure multiple custom JSON encoder/decoder modules might lead to unexpected behavior or errors, as documented in recent changes.
  Fix: If custom JSON serialization is needed, configure it globally for your Engine.IO `Server` or `Client` instance once. Avoid overriding it in multiple places or with different modules within the same process.
• deprecated Older Python versions (e.g., 3.7, 3.8, 3.9) are being dropped from continuous integration (CI) builds, indicating that while they might still work, active testing and support focus on newer Python versions (3.10+). The `requires_python` specifier is `>=3.8`.
  Fix: It is recommended to use `python-engineio` with Python 3.10 or newer for full compatibility and ongoing support. Upgrade your Python environment if possible.

Install

• pip install python-engineio Basic Installation
• pip install "python-engineio[client]" Client-side with standard Python
• pip install "python-engineio[asyncio_client]" Client-side with asyncio
• pip install "python-engineio[asyncio]" uvicorn Server-side with asyncio (e.g., Uvicorn)
• pip install "python-engineio[eventlet]" eventlet Server-side with Eventlet

Imports

• Server

  import engineio
  eio_server = engineio.Server()

  For a standard (threaded) Engine.IO server.
• AsyncServer

  import engineio
  eio_server = engineio.AsyncServer()

  For an asyncio-based Engine.IO server.
• Client

  import engineio
  eio_client = engineio.Client()

  For a standard (threaded) Engine.IO client.
• AsyncClient

  import engineio
  eio_client = engineio.AsyncClient()

  For an asyncio-based Engine.IO client.
• WSGIApp

  from engineio import WSGIApp

  To wrap an Engine.IO server instance for WSGI compatibility.
• ASGIApp

  from engineio import ASGIApp

  To wrap an Engine.IO server instance for ASGI compatibility.

Quickstart

This quickstart demonstrates a basic Engine.IO server using the `AsyncServer` with ASGI mode, integrated with `uvicorn`. It defines event handlers for connect, message, and disconnect. A corresponding `AsyncClient` example is commented out, showing how to connect to the server and send/receive messages. Remember to install `uvicorn` and run the server and client in separate processes.

import engineio
import uvicorn

eio = engineio.AsyncServer(async_mode='asgi')
app = engineio.ASGIApp(eio)

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

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

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

# To run the server (requires uvicorn):
# if __name__ == '__main__':
#     uvicorn.run(app, host='127.0.0.1', port=5000)

# --- Client Example (run in a separate process/script) ---
# import engineio
# import asyncio

# eio_client = engineio.AsyncClient()

# @eio_client.on('connect')
# async def on_connect():
#     print('client connected')
#     await eio_client.send('Hello from client!')

# @eio_client.on('message')
# async def on_message(data):
#     print('client received: ', data)

# @eio_client.on('disconnect')
# async def on_disconnect():
#     print('client disconnected')

# async def start_client():
#     await eio_client.connect('http://localhost:5000')
#     await eio_client.wait()

# # To run the client:
# # if __name__ == '__main__':
# #    asyncio.run(start_client())