0
# HTTP Client
1

2
Comprehensive HTTP client functionality built on asyncio for making HTTP requests with session management, connection pooling, and extensive configuration options. The client supports all HTTP methods, automatic redirects, cookie handling, authentication, and WebSocket connections.
3

4
## Capabilities
5

6
### Client Sessions
7

8
The primary interface for making HTTP requests. ClientSession provides connection pooling, cookie handling, and configuration management across multiple requests.
9

10
```python { .api }
11
class ClientSession:
12
    def __init__(
13
        self,
14
        base_url=None,
15
        *,
16
        connector=None,
17
        loop=None,
18
        cookies=None,
19
        headers=None,
20
        proxy=None,
21
        proxy_auth=None,
22
        skip_auto_headers=None,
23
        auth=None,
24
        json_serialize=json.dumps,
25
        request_class=None,
26
        response_class=None,
27
        ws_response_class=None,
28
        version=None,
29
        cookie_jar=None,
30
        connector_owner=True,
31
        raise_for_status=False,
32
        read_timeout=None,
33
        conn_timeout=None,
34
        timeout=None,
35
        auto_decompress=True,
36
        trust_env=False,
37
        requote_redirect_url=True,
38
        trace_configs=None,
39
        read_bufsize=65536,
40
        max_line_size=8190,
41
        max_field_size=8190,
42
        fallback_charset_resolver=None
43
    ):
44
        """
45
        Create HTTP client session.
46
        
47
        Parameters:
48
        - base_url: Base URL for all requests
49
        - connector: Connection pool manager
50
        - loop: Event loop
51
        - cookies: Default cookies for all requests
52
        - headers: Default headers for all requests
53
        - proxy: Proxy URL
54
        - proxy_auth: Proxy authentication
55
        - skip_auto_headers: Headers to skip auto-generation
56
        - auth: Default authentication
57
        - json_serialize: JSON serialization function
58
        - request_class: Custom request class
59
        - response_class: Custom response class
60
        - ws_response_class: Custom WebSocket response class
61
        - version: HTTP version
62
        - cookie_jar: Cookie storage implementation
63
        - connector_owner: Whether session owns connector
64
        - raise_for_status: Auto-raise for HTTP errors
65
        - read_timeout: Read timeout (deprecated)
66
        - conn_timeout: Connection timeout (deprecated)
67
        - timeout: Timeout configuration
68
        - auto_decompress: Auto-decompress responses
69
        - trust_env: Trust environment variables for proxy
70
        - requote_redirect_url: Re-quote redirect URLs
71
        - trace_configs: Request tracing configurations
72
        - read_bufsize: Read buffer size
73
        - max_line_size: Maximum line size
74
        - max_field_size: Maximum header field size
75
        - fallback_charset_resolver: Charset resolver function
76
        """
77
    
78
    async def get(self, url, **kwargs):
79
        """Make GET request."""
80
    
81
    async def post(self, url, **kwargs):
82
        """Make POST request."""
83
    
84
    async def put(self, url, **kwargs):
85
        """Make PUT request."""
86
    
87
    async def patch(self, url, **kwargs):
88
        """Make PATCH request."""
89
    
90
    async def delete(self, url, **kwargs):
91
        """Make DELETE request."""
92
    
93
    async def head(self, url, **kwargs):
94
        """Make HEAD request."""
95
    
96
    async def options(self, url, **kwargs):
97
        """Make OPTIONS request."""
98
    
99
    async def request(self, method, url, **kwargs):
100
        """Make HTTP request with specified method."""
101
    
102
    async def ws_connect(self, url, **kwargs):
103
        """Establish WebSocket connection."""
104
    
105
    async def close(self):
106
        """Close session and cleanup resources."""
107
    
108
    def closed(self):
109
        """Check if session is closed."""
110
```
111

112
### Standalone Request Function
113

114
Convenience function for making single HTTP requests without creating a session.
115

