0
# Networking
1

2
Complete networking stack with cooperative sockets, SSL support, and gevent-aware I/O operations. All network operations work seamlessly with greenlets, yielding control during I/O to enable high concurrency.
3

4
## Capabilities
5

6
### Socket Operations
7

8
Cooperative socket interface that mirrors Python's standard socket API.
9

10
```python { .api }
11
def create_connection(address, timeout=None, source_address=None) -> socket:
12
    """
13
    Create a socket connection to address.
14
    
15
    Parameters:
16
    - address: tuple (host, port) or string path for Unix sockets
17
    - timeout: float, connection timeout in seconds
18
    - source_address: tuple, source address to bind to
19
    
20
    Returns:
21
    Connected socket object
22
    """
23

24
class socket:
25
    """
26
    Cooperative socket that yields during I/O operations.
27
    """
28
    
29
    def __init__(self, family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None):
30
        """
31
        Create a socket.
32
        
33
        Parameters:
34
        - family: int, address family (AF_INET, AF_INET6, AF_UNIX)
35
        - type: int, socket type (SOCK_STREAM, SOCK_DGRAM)
36
        - proto: int, protocol number
37
        - fileno: int, existing file descriptor
38
        """
39
    
40
    def connect(self, address):
41
        """
42
        Connect to address.
43
        
44
        Parameters:
45
        - address: tuple (host, port) or string path
46
        
47
        Returns:
48
        None
49
        """
50
    
51
    def bind(self, address):
52
        """
53
        Bind socket to address.
54
        
55
        Parameters:
56
        - address: tuple (host, port) or string path
57
        
58
        Returns:
59
        None
60
        """
61
    
62
    def listen(self, backlog=None):
63
        """
64
        Listen for connections.
65
        
66
        Parameters:
67
        - backlog: int, maximum number of pending connections
68
        
69
        Returns:
70
        None
71
        """
72
    
73
    def accept(self) -> tuple[socket, tuple]:
74
        """
75
        Accept a connection.
76
        
77
        Returns:
78
        tuple of (socket, address) for new connection
79
        """
80
    
81
    def recv(self, bufsize, flags=0) -> bytes:
82
        """
83
        Receive data from socket.
84
        
85
        Parameters:
86
        - bufsize: int, maximum bytes to receive
87
        - flags: int, optional flags
88
        
89
        Returns:
90
        bytes received
91
        """
92
    
93
    def send(self, data, flags=0) -> int:
94
        """
95
        Send data on socket.
96
        
97
        Parameters:
98
        - data: bytes, data to send
99
        - flags: int, optional flags
100
        
101
        Returns:
102
        int, number of bytes sent
103
        """
104
    
105
    def sendall(self, data, flags=0):
106
        """
107
        Send all data on socket.
108
        
109
        Parameters:
110
        - data: bytes, data to send
111
        - flags: int, optional flags
112
        
113
        Returns:
114
        None
115
        """
116
    
117
    def close(self):
118
        """
119
        Close the socket.
120
        
121
        Returns:
122
        None
123
        """
124
    
125
    def wait_read(self, timeout=None):
126
        """
127
        Wait for socket to become readable.
128
        
129
        Parameters:
130
        - timeout: float, maximum time to wait
131
        
132
        Returns:
133
        None
134
        """
135
    
136
    def wait_write(self, timeout=None):
137
        """
138
        Wait for socket to become writable.
139
        
140
        Parameters:
141
        - timeout: float, maximum time to wait
142
        
143
        Returns:
144
        None
145
        """
146
```
147

148
### DNS Resolution
149

150
Cooperative DNS resolution functions.
151

152
```python { .api }
153
def getaddrinfo(host, port, family=0, type=0, proto=0, flags=0):
154
    """
155
    Get address info for host and port.
156
    
157
    Parameters:
158
    - host: str, hostname or IP address
159
    - port: int or str, port number or service name
160
    - family: int, address family filter
161
    - type: int, socket type filter
162
    - proto: int, protocol filter
163
    - flags: int, optional flags
164
    
165
    Returns:
166
    list of (family, type, proto, canonname, sockaddr) tuples
167
    """
168

169
def gethostbyname(hostname) -> str:
170
    """
171
    Get IP address for hostname.
172
    
173
    Parameters:
174
    - hostname: str, hostname to resolve
175
    
176
    Returns:
177
    str, IP address
178
    """
179

180
def gethostbyaddr(ip_address) -> tuple:
181
    """
182
    Get hostname for IP address.
183
    
184
    Parameters:
185
    - ip_address: str, IP address to reverse lookup
186
    
187
    Returns:
188
    tuple of (hostname, aliaslist, ipaddrlist)
189
    """
190
```
191

192
### SSL Support
193

194
Secure socket layer support for encrypted connections.
195

