0
# Python Engine.IO
1

2
A comprehensive Python implementation of the Engine.IO realtime communication protocol, providing both client and server capabilities for building real-time web applications. Engine.IO enables bidirectional event-based communication between clients and servers with automatic reconnection, transport fallbacks (WebSocket to HTTP long-polling), and seamless integration with multiple async frameworks.
3

4
## Package Information
5

6
- **Package Name**: python-engineio
7
- **Language**: Python
8
- **Installation**: `pip install python-engineio`
9
- **Python Requirements**: >= 3.6
10
- **Core Dependencies**: simple-websocket >= 0.10.0
11

12
## Core Imports
13

14
```python
15
import engineio
16
```
17

18
Common usage patterns:
19

20
```python
21
# Server applications
22
from engineio import Server, AsyncServer
23
from engineio import WSGIApp, ASGIApp
24

25
# Client applications  
26
from engineio import Client, AsyncClient
27

28
# Exception handling
29
from engineio.exceptions import EngineIOError, ConnectionError
30
```
31

32
## Basic Usage
33

34
### Simple Server Example
35

36
```python
37
import engineio
38

39
# Create synchronous server
40
eio = engineio.Server()
41

42
@eio.on('connect')
43
def on_connect(sid, environ):
44
    print(f'Client {sid} connected')
45

46
@eio.on('message')
47
def on_message(sid, data):
48
    print(f'Received {data} from {sid}')
49
    eio.send(sid, 'response message')
50

51
@eio.on('disconnect')
52
def on_disconnect(sid):
53
    print(f'Client {sid} disconnected')
54

55
# Use with WSGI application
56
app = engineio.WSGIApp(eio)
57
```
58

59
### Simple Client Example
60

61
```python
62
import engineio
63

64
# Create synchronous client
65
eio = engineio.Client()
66

67
@eio.on('connect')
68
def on_connect():
69
    print('Connected to server')
70
    eio.send('Hello Server!')
71

72
@eio.on('message')
73
def on_message(data):
74
    print(f'Received from server: {data}')
75

76
@eio.on('disconnect')
77
def on_disconnect():
78
    print('Disconnected from server')
79

80
# Connect to server
81
eio.connect('http://localhost:5000')
82
eio.wait()
83
```
84

85
### Async Server Example
86

87
```python
88
import engineio
89

90
# Create asynchronous server
91
eio = engineio.AsyncServer()
92

93
@eio.on('connect')
94
async def on_connect(sid, environ):
95
    print(f'Client {sid} connected')
96

97
@eio.on('message')
98
async def on_message(sid, data):
99
    print(f'Received {data} from {sid}')
100
    await eio.send(sid, 'async response')
101

102
# Use with ASGI application
103
app = engineio.ASGIApp(eio)
104
```
105

106
## Architecture
107

108
Engine.IO provides a layered architecture for real-time communication:
109

110
- **Transport Layer**: Handles WebSocket and HTTP long-polling protocols with automatic upgrades
111
- **Session Management**: Manages client connections, sessions, and automatic reconnection
112
- **Event System**: Event-driven programming model for handling connections, messages, and disconnections
113
- **Middleware Integration**: WSGI/ASGI middleware for seamless web framework integration
114
- **Async Support**: Native support for asyncio, eventlet, gevent, and threading models
115

116
The library serves as the foundation transport layer for Socket.IO and other real-time communication systems, providing reliable bidirectional messaging with automatic connection management and protocol negotiation.
117

118
## Capabilities
119

120
### Synchronous Server
121

122
Full-featured Engine.IO server for synchronous Python applications with support for multiple async models including threading, eventlet, and gevent.
123

124
```python { .api }
125
class Server:
126
    def __init__(self, async_mode=None, ping_interval=25, ping_timeout=20, **kwargs): ...
127
    def send(self, sid, data): ...
128
    def disconnect(self, sid=None): ...
129
    def on(self, event, handler=None): ...
130
    def handle_request(self, environ, start_response): ...
131
```
132

133
[Server](./server.md)
134

135
### Asynchronous Server
136

137
Engine.IO server optimized for asyncio-based applications with full async/await support and integration with modern async web frameworks.
138