116
```python { .api }
117
async def request(
118
    method,
119
    url,
120
    *,
121
    params=None,
122
    data=None,
123
    json=None,
124
    headers=None,
125
    cookies=None,
126
    auth=None,
127
    timeout=None,
128
    allow_redirects=True,
129
    proxy=None,
130
    ssl=None,
131
    **kwargs
132
):
133
    """
134
    Make HTTP request without creating session.
135
    
136
    Parameters:
137
    - method (str): HTTP method
138
    - url (str or URL): Request URL
139
    - params (dict): URL query parameters
140
    - data: Request body data
141
    - json: JSON request body
142
    - headers (dict): Request headers
143
    - cookies (dict): Request cookies
144
    - auth: Authentication credentials
145
    - timeout: Request timeout configuration
146
    - allow_redirects (bool): Follow redirects
147
    - proxy (str): Proxy URL
148
    - ssl: SSL context or verification settings
149
    
150
    Returns:
151
    ClientResponse: HTTP response object
152
    """
153
```
154

155
### Request and Response Objects
156

157
Objects representing HTTP requests and responses with comprehensive data access methods.
158

159
```python { .api }
160
class ClientRequest:
161
    def __init__(
162
        self,
163
        method,
164
        url,
165
        *,
166
        params=None,
167
        headers=None,
168
        data=None,
169
        cookies=None,
170
        auth=None,
171
        **kwargs
172
    ):
173
        """HTTP request representation."""
174
    
175
    @property
176
    def method(self):
177
        """Request HTTP method."""
178
    
179
    @property
180
    def url(self):
181
        """Request URL."""
182
    
183
    @property
184
    def headers(self):
185
        """Request headers."""
186

187
class ClientResponse:
188
    @property
189
    def status(self):
190
        """HTTP status code."""
191
    
192
    @property
193
    def reason(self):
194
        """HTTP reason phrase."""
195
    
196
    @property
197
    def headers(self):
198
        """Response headers."""
199
    
200
    @property
201
    def url(self):
202
        """Response URL."""
203
    
204
    @property
205
    def content_type(self):
206
        """Response content type."""
207
    
208
    async def read(self):
209
        """Read response body as bytes."""
210
    
211
    async def text(self, encoding=None):
212
        """Read response body as text."""
213
    
214
    async def json(self, **kwargs):
215
        """Parse response body as JSON."""
216
    
217
    def raise_for_status(self):
218
        """Raise exception for HTTP error status."""
219
    
220
    async def release(self):
221
        """Release response resources."""
222
```
223

224
### Connection Management
225

226
Connection pooling and management with support for different transport types and SSL configuration.
227

228
```python { .api }
229
class BaseConnector:
230
    def __init__(
231
        self,
232
        *,
233
        keepalive_timeout=30,
234
        enable_cleanup_closed=False,
235
        limit=100,
236
        limit_per_host=30,
237
        **kwargs
238
    ):
239
        """Base connector for connection management."""
240

241
class TCPConnector(BaseConnector):
242
    def __init__(
243
        self,
244
        *,
245
        ssl=None,
246
        use_dns_cache=True,
247
        ttl_dns_cache=10,
248
        family=0,
249
        local_addr=None,
250
        resolver=None,
251
        **kwargs
252
    ):
253
        """TCP connector for HTTP connections."""
254

255
class UnixConnector(BaseConnector):
256
    def __init__(self, path, **kwargs):
257
        """Unix domain socket connector."""
258

259
class NamedPipeConnector(BaseConnector):
260
    def __init__(self, path, **kwargs):
261
        """Named pipe connector (Windows)."""
262
```
263

264
### Timeout Configuration
265

266
Comprehensive timeout management for different phases of HTTP requests.
267

268
```python { .api }
269
class ClientTimeout:
270
    def __init__(
271
        self,
272
        total=None,
273
        sock_connect=None,
274
        sock_read=None
275
    ):
276
        """
277
        Configure request timeouts.
278
        
279
        Parameters:
280
        - total (float): Total request timeout
281
        - sock_connect (float): Socket connection timeout
282
        - sock_read (float): Socket read timeout
283
        """
284
    
285
    @property
286
    def total(self):
287
        """Total timeout value."""
288
    
289
    @property
290
    def sock_connect(self):
291
        """Socket connect timeout."""
292
    
293
    @property
294
    def sock_read(self):
295
        """Socket read timeout."""
296
```
297

298
### Authentication
299

300
Authentication helpers for common HTTP authentication schemes.
301

