or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

tessl/pypi-niquests

Niquests is a simple, yet elegant, HTTP library that is a drop-in replacement for Requests, which is under feature freeze.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/niquests@3.15.x

To install, run

npx @tessl/cli install tessl/pypi-niquests@3.15.0

0

# 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

```