0
# Simple WebSocket
1

2
Simple WebSocket provides easy-to-use WebSocket server and client implementations for Python applications. It supports both synchronous (blocking) and asynchronous (async/await) programming patterns, with built-in connection management, message handling, and support for multiple web frameworks.
3

4
## Package Information
5

6
- **Package Name**: simple-websocket
7
- **Language**: Python
8
- **Installation**: `pip install simple-websocket`
9

10
## Core Imports
11

12
```python
13
import simple_websocket
14
```
15

16
Direct class imports:
17

18
```python
19
from simple_websocket import Server, Client, AioServer, AioClient
20
from simple_websocket import ConnectionError, ConnectionClosed, SimpleWebsocketError
21
```
22

23
ASGI integration import:
24

25
```python
26
from simple_websocket.asgi import WebSocketASGI
27
```
28

29
## Basic Usage
30

31
### Synchronous Server
32

33
```python
34
import simple_websocket
35

36
# Accept WebSocket connection from WSGI environ
37
ws = simple_websocket.Server.accept(environ)
38

39
# Send and receive messages
40
ws.send("Hello from server!")
41
message = ws.receive()
42
print(f"Received: {message}")
43

44
# Close connection
45
ws.close()
46
```
47

48
### Synchronous Client
49

50
```python
51
import simple_websocket
52

53
# Connect to WebSocket server
54
ws = simple_websocket.Client.connect("ws://localhost:8000/ws")
55

56
# Send and receive messages
57
ws.send("Hello from client!")
58
response = ws.receive()
59
print(f"Server responded: {response}")
60

61
# Close connection
62
ws.close()
63
```
64

65
### Asynchronous Server
66

67
```python
68
import simple_websocket
69

70
# Accept async WebSocket connection (aiohttp example)
71
ws = await simple_websocket.AioServer.accept(aiohttp=request)
72

73
# Send and receive messages
74
await ws.send("Hello from async server!")
75
message = await ws.receive()
76
print(f"Received: {message}")
77

78
# Close connection
79
await ws.close()
80
```
81

82
### Asynchronous Client
83

84
```python
85
import simple_websocket
86

87
# Connect to WebSocket server asynchronously
88
ws = await simple_websocket.AioClient.connect("ws://localhost:8000/ws")
89

90
# Send and receive messages
91
await ws.send("Hello from async client!")
92
response = await ws.receive()
93
print(f"Server responded: {response}")
94

95
# Close connection
96
await ws.close()
97
```
98

99
## Architecture
100

101
Simple WebSocket provides two implementation layers:
102

103
- **Synchronous Layer**: Server and Client classes using threads for I/O operations
104
- **Asynchronous Layer**: AioServer and AioClient classes using asyncio for I/O operations
105

106
Both layers share common functionality:
107
- **Message Handling**: Automatic detection of text vs binary messages based on data type
108
- **Connection Management**: Built-in connection lifecycle management with proper cleanup
109
- **Framework Integration**: Support for multiple web frameworks (WSGI, ASGI, aiohttp)
110
- **Subprotocol Support**: Full WebSocket subprotocol negotiation
111
- **Error Handling**: Specific exceptions for connection errors and closures
112

113
## Capabilities
114

115
### Synchronous WebSocket Operations
116

117
Core synchronous WebSocket server and client functionality with thread-based I/O operations. Supports WSGI environments and direct socket connections with automatic message type detection.
118

119
```python { .api }
120
class Server:
121
    @classmethod
122
    def accept(cls, environ, subprotocols=None, receive_bytes=4096, 
123
               ping_interval=None, max_message_size=None, thread_class=None, 
124
               event_class=None, selector_class=None): ...
125
    
126
    def send(self, data): ...
127
    def receive(self, timeout=None): ...
128
    def close(self, reason=None, message=None): ...
129

130
class Client:
131
    @classmethod
132
    def connect(cls, url, subprotocols=None, headers=None, receive_bytes=4096,
133
                ping_interval=None, max_message_size=None, ssl_context=None,
134
                thread_class=None, event_class=None): ...
135
    
136
    def send(self, data): ...
137
    def receive(self, timeout=None): ...
138
    def close(self, reason=None, message=None): ...
139
```
140

141
[Synchronous WebSocket](./sync-websocket.md)
142

143
### Asynchronous WebSocket Operations
144

145
Async/await WebSocket server and client functionality using asyncio. Supports multiple async frameworks including aiohttp, ASGI, and custom socket integration with full async context management.
146

147
```python { .api }
148
class AioServer:
149
    @classmethod
150
    async def accept(cls, aiohttp=None, asgi=None, sock=None, headers=None,
151
                     subprotocols=None, receive_bytes=4096, ping_interval=None,
152
                     max_message_size=None): ...
153
    
154
    async def send(self, data): ...
155
    async def receive(self, timeout=None): ...
156
    async def close(self, reason=None, message=None): ...
157

158
class AioClient:
159
    @classmethod
160
    async def connect(cls, url, subprotocols=None, headers=None, receive_bytes=4096,
161
                      ping_interval=None, max_message_size=None, ssl_context=None): ...
162
    
163
    async def send(self, data): ...
164
    async def receive(self, timeout=None): ...
165
    async def close(self, reason=None, message=None): ...
166
```
167

168
[Asynchronous WebSocket](./async-websocket.md)
169

170
### ASGI Integration
171

172
Direct ASGI WebSocket support for modern Python web frameworks that implement ASGI specification, providing seamless integration with ASGI-compatible frameworks.
173

174
```python { .api }
175
class WebSocketASGI:
176
    @classmethod
177
    async def accept(cls, scope, receive, send, subprotocols=None): ...
178
    
179
    async def receive(self): ...
180
    async def send(self, data): ...
181
    async def close(self): ...
182
```
183

184
[ASGI Integration](./asgi-integration.md)
185

186
### Exception Handling
187

188
WebSocket-specific exceptions for handling connection errors and connection closures with detailed error information and status codes.
189

190
```python { .api }
191
class SimpleWebsocketError(RuntimeError): ...
192

193
class ConnectionError(SimpleWebsocketError):
194
    def __init__(self, status_code=None): ...
195

196
class ConnectionClosed(SimpleWebsocketError):
197
    def __init__(self, reason=None, message=None): ...
198
```
199

200
[Exception Handling](./exceptions.md)