196
```python { .api }
197
class SSLSocket:
198
    """
199
    SSL-wrapped socket for encrypted communication.
200
    """
201
    
202
    def read(self, len=1024) -> bytes:
203
        """
204
        Read data from SSL socket.
205
        
206
        Parameters:
207
        - len: int, maximum bytes to read
208
        
209
        Returns:
210
        bytes received
211
        """
212
    
213
    def write(self, data) -> int:
214
        """
215
        Write data to SSL socket.
216
        
217
        Parameters:
218
        - data: bytes, data to write
219
        
220
        Returns:
221
        int, number of bytes written
222
        """
223
    
224
    def do_handshake(self):
225
        """
226
        Perform SSL handshake.
227
        
228
        Returns:
229
        None
230
        """
231
    
232
    def unwrap(self) -> socket:
233
        """
234
        Unwrap SSL socket to plain socket.
235
        
236
        Returns:
237
        Plain socket object
238
        """
239

240
def wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ssl_version=PROTOCOL_TLS, ca_certs=None, do_handshake_on_connect=True, suppress_ragged_eofs=True, ciphers=None) -> SSLSocket:
241
    """
242
    Wrap socket with SSL.
243
    
244
    Parameters:
245
    - sock: socket object to wrap
246
    - keyfile: str, path to private key file
247
    - certfile: str, path to certificate file
248
    - server_side: bool, whether this is server side
249
    - cert_reqs: int, certificate requirements
250
    - ssl_version: int, SSL version to use
251
    - ca_certs: str, path to CA certificates
252
    - do_handshake_on_connect: bool, perform handshake immediately
253
    - suppress_ragged_eofs: bool, suppress SSL EOF errors
254
    - ciphers: str, cipher suite specification
255
    
256
    Returns:
257
    SSLSocket object
258
    """
259

260
class SSLContext:
261
    """
262
    SSL context for configuring SSL connections.
263
    """
264
    
265
    def wrap_socket(self, sock, server_side=False, do_handshake_on_connect=True, suppress_ragged_eofs=True, server_hostname=None) -> SSLSocket:
266
        """
267
        Wrap socket with this SSL context.
268
        
269
        Parameters:
270
        - sock: socket to wrap
271
        - server_side: bool, server mode
272
        - do_handshake_on_connect: bool, immediate handshake
273
        - suppress_ragged_eofs: bool, suppress EOF errors
274
        - server_hostname: str, expected server hostname
275
        
276
        Returns:
277
        SSLSocket object
278
        """
279
```
280

281
### File Objects
282

283
File-like objects for socket I/O.
284

285
```python { .api }
286
class FileObject:
287
    """
288
    File-like object wrapper for sockets.
289
    """
290
    
291
    def read(self, size=-1) -> bytes:
292
        """
293
        Read data from file object.
294
        
295
        Parameters:
296
        - size: int, bytes to read (-1 for all)
297
        
298
        Returns:
299
        bytes read
300
        """
301
    
302
    def readline(self, size=-1) -> bytes:
303
        """
304
        Read one line from file object.
305
        
306
        Parameters:
307
        - size: int, maximum bytes to read
308
        
309
        Returns:
310
        bytes for one line
311
        """
312
    
313
    def write(self, data) -> int:
314
        """
315
        Write data to file object.
316
        
317
        Parameters:
318
        - data: bytes, data to write
319
        
320
        Returns:
321
        int, bytes written
322
        """
323
    
324
    def flush(self):
325
        """
326
        Flush write buffers.
327
        
328
        Returns:
329
        None
330
        """
331
    
332
    def close(self):
333
        """
334
        Close file object.
335
        
336
        Returns:
337
        None
338
        """
339
```
340

341
## Usage Examples
342

343
### TCP Client
344

345
```python
346
import gevent
347
from gevent import socket
348

349
def tcp_client():
350
    # Create and connect socket
351
    sock = socket.socket()
352
    sock.connect(('example.com', 80))
353
    
354
    # Send HTTP request
355
    request = b'GET / HTTP/1.0\r\nHost: example.com\r\n\r\n'
356
    sock.sendall(request)
357
    
358
    # Receive response
359
    response = b''
360
    while True:
361
        data = sock.recv(4096)
362
        if not data:
363
            break
364
        response += data
365
    
366
    sock.close()
367
    return response
368

369
response = tcp_client()
370
print(response[:200])  # Print first 200 bytes
371
```
372

373
### TCP Server
374

375
```python
376
import gevent
377
from gevent import socket
378

379
def echo_server():
380
    server = socket.socket()
381
    server.bind(('localhost', 8080))
382
    server.listen(1000)
383
    
384
    print("Echo server listening on port 8080")
385
    
386
    while True:
387
        conn, addr = server.accept()
388
        gevent.spawn(handle_client, conn, addr)
389

390
def handle_client(conn, addr):
391
    print(f"Connection from {addr}")
392
    try:
393
        while True:
394
            data = conn.recv(1024)
395
            if not data:
396
                break
397
            conn.sendall(data)  # Echo back
398
    except Exception as e:
399
        print(f"Error handling client {addr}: {e}")
400
    finally:
401
        conn.close()
402

403
# Start server
404
echo_server()
405
```
406

407
### HTTPS Client
408

409
```python
410
import gevent
411
from gevent import socket, ssl
412

413
def https_client():
414
    # Create SSL context
415
    context = ssl.create_default_context()
416
    
417
    # Create socket and wrap with SSL
418
    sock = socket.socket()
419
    ssl_sock = context.wrap_socket(sock, server_hostname='httpbin.org')
420
    
421
    # Connect and send request
422
    ssl_sock.connect(('httpbin.org', 443))
423
    request = b'GET /get HTTP/1.1\r\nHost: httpbin.org\r\n\r\n'
424
    ssl_sock.sendall(request)
425
    
426
    # Read response
427
    response = ssl_sock.recv(4096)
428
    ssl_sock.close()
429
    
430
    return response
431

432
response = https_client()
433
print(response.decode())
434
```