Niquests is a simple, yet elegant, HTTP library that is a drop-in replacement for Requests, which is under feature freeze.
npx @tessl/cli install tessl/pypi-niquests@3.15.00
# Niquests
1
2
Niquests is a modern, high-performance HTTP client library for Python that serves as a drop-in replacement for the popular Requests library. It offers advanced features including HTTP/2 and HTTP/3 support with multiplexing capabilities, asynchronous and synchronous APIs, DNS over HTTPS/QUIC/TLS, OCSP certificate revocation verification, WebSocket support, and comprehensive network fine-tuning options.
3
4
## Package Information
5
6
- **Package Name**: niquests
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install niquests`
10
11
## Core Imports
12
13
```python
14
import niquests
15
```
16
17
Common usage patterns:
18
19
```python
20
# Synchronous requests
21
from niquests import get, post, Session
22
23
# Asynchronous requests
24
from niquests import aget, apost, AsyncSession
25
26
# Models and exceptions
27
from niquests import Response, Request, RequestException
28
```
29
30
## Basic Usage
31
32
```python
33
import niquests
34
35
# Simple GET request
36
response = niquests.get('https://httpbin.org/get')
37
print(response.status_code)
38
print(response.json())
39
40
# POST request with data
41
data = {'key': 'value'}
42
response = niquests.post('https://httpbin.org/post', json=data)
43
print(response.json())
44
45
# Using sessions for persistent connections
46
with niquests.Session() as session:
47
response = session.get('https://httpbin.org/get')
48
print(response.text)
49
50
# Async requests
51
import asyncio
52
53
async def fetch_data():
54
response = await niquests.aget('https://httpbin.org/get')
55
return response.json()
56
57
# Run async function
58
data = asyncio.run(fetch_data())
59
```
60
61
## Architecture
62
63
Niquests maintains compatibility with the Requests API while providing significant performance improvements through:
64
65
- **HTTP/2 and HTTP/3 Support**: Modern protocol implementations with multiplexing
66
- **Dual API Design**: Both synchronous and asynchronous interfaces
67
- **Connection Pooling**: Automatic connection reuse and management
68
- **Advanced Security**: OCSP verification, post-quantum cryptography, DNS over secure channels
69
- **Drop-in Compatibility**: Full API compatibility with existing Requests code
70
71
The library is built on top of urllib3 with extensive enhancements for modern networking requirements.
72
73
## Capabilities
74
75
### Synchronous HTTP Requests
76
77
Core HTTP methods for making synchronous requests including GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. These functions provide a simple interface for HTTP communication without requiring explicit session management.
78
79
```python { .api }
80
def request(method: HttpMethodType, url: str, *,
81
params: QueryParameterType | None = None,
82
data: BodyType | None = None,
83
json: Any | None = None,
84
headers: HeadersType | None = None,
85
cookies: CookiesType | None = None,
86
files: MultiPartFilesType | MultiPartFilesAltType | None = None,
87
auth: HttpAuthenticationType | None = None,
88
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
89
allow_redirects: bool = True,
90
proxies: ProxyType | None = None,
91
verify: TLSVerifyType = True,
92
stream: bool = False,
93
cert: TLSClientCertType | None = None,
94
hooks: HookType[PreparedRequest | Response] | None = None,
95
retries: RetryType = DEFAULT_RETRIES) -> Response: ...
96
97
def get(url: str, params: QueryParameterType | None = None, *,
98
headers: HeadersType | None = None,
99
cookies: CookiesType | None = None,
100
auth: HttpAuthenticationType | None = None,
101
timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
102
allow_redirects: bool = True,
103
proxies: ProxyType | None = None,
104
verify: TLSVerifyType = True,
105
stream: bool = False,
106
cert: TLSClientCertType | None = None,
107
hooks: HookType[PreparedRequest | Response] | None = None,
108
retries: RetryType = DEFAULT_RETRIES,
109
**kwargs: Any) -> Response: ...
110
111
def post(url: str, data: BodyType | None = None, json: Any | None = None, *,
112
params: QueryParameterType | None = None,
113
headers: HeadersType | None = None,
114
cookies: CookiesType | None = None,
115
files: MultiPartFilesType | MultiPartFilesAltType | None = None,
116
auth: HttpAuthenticationType | None = None,
117
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
118
allow_redirects: bool = True,
119
proxies: ProxyType | None = None,
120
verify: TLSVerifyType = True,
121
stream: bool = False,
122
cert: TLSClientCertType | None = None,
123
hooks: HookType[PreparedRequest | Response] | None = None,
124
retries: RetryType = DEFAULT_RETRIES) -> Response: ...
125
126
def put(url: str, data: BodyType | None = None, *,
127
json: Any | None = None,
128
params: QueryParameterType | None = None,
129
headers: HeadersType | None = None,
130
cookies: CookiesType | None = None,
131
files: MultiPartFilesType | MultiPartFilesAltType | None = None,
132
auth: HttpAuthenticationType | None = None,
133
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
134
allow_redirects: bool = True,
135
proxies: ProxyType | None = None,
136
verify: TLSVerifyType = True,
137
stream: bool = False,
138
cert: TLSClientCertType | None = None,
139
hooks: HookType[PreparedRequest | Response] | None = None,
140
retries: RetryType = DEFAULT_RETRIES) -> Response: ...
141
142
def patch(url: str, data: BodyType | None = None, *,
143
json: Any | None = None,
144
params: QueryParameterType | None = None,
145
headers: HeadersType | None = None,
146
cookies: CookiesType | None = None,
147
files: MultiPartFilesType | MultiPartFilesAltType | None = None,
148
auth: HttpAuthenticationType | None = None,
149
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
150
allow_redirects: bool = True,
151
proxies: ProxyType | None = None,
152
verify: TLSVerifyType = True,
153
stream: bool = False,
154
cert: TLSClientCertType | None = None,
155
hooks: HookType[PreparedRequest | Response] | None = None,
156
retries: RetryType = DEFAULT_RETRIES) -> Response: ...
157
158
def delete(url: str, *,
159
params: QueryParameterType | None = None,
160
headers: HeadersType | None = None,
161
cookies: CookiesType | None = None,
162
auth: HttpAuthenticationType | None = None,
163
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
164
allow_redirects: bool = True,
165
proxies: ProxyType | None = None,
166
verify: TLSVerifyType = True,
167
stream: bool = False,
168
cert: TLSClientCertType | None = None,
169
hooks: HookType[PreparedRequest | Response] | None = None,
170
retries: RetryType = DEFAULT_RETRIES,
171
**kwargs: Any) -> Response: ...
172
173
def head(url: str, *,
174
params: QueryParameterType | None = None,
175
headers: HeadersType | None = None,
176
cookies: CookiesType | None = None,
177
auth: HttpAuthenticationType | None = None,
178
timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
179
allow_redirects: bool = False,
180
proxies: ProxyType | None = None,
181
verify: TLSVerifyType = True,
182
stream: bool = False,
183
cert: TLSClientCertType | None = None,
184
hooks: HookType[PreparedRequest | Response] | None = None,
185
retries: RetryType = DEFAULT_RETRIES,
186
**kwargs: Any) -> Response: ...
187
188
def options(url: str, *,
189
params: QueryParameterType | None = None,
190
headers: HeadersType | None = None,
191
cookies: CookiesType | None = None,
192
auth: HttpAuthenticationType | None = None,
193
timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
194
allow_redirects: bool = True,
195
proxies: ProxyType | None = None,
196
verify: TLSVerifyType = True,
197
stream: bool = False,
198
cert: TLSClientCertType | None = None,
199
hooks: HookType[PreparedRequest | Response] | None = None,
200
retries: RetryType = DEFAULT_RETRIES,
201
**kwargs: Any) -> Response: ...
202
```
203
204
[Synchronous Requests](./sync-requests.md)
205
206
### Asynchronous HTTP Requests
207
208
Async versions of all HTTP methods for high-performance concurrent request handling. These functions enable non-blocking HTTP operations and are ideal for applications requiring high throughput. Return type depends on stream parameter.
209
210
```python { .api }
211
async def arequest(method: HttpMethodType, url: str, *,
212
params: QueryParameterType | None = None,
213
data: BodyType | AsyncBodyType | None = None,
214
headers: HeadersType | None = None,
215
cookies: CookiesType | None = None,
216
files: MultiPartFilesType | MultiPartFilesAltType | None = None,
217
auth: HttpAuthenticationType | AsyncHttpAuthenticationType | None = None,
218
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
219
allow_redirects: bool = True,
220
proxies: ProxyType | None = None,
221
hooks: AsyncHookType[PreparedRequest | Response] | None = None,
222
stream: bool | None = None,
223
verify: TLSVerifyType | None = None,
224
cert: TLSClientCertType | None = None,
225
json: Any | None = None,
226
retries: RetryType = DEFAULT_RETRIES) -> Response | AsyncResponse: ...
227
228
async def aget(url: str, params: QueryParameterType | None = None, *,
229
headers: HeadersType | None = None,
230
cookies: CookiesType | None = None,
231
auth: HttpAuthenticationType | AsyncHttpAuthenticationType | None = None,
232
timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
233
allow_redirects: bool = True,
234
proxies: ProxyType | None = None,
235
hooks: AsyncHookType[PreparedRequest | Response] | None = None,
236
verify: TLSVerifyType | None = None,
237
stream: bool | None = None,
238
cert: TLSClientCertType | None = None,
239
retries: RetryType = DEFAULT_RETRIES,
240
**kwargs: Any) -> Response | AsyncResponse: ...
241
242
async def apost(url: str, data: BodyType | AsyncBodyType | None = None, json: Any | None = None, *,
243
params: QueryParameterType | None = None,
244
headers: HeadersType | None = None,
245
cookies: CookiesType | None = None,
246
files: MultiPartFilesType | MultiPartFilesAltType | None = None,
247
auth: HttpAuthenticationType | AsyncHttpAuthenticationType | None = None,
248
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
249
allow_redirects: bool = True,
250
proxies: ProxyType | None = None,
251
hooks: AsyncHookType[PreparedRequest | Response] | None = None,
252
verify: TLSVerifyType | None = None,
253
stream: bool | None = None,
254
cert: TLSClientCertType | None = None,
255
retries: RetryType = DEFAULT_RETRIES) -> Response | AsyncResponse: ...
256
257
async def aput(url: str, data: BodyType | AsyncBodyType | None = None, *,
258
json: Any | None = None,
259
params: QueryParameterType | None = None,
260
headers: HeadersType | None = None,
261
cookies: CookiesType | None = None,
262
files: MultiPartFilesType | MultiPartFilesAltType | None = None,
263
auth: HttpAuthenticationType | AsyncHttpAuthenticationType | None = None,
264
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
265
allow_redirects: bool = True,
266
proxies: ProxyType | None = None,
267
hooks: AsyncHookType[PreparedRequest | Response] | None = None,
268
verify: TLSVerifyType | None = None,
269
stream: bool | None = None,
270
cert: TLSClientCertType | None = None,
271
retries: RetryType = DEFAULT_RETRIES) -> Response | AsyncResponse: ...
272
273
async def apatch(url: str, data: BodyType | AsyncBodyType | None = None, *,
274
json: Any | None = None,
275
params: QueryParameterType | None = None,
276
headers: HeadersType | None = None,
277
cookies: CookiesType | None = None,
278
files: MultiPartFilesType | MultiPartFilesAltType | None = None,
279
auth: HttpAuthenticationType | AsyncHttpAuthenticationType | None = None,
280
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
281
allow_redirects: bool = True,
282
proxies: ProxyType | None = None,
283
hooks: AsyncHookType[PreparedRequest | Response] | None = None,
284
verify: TLSVerifyType | None = None,
285
stream: bool | None = None,
286
cert: TLSClientCertType | None = None,
287
retries: RetryType = DEFAULT_RETRIES) -> Response | AsyncResponse: ...
288
289
async def adelete(url: str, *,
290
params: QueryParameterType | None = None,
291
headers: HeadersType | None = None,
292
cookies: CookiesType | None = None,
293
auth: HttpAuthenticationType | AsyncHttpAuthenticationType | None = None,
294
timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
295
allow_redirects: bool = True,
296
proxies: ProxyType | None = None,
297
hooks: AsyncHookType[PreparedRequest | Response] | None = None,
298
verify: TLSVerifyType | None = None,
299
stream: bool | None = None,
300
cert: TLSClientCertType | None = None,
301
retries: RetryType = DEFAULT_RETRIES,
302
**kwargs: Any) -> Response | AsyncResponse: ...
303
304
async def ahead(url: str, *,
305
params: QueryParameterType | None = None,
306
headers: HeadersType | None = None,
307
cookies: CookiesType | None = None,
308
auth: HttpAuthenticationType | AsyncHttpAuthenticationType | None = None,
309
timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
310
allow_redirects: bool = False,
311
proxies: ProxyType | None = None,
312
hooks: AsyncHookType[PreparedRequest | Response] | None = None,
313
verify: TLSVerifyType | None = None,
314
stream: bool | None = None,
315
cert: TLSClientCertType | None = None,
316
retries: RetryType = DEFAULT_RETRIES,
317
**kwargs: Any) -> Response | AsyncResponse: ...
318
319
async def aoptions(url: str, *,
320
params: QueryParameterType | None = None,
321
headers: HeadersType | None = None,
322
cookies: CookiesType | None = None,
323
auth: HttpAuthenticationType | AsyncHttpAuthenticationType | None = None,
324
timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
325
allow_redirects: bool = True,
326
proxies: ProxyType | None = None,
327
hooks: AsyncHookType[PreparedRequest | Response] | None = None,
328
verify: TLSVerifyType | None = None,
329
stream: bool | None = None,
330
cert: TLSClientCertType | None = None,
331
retries: RetryType = DEFAULT_RETRIES,
332
**kwargs: Any) -> Response | AsyncResponse: ...
333
```
334
335
[Asynchronous Requests](./async-requests.md)
336
337
### Session Management
338
339
Session classes for managing persistent connections, cookies, authentication, and other settings across multiple requests. Sessions provide connection pooling and configuration management.
340
341
```python { .api }
342
class Session:
343
def request(self, method: HttpMethodType, url: str, **kwargs) -> Response: ...
344
def get(self, url: str, **kwargs) -> Response: ...
345
def post(self, url: str, **kwargs) -> Response: ...
346
347
class AsyncSession:
348
async def request(self, method: HttpMethodType, url: str, **kwargs) -> AsyncResponse: ...
349
async def get(self, url: str, **kwargs) -> AsyncResponse: ...
350
async def post(self, url: str, **kwargs) -> AsyncResponse: ...
351
```
352
353
[Session Management](./sessions.md)
354
355
### Request and Response Models
356
357
Core data structures for representing HTTP requests and responses. These classes provide access to all HTTP components including headers, body content, status codes, and metadata.
358
359
```python { .api }
360
class Request:
361
def __init__(self, method: HttpMethodType, url: str, **kwargs): ...
362
363
class PreparedRequest:
364
method: HttpMethodType
365
url: str
366
headers: HeadersType
367
368
class Response:
369
status_code: int
370
headers: HeadersType
371
content: bytes
372
def json(self) -> Any: ...
373
374
class AsyncResponse:
375
status_code: int
376
headers: HeadersType
377
content: bytes
378
async def json(self) -> Any: ...
379
```
380
381
[Request and Response Models](./models.md)
382
383
### Exception Handling
384
385
Comprehensive exception hierarchy for handling various error conditions during HTTP operations. These exceptions provide detailed error information and enable robust error handling.
386
387
```python { .api }
388
class RequestException(IOError): ...
389
class HTTPError(RequestException): ...
390
class ConnectionError(RequestException): ...
391
class Timeout(RequestException): ...
392
class JSONDecodeError(RequestException): ...
393
```
394
395
[Exception Handling](./exceptions.md)
396
397
### Advanced Features
398
399
Configuration classes, status code utilities, and advanced networking options for fine-tuning HTTP behavior and handling complex scenarios.
400
401
```python { .api }
402
class TimeoutConfiguration: ...
403
class RetryConfiguration: ...
404
405
# Status codes lookup
406
codes: LookupDict
407
408
# Legacy compatibility flag
409
HAS_LEGACY_URLLIB3: bool
410
```
411
412
[Advanced Features](./advanced-features.md)
413
414
### Utilities
415
416
Utility functions for HTTP handling, URL processing, authentication, and data conversion.
417
418
```python { .api }
419
def super_len(o: Any) -> int: ...
420
def get_netrc_auth(url: str | None, raise_errors: bool = False) -> tuple[str, str] | None: ...
421
def guess_filename(obj: IO) -> str | None: ...
422
def from_key_val_list(value: Any | None) -> OrderedDict | None: ...
423
def to_key_val_list(value: list | dict | OrderedDict | None) -> list[tuple[str, str]] | None: ...
424
def parse_list_header(value: str) -> list[str]: ...
425
def parse_dict_header(value: str) -> Mapping[str, str | None]: ...
426
def unquote_header_value(value: str, is_filename: bool = False) -> str: ...
427
def dict_from_cookiejar(cj: CookieJar) -> dict[str, str | None]: ...
428
def add_dict_to_cookiejar(cj: RequestsCookieJar, cookie_dict) -> RequestsCookieJar | CookieJar: ...
429
def get_encoding_from_headers(headers: Mapping[str, str]) -> str | None: ...
430
def stream_decode_response_unicode(iterator: Iterator[bytes], encoding: str) -> Iterator[str]: ...
431
def iter_slices(string: str, slice_length: int | None) -> Generator[str, None, None]: ...
432
def unquote_unreserved(uri: str) -> str: ...
433
def requote_uri(uri: str) -> str: ...
434
def address_in_network(ip: str, net: str) -> bool: ...
435
def dotted_netmask(mask: int) -> str: ...
436
437
# Utils module reference
438
utils: ModuleType
439
```
440
441
## Package Metadata
442
443
```python { .api }
444
__version__: str
445
__title__: str
446
__description__: str
447
__url__: str
448
__author__: str
449
__author_email__: str
450
__license__: str
451
__copyright__: str
452
__build__: str
453
__cake__: str
454
```
455
456
## Type Definitions
457
458
```python { .api }
459
# Import statements
460
from typing import (
461
Any, Union, List, Tuple, Dict, Mapping, MutableMapping,
462
Optional, Callable, Awaitable, Iterable, AsyncIterable,
463
IO, Iterator, Generator, TypeVar
464
)
465
from http.cookiejar import CookieJar
466
from os import PathLike
467
from collections import OrderedDict
468
from types import ModuleType
469
470
# Type variables
471
_T = TypeVar('_T')
472
473
# Basic type aliases
474
HttpMethodType = str
475
476
# Query parameters and headers
477
QueryParameterType = Union[
478
List[Tuple[str, Union[str, List[str], None]]],
479
Mapping[str, Union[str, List[str], None]],
480
bytes,
481
str,
482
]
483
484
HeadersType = Union[
485
MutableMapping[Union[str, bytes], Union[str, bytes]],
486
MutableMapping[str, str],
487
MutableMapping[bytes, bytes],
488
CaseInsensitiveDict,
489
List[Tuple[Union[str, bytes], Union[str, bytes]]],
490
Headers,
491
]
492
493
# Request body types
494
BodyFormType = Union[
495
List[Tuple[str, str]],
496
Dict[str, Union[List[str], str]],
497
]
498
499
BodyType = Union[
500
str,
501
bytes,
502
bytearray,
503
IO,
504
BodyFormType,
505
Iterable[bytes],
506
Iterable[str],
507
]
508
509
AsyncBodyType = Union[
510
AsyncIterable[bytes],
511
AsyncIterable[str],
512
]
513
514
# Cookies and authentication
515
CookiesType = Union[
516
MutableMapping[str, str],
517
CookieJar,
518
]
519
520
HttpAuthenticationType = Union[
521
Tuple[Union[str, bytes], Union[str, bytes]],
522
str,
523
AuthBase,
524
Callable[[PreparedRequest], PreparedRequest],
525
]
526
527
AsyncHttpAuthenticationType = Union[
528
AsyncAuthBase,
529
Callable[[PreparedRequest], Awaitable[PreparedRequest]],
530
]
531
532
# TLS and security
533
TLSVerifyType = Union[bool, str, bytes, PathLike]
534
TLSClientCertType = Union[str, Tuple[str, str], Tuple[str, str, str]]
535
536
# Timeouts and retries
537
TimeoutType = Union[
538
int,
539
float,
540
Tuple[Union[int, float], Union[int, float]],
541
Tuple[Union[int, float], Union[int, float], Union[int, float]],
542
Timeout,
543
]
544
545
RetryType = Union[bool, int, Retry]
546
547
# Proxies and networking
548
ProxyType = Dict[str, str]
549
550
# File uploads
551
BodyFileType = Union[str, bytes, bytearray, IO]
552
553
MultiPartFileType = Tuple[
554
str,
555
Union[
556
BodyFileType,
557
Tuple[str, BodyFileType],
558
Tuple[str, BodyFileType, str],
559
Tuple[str, BodyFileType, str, HeadersType],
560
],
561
]
562
563
MultiPartFilesType = List[MultiPartFileType]
564
565
MultiPartFilesAltType = Dict[
566
str,
567
Union[
568
BodyFileType,
569
Tuple[str, BodyFileType],
570
Tuple[str, BodyFileType, str],
571
Tuple[str, BodyFileType, str, HeadersType],
572
],
573
]
574
575
# Hooks and callbacks
576
HookCallableType = Callable[[_T], Optional[_T]]
577
HookType = Dict[str, List[HookCallableType[_T]]]
578
579
AsyncHookCallableType = Callable[[_T], Awaitable[Optional[_T]]]
580
AsyncHookType = Dict[str, List[Union[HookCallableType[_T], AsyncHookCallableType[_T]]]]
581
582
# Cache and connection management
583
CacheLayerAltSvcType = MutableMapping[Tuple[str, int], Optional[Tuple[str, int]]]
584
585
# Resolver types for DNS
586
ResolverType = Union[
587
str,
588
ResolverDescription,
589
BaseResolver,
590
List[str],
591
List[ResolverDescription],
592
]
593
594
AsyncResolverType = Union[
595
str,
596
AsyncResolverDescription,
597
AsyncBaseResolver,
598
List[str],
599
List[AsyncResolverDescription],
600
]
601
602
# Default timeout constants
603
READ_DEFAULT_TIMEOUT: TimeoutType
604
WRITE_DEFAULT_TIMEOUT: TimeoutType
605
DEFAULT_RETRIES: RetryType
606
607
# Additional exported classes and utilities
608
class CaseInsensitiveDict: ...
609
class Headers: ...
610
class AuthBase: ...
611
class AsyncAuthBase: ...
612
class Retry: ...
613
class Timeout: ...
614
class LookupDict: ...
615
class ResolverDescription: ...
616
class AsyncResolverDescription: ...
617
class BaseResolver: ...
618
class AsyncBaseResolver: ...
619
class RequestsCookieJar(CookieJar): ...
620
```