0
# HTTP3
1

2
A next-generation HTTP client for Python 3 with modern features including HTTP/2 and HTTP/1.1 support, async/await capabilities, connection pooling, and a requests-compatible API. HTTP3 enables building robust HTTP client applications with comprehensive timeout control, streaming support, and full type annotations.
3

4
## Package Information
5

6
- **Package Name**: http3
7
- **Language**: Python
8
- **Installation**: `pip install http3`
9
- **Python Requirements**: >=3.6
10

11
## Core Imports
12

13
```python
14
import http3
15
```
16

17
For high-level request functions:
18

19
```python
20
from http3 import get, post, put, patch, delete, head, options, request
21
```
22

23
For client classes:
24

25
```python
26
from http3 import Client, AsyncClient
27
```
28

29
## Basic Usage
30

31
```python
32
import http3
33

34
# Simple synchronous requests
35
response = http3.get('https://www.example.org/')
36
print(response.status_code)  # 200
37
print(response.protocol)     # 'HTTP/2'
38
print(response.text)         # Response content
39

40
# POST with JSON data
41
response = http3.post(
42
    'https://api.example.com/data',
43
    json={'key': 'value'},
44
    headers={'Authorization': 'Bearer token'}
45
)
46

47
# Using a client for session-like behavior
48
with http3.Client() as client:
49
    response = client.get('https://www.example.org/')
50
    response2 = client.post('https://www.example.org/api')
51
```
52

53
Async usage:
54

55
```python
56
import http3
57
import asyncio
58

59
async def main():
60
    async with http3.AsyncClient() as client:
61
        response = await client.get('https://www.example.org/')
62
        print(response.status_code)
63

64
asyncio.run(main())
65
```
66

67
## Architecture
68

69
HTTP3 uses a modular architecture built around these key components:
70

71
- **Clients**: High-level synchronous (Client) and asynchronous (AsyncClient) interfaces
72
- **Dispatchers**: Handle protocol-specific communication (HTTP/1.1, HTTP/2, WSGI, ASGI)
73
- **Connection Pools**: Manage connection reuse and limits for optimal performance
74
- **Models**: Request/Response objects with comprehensive data handling
75
- **Configuration**: Flexible timeout, SSL, and connection pool configuration
76

77
This design enables HTTP3 to provide both simple request functions and sophisticated client capabilities while supporting modern web protocols and async patterns.
78

79
## Capabilities
80

81
### High-Level Request Functions
82

83
Simple functions for making HTTP requests without managing client instances. These provide a requests-compatible API with support for all standard HTTP methods.
84

85
```python { .api }
86
def get(url: URLTypes, *, params: QueryParamTypes = None, headers: HeaderTypes = None, cookies: CookieTypes = None, stream: bool = False, auth: AuthTypes = None, allow_redirects: bool = True, cert: CertTypes = None, verify: VerifyTypes = True, timeout: TimeoutTypes = None) -> Response: ...
87
def post(url: URLTypes, *, data: RequestData = None, files: RequestFiles = None, json: typing.Any = None, params: QueryParamTypes = None, headers: HeaderTypes = None, cookies: CookieTypes = None, stream: bool = False, auth: AuthTypes = None, allow_redirects: bool = True, cert: CertTypes = None, verify: VerifyTypes = True, timeout: TimeoutTypes = None) -> Response: ...
88
def put(url: URLTypes, *, data: RequestData = None, files: RequestFiles = None, json: typing.Any = None, params: QueryParamTypes = None, headers: HeaderTypes = None, cookies: CookieTypes = None, stream: bool = False, auth: AuthTypes = None, allow_redirects: bool = True, cert: CertTypes = None, verify: VerifyTypes = True, timeout: TimeoutTypes = None) -> Response: ...
89
def patch(url: URLTypes, *, data: RequestData = None, files: RequestFiles = None, json: typing.Any = None, params: QueryParamTypes = None, headers: HeaderTypes = None, cookies: CookieTypes = None, stream: bool = False, auth: AuthTypes = None, allow_redirects: bool = True, cert: CertTypes = None, verify: VerifyTypes = True, timeout: TimeoutTypes = None) -> Response: ...
90
def delete(url: URLTypes, *, data: RequestData = None, files: RequestFiles = None, json: typing.Any = None, params: QueryParamTypes = None, headers: HeaderTypes = None, cookies: CookieTypes = None, stream: bool = False, auth: AuthTypes = None, allow_redirects: bool = True, cert: CertTypes = None, verify: VerifyTypes = True, timeout: TimeoutTypes = None) -> Response: ...
91
def head(url: URLTypes, *, params: QueryParamTypes = None, headers: HeaderTypes = None, cookies: CookieTypes = None, stream: bool = False, auth: AuthTypes = None, allow_redirects: bool = False, cert: CertTypes = None, verify: VerifyTypes = True, timeout: TimeoutTypes = None) -> Response: ...
92
def options(url: URLTypes, *, params: QueryParamTypes = None, headers: HeaderTypes = None, cookies: CookieTypes = None, stream: bool = False, auth: AuthTypes = None, allow_redirects: bool = True, cert: CertTypes = None, verify: VerifyTypes = True, timeout: TimeoutTypes = None) -> Response: ...
93
def request(method: str, url: URLTypes, *, params: QueryParamTypes = None, data: RequestData = None, files: RequestFiles = None, json: typing.Any = None, headers: HeaderTypes = None, cookies: CookieTypes = None, auth: AuthTypes = None, timeout: TimeoutTypes = None, allow_redirects: bool = True, cert: CertTypes = None, verify: VerifyTypes = True, stream: bool = False) -> Response: ...
94
```
95