302
```python { .api }
303
class BasicAuth:
304
    def __init__(self, login, password, encoding='latin1'):
305
        """
306
        HTTP Basic authentication.
307
        
308
        Parameters:
309
        - login (str): Username
310
        - password (str): Password  
311
        - encoding (str): Text encoding
312
        """
313
    
314
    @property
315
    def login(self):
316
        """Authentication username."""
317
    
318
    @property
319
    def password(self):
320
        """Authentication password."""
321

322
class DigestAuthMiddleware:
323
    def __init__(self, username, password):
324
        """
325
        HTTP Digest authentication middleware.
326
        
327
        Parameters:
328
        - username (str): Username
329
        - password (str): Password
330
        """
331
```
332

333
### Client Exceptions
334

335
Comprehensive exception hierarchy for HTTP client errors.
336

337
```python { .api }
338
class ClientError(Exception):
339
    """Base exception for client errors."""
340

341
class ClientConnectionError(ClientError):
342
    """Connection-related errors."""
343

344
class ClientConnectorError(ClientConnectionError):
345
    """Connector-specific errors."""
346

347
class ClientConnectorDNSError(ClientConnectorError):
348
    """DNS resolution errors."""
349

350
class ClientConnectorSSLError(ClientConnectorError):
351
    """SSL/TLS connector errors."""
352

353
class ClientResponseError(ClientError):
354
    """HTTP response errors."""
355
    
356
    @property
357
    def status(self):
358
        """HTTP status code."""
359
    
360
    @property
361
    def message(self):
362
        """Error message."""
363

364
class ClientTimeout(ClientError):
365
    """Request timeout errors."""
366

367
class ContentTypeError(ClientError):
368
    """Content type parsing errors."""
369

370
class InvalidURL(ClientError):
371
    """Invalid URL errors."""
372

373
class TooManyRedirects(ClientError):
374
    """Excessive redirect errors."""
375
```
376

377
### SSL and Security
378

379
SSL/TLS configuration and security features.
380

381
```python { .api }
382
class Fingerprint:
383
    def __init__(self, fingerprint):
384
        """
385
        SSL certificate fingerprint verification.
386
        
387
        Parameters:
388
        - fingerprint (bytes): Expected certificate fingerprint
389
        """
390
    
391
    def check(self, transport):
392
        """Verify certificate fingerprint."""
393
```
394

395
## Usage Examples
396

397
### Basic HTTP Client
398

399
```python
400
import asyncio
401
import aiohttp
402

403
async def fetch_data():
404
    async with aiohttp.ClientSession() as session:
405
        # GET request
406
        async with session.get('https://api.example.com/users') as response:
407
            users = await response.json()
408
        
409
        # POST request with JSON data
410
        user_data = {'name': 'John', 'email': 'john@example.com'}
411
        async with session.post('https://api.example.com/users', 
412
                               json=user_data) as response:
413
            result = await response.json()
414
        
415
        return users, result
416

417
users, result = asyncio.run(fetch_data())
418
```
419

420
### Custom Session Configuration
421

422
```python
423
import aiohttp
424
import asyncio
425

426
async def configured_client():
427
    # Custom timeout configuration
428
    timeout = aiohttp.ClientTimeout(total=30, sock_connect=10)
429
    
430
    # Custom headers for all requests
431
    headers = {'User-Agent': 'MyApp/1.0'}
432
    
433
    # Authentication
434
    auth = aiohttp.BasicAuth('username', 'password')
435
    
436
    async with aiohttp.ClientSession(
437
        timeout=timeout,
438
        headers=headers,
439
        auth=auth
440
    ) as session:
441
        async with session.get('https://api.example.com/protected') as response:
442
            return await response.text()
443

444
data = asyncio.run(configured_client())
445
```
446

447
### Error Handling
448

449
```python
450
import aiohttp
451
import asyncio
452

453
async def robust_request():
454
    try:
455
        async with aiohttp.ClientSession() as session:
456
            async with session.get('https://api.example.com/data',
457
                                 timeout=aiohttp.ClientTimeout(total=10)) as response:
458
                response.raise_for_status()  # Raise for HTTP errors
459
                return await response.json()
460
    
461
    except aiohttp.ClientTimeout:
462
        print("Request timed out")
463
    except aiohttp.ClientConnectionError:
464
        print("Connection failed")
465
    except aiohttp.ClientResponseError as e:
466
        print(f"HTTP error: {e.status}")
467
    except Exception as e:
468
        print(f"Unexpected error: {e}")
469

470
result = asyncio.run(robust_request())
471
```