0
# Asynchronous WebSocket
1

2
Asynchronous WebSocket implementation providing asyncio-based WebSocket server and client functionality. These classes handle WebSocket connections using async/await patterns with full asyncio integration for modern Python applications.
3

4
## Capabilities
5

6
### AioServer Class
7

8
Async WebSocket server supporting multiple async frameworks including aiohttp, ASGI, and custom socket integration. Provides seamless integration with asyncio-based web applications.
9

10
```python { .api }
11
class AioServer:
12
    def __init__(self, request, subprotocols=None, receive_bytes=4096,
13
                 ping_interval=None, max_message_size=None):
14
        """
15
        Initialize async WebSocket server.
16
        
17
        Parameters:
18
        - request: Request object containing connection details
19
        - subprotocols: List of supported subprotocols or None
20
        - receive_bytes: Buffer size for receiving data (default: 4096)
21
        - ping_interval: Ping interval in seconds or None to disable
22
        - max_message_size: Maximum message size in bytes or None for no limit
23
        """
24
```
25

26
```python { .api }
27
@classmethod
28
async def accept(cls, aiohttp=None, asgi=None, sock=None, headers=None,
29
                 subprotocols=None, receive_bytes=4096, ping_interval=None,
30
                 max_message_size=None):
31
    """
32
    Accept async WebSocket connection from client.
33
    
34
    Parameters:
35
    - aiohttp: aiohttp request object (mutually exclusive with other options)
36
    - asgi: ASGI (scope, receive, send) tuple (mutually exclusive)
37
    - sock: Connected socket with headers dict (mutually exclusive)
38
    - headers: Request headers dict when using sock parameter
39
    - subprotocols: List of supported subprotocols or None
40
    - receive_bytes: Buffer size for receiving data (default: 4096)
41
    - ping_interval: Send ping packets at this interval in seconds or None
42
    - max_message_size: Maximum allowed message size in bytes or None
43
    
44
    Returns:
45
    AioServer instance connected to the client
46
    """
47
```
48

49
### AioServer Methods
50

51
```python { .api }
52
async def send(self, data):
53
    """
54
    Send data over the WebSocket connection.
55
    
56
    Parameters:
57
    - data: Data to send (str for text message, bytes for binary message)
58
    """
59

60
async def receive(self, timeout=None):
61
    """
62
    Receive data over the WebSocket connection.
63
    
64
    Parameters:
65
    - timeout: Timeout in seconds (None for indefinite, 0 for non-blocking)
66
    
67
    Returns:
68
    Received data as str or bytes depending on message type
69
    """
70

71
async def close(self, reason=None, message=None):
72
    """
73
    Close the WebSocket connection.
74
    
75
    Parameters:
76
    - reason: Numeric status code for closure (default: 1000 normal closure)
77
    - message: Text message to send with closure
78
    """
79

80
def choose_subprotocol(self, request):
81
    """
82
    Choose subprotocol for the WebSocket connection.
83
    
84
    Parameters:
85
    - request: Request object containing client's requested subprotocols
86
    
87
    Returns:
88
    Selected subprotocol name or None if no subprotocol chosen
89
    """
90
```
91

92
### AioClient Class
93

94
Async WebSocket client that connects to WebSocket servers using asyncio. Supports secure connections, custom headers, subprotocol negotiation, and full async context management.
95

96
```python { .api }
97
class AioClient:
98
    def __init__(self, url, subprotocols=None, headers=None, receive_bytes=4096,
99
                 ping_interval=None, max_message_size=None, ssl_context=None):
100
        """
101
        Initialize async WebSocket client.
102
        
103
        Parameters:
104
        - url: WebSocket URL to connect to (ws:// or wss://)
105
        - subprotocols: Subprotocol name or list of names to request
106
        - headers: Additional HTTP headers as dict or list of tuples
107
        - receive_bytes: Buffer size for receiving data (default: 4096)
108
        - ping_interval: Ping interval in seconds or None to disable
109
        - max_message_size: Maximum message size in bytes or None for no limit
110
        - ssl_context: SSL context for secure connections or None for default
111
        """
112
```
113

114
```python { .api }
115
@classmethod
116
async def connect(cls, url, subprotocols=None, headers=None, receive_bytes=4096,
117
                  ping_interval=None, max_message_size=None, ssl_context=None):
118
    """
119
    Create and connect async WebSocket client.
120
    
121
    Parameters:
122
    - url: WebSocket URL (ws:// or wss://)
123
    - subprotocols: Subprotocol name or list of preference-ordered names
124
    - headers: Additional HTTP headers as dict or list of tuples
125
    - receive_bytes: Buffer size for receiving data (default: 4096)
126
    - ping_interval: Send ping packets at this interval in seconds or None
127
    - max_message_size: Maximum allowed message size in bytes or None
128
    - ssl_context: Custom SSL context or None for default secure context
129
    
130
    Returns:
131
    Connected AioClient instance
132
    """
133
```
134

135
### AioClient Methods
136