96
[Request Functions](./request-functions.md)
97

98
### Client Classes
99

100
Persistent client instances for session-like behavior, connection pooling, and advanced configuration. Supports both synchronous and asynchronous operations.
101

102
```python { .api }
103
class Client:
104
    def __init__(self, auth: AuthTypes = None, cookies: CookieTypes = None, verify: VerifyTypes = True, cert: CertTypes = None, timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG, pool_limits: PoolLimits = DEFAULT_POOL_LIMITS, max_redirects: int = DEFAULT_MAX_REDIRECTS, base_url: URLTypes = None, dispatch: Dispatcher = None, app: typing.Callable = None, raise_app_exceptions: bool = True, backend: ConcurrencyBackend = None): ...
105
    def request(self, method: str, url: URLTypes, *, data: RequestData = None, files: RequestFiles = None, json: typing.Any = None, params: QueryParamTypes = None, headers: HeaderTypes = None, cookies: CookieTypes = None, stream: bool = False, auth: AuthTypes = None, allow_redirects: bool = True, cert: CertTypes = None, verify: VerifyTypes = None, timeout: TimeoutTypes = None) -> Response: ...
106
    def get(self, url, **kwargs): ...
107
    def post(self, url, **kwargs): ...
108
    # ... other HTTP methods
109
    def close(self): ...
110

111
class AsyncClient:
112
    def __init__(self, auth: AuthTypes = None, cookies: CookieTypes = None, verify: VerifyTypes = True, cert: CertTypes = None, timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG, pool_limits: PoolLimits = DEFAULT_POOL_LIMITS, max_redirects: int = DEFAULT_MAX_REDIRECTS, base_url: URLTypes = None, dispatch: AsyncDispatcher = None, app: typing.Callable = None, raise_app_exceptions: bool = True, backend: ConcurrencyBackend = None): ...
113
    async def request(self, method: str, url: URLTypes, *, data: AsyncRequestData = None, files: RequestFiles = None, json: typing.Any = None, params: QueryParamTypes = None, headers: HeaderTypes = None, cookies: CookieTypes = None, stream: bool = False, auth: AuthTypes = None, allow_redirects: bool = True, cert: CertTypes = None, verify: VerifyTypes = None, timeout: TimeoutTypes = None) -> AsyncResponse: ...
114
    async def get(self, url, **kwargs): ...
115
    async def post(self, url, **kwargs): ...
116
    # ... other HTTP methods
117
    async def close(self): ...
118
```
119

120
[Client Classes](./clients.md)
121

122
### Request and Response Models
123

124
Comprehensive objects for handling HTTP requests and responses with full data access, streaming support, and type safety.
125