139
```python { .api }
140
class AsyncServer:
141
    def __init__(self, async_mode=None, ping_interval=25, ping_timeout=20, **kwargs): ...
142
    async def send(self, sid, data): ...
143
    async def disconnect(self, sid=None): ...
144
    def on(self, event, handler=None): ...
145
    async def handle_request(self, *args, **kwargs): ...
146
```
147

148
[Async Server](./async-server.md)
149

150
### Synchronous Client
151

152
Engine.IO client for connecting to servers from synchronous Python applications with automatic reconnection and transport fallback support.
153

154
```python { .api }
155
class Client:
156
    def __init__(self, logger=False, request_timeout=5, **kwargs): ...
157
    def connect(self, url, headers=None, transports=None, engineio_path='engine.io'): ...
158
    def send(self, data): ...
159
    def disconnect(self, abort=False, reason=None): ...
160
    def on(self, event, handler=None): ...
161
```
162

163
[Client](./client.md)
164

165
### Asynchronous Client
166

167
Asyncio-based Engine.IO client for connecting to servers from async Python applications with full async/await support.
168

169
```python { .api }
170
class AsyncClient:
171
    def __init__(self, logger=False, request_timeout=5, **kwargs): ...
172
    async def connect(self, url, headers=None, transports=None, engineio_path='engine.io'): ...
173
    async def send(self, data): ...
174
    async def disconnect(self, abort=False, reason=None): ...
175
    def on(self, event, handler=None): ...
176
```
177

178
[Async Client](./async-client.md)
179

180
### WSGI Middleware
181

182
WSGI application middleware for integrating Engine.IO servers with Flask, Django, and other WSGI-compatible web frameworks.
183

184
```python { .api }
185
class WSGIApp:
186
    def __init__(self, engineio_app, wsgi_app=None, static_files=None, engineio_path='engine.io'): ...
187
    def __call__(self, environ, start_response): ...
188
```
189

190
[WSGI Middleware](./wsgi-middleware.md)
191

192
### ASGI Middleware
193

194
ASGI application middleware for integrating Engine.IO servers with FastAPI, Starlette, and other ASGI-compatible web frameworks.
195

196
```python { .api }
197
class ASGIApp:
198
    def __init__(self, engineio_server, other_asgi_app=None, static_files=None, **kwargs): ...
199
    async def __call__(self, scope, receive, send): ...
200
```
201

202
[ASGI Middleware](./asgi-middleware.md)
203

204
### Tornado Integration
205

206
Tornado WebSocket handler for integrating Engine.IO with Tornado web applications. Returns a dynamically created handler class that extends tornado.websocket.WebSocketHandler.
207

208
```python { .api }
209
def get_tornado_handler(engineio_server):
210
    """
211
    Return a Tornado WebSocket handler class for Engine.IO integration.
212
    
213
    Args:
214
        engineio_server (AsyncServer): The Engine.IO async server instance
215
        
216
    Returns:
217
        class: Tornado WebSocket handler class that extends WebSocketHandler
218
        
219
    Note:
220
        Function may return None if Tornado is not installed.
221
        The returned handler class supports both HTTP and WebSocket requests.
222
    """
223
```
224

225
### Exception Handling
226

227
Comprehensive exception system for handling Engine.IO-specific errors and connection issues.
228

229
```python { .api }
230
class EngineIOError(Exception): ...
231
class ContentTooLongError(EngineIOError): ...
232
class UnknownPacketError(EngineIOError): ...
233
class QueueEmpty(EngineIOError): ...
234
class SocketIsClosedError(EngineIOError): ...
235
class ConnectionError(EngineIOError): ...
236
```
237

238
[Exception Handling](./exceptions.md)
239

240
## Types
241

242
```python { .api }
243
# Session ID type
244
SessionId = str
245

246
# Event handler signature
247
EventHandler = Callable[[str, Any], None]
248
AsyncEventHandler = Callable[[str, Any], Awaitable[None]]
249

250
# WSGI environment
251
WSGIEnviron = Dict[str, Any]
252

253
# Transport types
254
Transport = Literal['polling', 'websocket']
255
```