137
```python { .api }
138
async def send(self, data):
139
    """
140
    Send data over the WebSocket connection.
141
    
142
    Parameters:
143
    - data: Data to send (str for text message, bytes for binary message)
144
    """
145

146
async def receive(self, timeout=None):
147
    """
148
    Receive data over the WebSocket connection.
149
    
150
    Parameters:
151
    - timeout: Timeout in seconds (None for indefinite, 0 for non-blocking)
152
    
153
    Returns:
154
    Received data as str or bytes depending on message type
155
    """
156

157
async def close(self, reason=None, message=None):
158
    """
159
    Close the WebSocket connection and underlying socket.
160
    
161
    Parameters:
162
    - reason: Numeric status code for closure (default: 1000 normal closure)
163
    - message: Text message to send with closure
164
    """
165
```
166

167
## Usage Examples
168

169
### aiohttp Integration
170

171
```python
172
import simple_websocket
173
from aiohttp import web, WSMsgType
174

175
async def websocket_handler(request):
176
    # Accept WebSocket connection from aiohttp
177
    ws = await simple_websocket.AioServer.accept(aiohttp=request)
178
    
179
    try:
180
        async for message in ws:
181
            # Process incoming message
182
            if message.type == WSMsgType.TEXT:
183
                data = message.data
184
                # Echo message back
185
                await ws.send(f"Echo: {data}")
186
            elif message.type == WSMsgType.ERROR:
187
                print(f"WebSocket error: {ws.exception()}")
188
                break
189
    except simple_websocket.ConnectionClosed:
190
        print("Client disconnected")
191
    finally:
192
        await ws.close()
193

194
app = web.Application()
195
app.router.add_get('/ws', websocket_handler)
196
```
197

198
### Async Client Usage
199

200
```python
201
import asyncio
202
import simple_websocket
203

204
async def client_example():
205
    try:
206
        # Connect to WebSocket server
207
        ws = await simple_websocket.AioClient.connect("ws://localhost:8000/ws")
208
        
209
        # Send message
210
        await ws.send("Hello, Async Server!")
211
        
212
        # Receive response with timeout
213
        response = await ws.receive(timeout=10)
214
        print(f"Server response: {response}")
215
        
216
        # Send binary data
217
        await ws.send(b"Binary data")
218
        binary_response = await ws.receive()
219
        print(f"Binary response: {binary_response}")
220
        
221
    except simple_websocket.ConnectionError as e:
222
        print(f"Failed to connect: {e}")
223
    except simple_websocket.ConnectionClosed:
224
        print("Server closed connection")
225
    except asyncio.TimeoutError:
226
        print("Timeout waiting for response")
227
    finally:
228
        await ws.close()
229

230
# Run the client
231
asyncio.run(client_example())
232
```
233

234
### Custom Socket Integration
235

236
```python
237
import asyncio
238
import socket
239
import simple_websocket
240

241
async def custom_socket_server():
242
    # Create and bind socket
243
    server_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
244
    server_sock.bind(('localhost', 8000))
245
    server_sock.listen(1)
246
    
247
    while True:
248
        client_sock, addr = server_sock.accept()
249
        
250
        # Prepare headers dict (simplified example)
251
        headers = {
252
            'Host': 'localhost:8000',
253
            'Connection': 'Upgrade',
254
            'Upgrade': 'websocket',
255
            'Sec-WebSocket-Key': 'example-key',
256
            'Sec-WebSocket-Version': '13'
257
        }
258
        
259
        # Accept WebSocket with custom socket
260
        ws = await simple_websocket.AioServer.accept(
261
            sock=client_sock,
262
            headers=headers
263
        )
264
        
265
        try:
266
            # Handle connection
267
            while True:
268
                message = await ws.receive(timeout=30)
269
                if message is None:
270
                    break
271
                await ws.send(f"Received: {message}")
272
        except simple_websocket.ConnectionClosed:
273
            print(f"Client {addr} disconnected")
274
        finally:
275
            await ws.close()
276

277
# Run the server
278
asyncio.run(custom_socket_server())
279
```
280

281
### Async Context Manager Pattern
282

283
```python
284
import asyncio
285
import simple_websocket
286

287
class AsyncWebSocketClient:
288
    def __init__(self, url, **kwargs):
289
        self.url = url
290
        self.kwargs = kwargs
291
        self.ws = None
292
    
293
    async def __aenter__(self):
294
        self.ws = await simple_websocket.AioClient.connect(self.url, **self.kwargs)
295
        return self.ws
296
    
297
    async def __aexit__(self, exc_type, exc_val, exc_tb):
298
        if self.ws:
299
            await self.ws.close()
300

301
# Usage with async context manager
302
async def context_manager_example():
303
    async with AsyncWebSocketClient("ws://localhost:8000/ws") as ws:
304
        await ws.send("Hello with context manager!")
305
        response = await ws.receive()
306
        print(f"Response: {response}")
307
    # WebSocket automatically closed when exiting context
308

309
asyncio.run(context_manager_example())
310
```
311

312
## Types
313

314
### AioBase Class Attributes
315

316
```python { .api }
317
class AioBase:
318
    subprotocol: str | None  # Negotiated subprotocol name
319
    connected: bool          # Connection status
320
    receive_bytes: int       # Buffer size for receiving data
321
    ping_interval: float | None  # Ping interval in seconds
322
    max_message_size: int | None  # Maximum message size limit
323
    rsock: asyncio.StreamReader | None  # Read stream
324
    wsock: asyncio.StreamWriter | None  # Write stream
325
    event: asyncio.Event     # Async event for synchronization
326
    task: asyncio.Task | None  # Background task handle
327
```