126
```python { .api }
127
class Request:
128
    def __init__(self, method, url, *, data=b"", params=None, headers=None): ...
129
    @property
130
    def method(self) -> str: ...
131
    @property
132
    def url(self) -> URL: ...
133
    @property
134
    def headers(self) -> Headers: ...
135

136
class Response:
137
    @property
138
    def status_code(self) -> int: ...
139
    @property
140
    def protocol(self) -> str: ...
141
    @property
142
    def headers(self) -> Headers: ...
143
    @property
144
    def text(self) -> str: ...
145
    @property
146
    def content(self) -> bytes: ...
147
    def json(self) -> typing.Any: ...
148
    def read(self) -> bytes: ...
149
    def stream(self) -> typing.Iterator[bytes]: ...
150

151
class AsyncRequest:
152
    def __init__(self, method, url, *, data=b"", params=None, headers=None): ...
153
    # Similar interface to Request
154

155
class AsyncResponse:
156
    # Async versions of Response methods
157
    async def json(self) -> typing.Any: ...
158
    async def read(self) -> bytes: ...
159
    async def stream(self) -> typing.AsyncIterator[bytes]: ...
160
```
161

162
[Request Response Models](./models.md)
163

164
### Configuration and Settings
165

166
Flexible configuration classes for timeouts, SSL settings, connection pools, and other client behavior customization.
167

168
```python { .api }
169
class TimeoutConfig:
170
    def __init__(self, timeout=None, *, connect_timeout=None, read_timeout=None, write_timeout=None): ...
171

172
class SSLConfig:
173
    def __init__(self, *, cert=None, verify=True): ...
174

175
class PoolLimits:
176
    def __init__(self, *, soft_limit=None, hard_limit=None, pool_timeout=None): ...
177
```
178

179
[Configuration](./configuration.md)
180

181
### Data Models and Utilities
182

183
URL handling, headers management, query parameters, cookies, and other data structures used throughout the HTTP client.
184

185
```python { .api }
186
class URL:
187
    def __init__(self, url, allow_relative=False, params=None): ...
188
    @property
189
    def scheme(self) -> str: ...
190
    @property
191
    def host(self) -> str: ...
192
    @property
193
    def port(self) -> int: ...
194
    @property
195
    def path(self) -> str: ...
196
    @property
197
    def query(self) -> str: ...
198
    def join(self, relative_url) -> "URL": ...
199

200
class Headers:
201
    def __getitem__(self, key: str) -> str: ...
202
    def __setitem__(self, key: str, value: str): ...
203
    def get(self, key: str, default=None): ...
204

205
class QueryParams:
206
    def __init__(self, params=None): ...
207
    # Mapping-like interface
208

209
class Cookies:
210
    def __init__(self, cookies=None): ...
211
    # MutableMapping interface
212
```
213

214
[Data Models](./data-models.md)
215

216
### Exception Handling
217

218
Comprehensive exception hierarchy for handling different types of HTTP errors, timeouts, and connection issues.
219

220
```python { .api }
221
# Timeout exceptions
222
class Timeout(Exception): ...
223
class ConnectTimeout(Timeout): ...
224
class ReadTimeout(Timeout): ...
225
class WriteTimeout(Timeout): ...
226
class PoolTimeout(Timeout): ...
227

228
# HTTP exceptions
229
class ProtocolError(Exception): ...
230
class DecodingError(Exception): ...
231
class InvalidURL(Exception): ...
232

233
# Redirect exceptions
234
class TooManyRedirects(Exception): ...
235
class RedirectBodyUnavailable(Exception): ...
236
class RedirectLoop(Exception): ...
237

238
# Stream exceptions
239
class StreamConsumed(Exception): ...
240
class ResponseNotRead(Exception): ...
241
class ResponseClosed(Exception): ...
242
```
243

244
[Exception Handling](./exceptions.md)
245

246
### Advanced Components
247

248
Low-level components for advanced use cases including custom dispatchers, connection management, and protocol-specific interfaces.
249

250
```python { .api }
251
class HTTPConnection:
252
    def __init__(self, origin: typing.Union[str, Origin], verify: VerifyTypes = True, cert: CertTypes = None, timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG, backend: ConcurrencyBackend = None, release_func: typing.Optional[ReleaseCallback] = None): ...
253
    async def send(self, request: AsyncRequest, verify: VerifyTypes = None, cert: CertTypes = None, timeout: TimeoutTypes = None) -> AsyncResponse: ...
254
    async def connect(self, verify: VerifyTypes = None, cert: CertTypes = None, timeout: TimeoutTypes = None) -> None: ...
255
    async def close(self) -> None: ...
256
    @property
257
    def is_http2(self) -> bool: ...
258

259
class ConnectionPool:
260
    def __init__(self, *, verify: VerifyTypes = True, cert: CertTypes = None, timeout: TimeoutTypes = DEFAULT_TIMEOUT_CONFIG, pool_limits: PoolLimits = DEFAULT_POOL_LIMITS, backend: ConcurrencyBackend = None): ...
261
    async def send(self, request: AsyncRequest, verify: VerifyTypes = None, cert: CertTypes = None, timeout: TimeoutTypes = None) -> AsyncResponse: ...
262
    async def close(self) -> None: ...
263

264
# Interface classes for custom implementations
265
class AsyncDispatcher:
266
    async def send(self, request: AsyncRequest, verify: VerifyTypes = None, cert: CertTypes = None, timeout: TimeoutTypes = None) -> AsyncResponse: ...
267
    async def close(self) -> None: ...
268

269
class Dispatcher:
270
    def send(self, request: Request, verify: VerifyTypes = None, cert: CertTypes = None, timeout: TimeoutTypes = None) -> Response: ...
271
    def close(self) -> None: ...
272

273
class ConcurrencyBackend:
274
    async def connect(self, hostname: str, port: int, ssl_context: typing.Optional[ssl.SSLContext], timeout: TimeoutConfig) -> typing.Tuple[BaseReader, BaseWriter, Protocol]: ...
275
    def get_semaphore(self, limits: PoolLimits) -> BasePoolSemaphore: ...
276

277
class AsyncioBackend(ConcurrencyBackend):
278
    # Default asyncio implementation
279
    pass
280
```
281

282
## Types
283

284
```python { .api }
285
# Type aliases for flexible input handling
286
URLTypes = Union[URL, str]
287
QueryParamTypes = Union[QueryParams, Mapping[str, str], List[Tuple[Any, Any]], str]
288
HeaderTypes = Union[Headers, Dict[AnyStr, AnyStr], List[Tuple[AnyStr, AnyStr]]]
289
CookieTypes = Union[Cookies, CookieJar, Dict[str, str]]
290
AuthTypes = Union[Tuple[Union[str, bytes], Union[str, bytes]], Callable[[AsyncRequest], AsyncRequest]]
291
RequestData = Union[dict, str, bytes, Iterator[bytes]]
292
AsyncRequestData = Union[dict, str, bytes, AsyncIterator[bytes]]
293
RequestFiles = Dict[str, Union[IO[AnyStr], Tuple[str, IO[AnyStr]], Tuple[str, IO[AnyStr], str]]]
294
TimeoutTypes = Union[float, Tuple[float, float, float], TimeoutConfig]
295
CertTypes = Union[str, Tuple[str, str]]
296
VerifyTypes = Union[str, bool]
297

298
# Constants
299
USER_AGENT: str  # Default user agent string
300

301
# Default configuration values
302
DEFAULT_TIMEOUT_CONFIG = TimeoutConfig(timeout=5.0)
303
DEFAULT_POOL_LIMITS = PoolLimits(soft_limit=10, hard_limit=100, pool_timeout=5.0)
304
DEFAULT_MAX_REDIRECTS = 20
305

306
# Status codes enum and utilities
307
class StatusCode(IntEnum):
308
    # HTTP status codes with utility methods
309
    @classmethod
310
    def get_reason_phrase(cls, value: int) -> str: ...
311
    @classmethod
312
    def is_redirect(cls, value: int) -> bool: ...
313
    @classmethod
314
    def is_client_error(cls, value: int) -> bool: ...
315
    @classmethod
316
    def is_server_error(cls, value: int) -> bool: ...
317

318
codes: StatusCode  # Status codes lookup instance
319
```