niquests Documentation

Niquests supports WASI (WebAssembly System Interface) by performing capability discovery from wit_world bindings. It automatically selects the appropriate transport based on the available interfaces:

• Synchronous Session: Prefers Preview 2 sockets. Can fallback to wasi:http@0.2.0 if sockets are absent.
• Asynchronous AsyncSession: Prefers Preview 3 sockets. Can fallback to wasi:http@0.3.0 if sockets are absent.

Socket WIT (Native Networking)

Provides full control over the transport (pooling, TLS, DNS) inside the guest. Requires urllib3.future >= 2.24.900 and niquests[rtls] for HTTPS.

• Wasmtime Grant: -Sinherit-network -Sallow-ip-name-lookup=y (and -Sp3 for Preview 3).

WIT HTTP (High-level Capability)

Submits requests to the host. The host manages DNS, TCP, and TLS. This is a smaller authority surface suitable for untrusted plugins.

• Wasmtime Grant: -Shttp (and -Sp3 for Preview 3). No socket permissions required.
• Limitations: Custom CA bundles, verify=False, custom DNS, and SOCKS proxies are unavailable because the host controls the TLS/TCP layer.

A Session (or AsyncSession) object allows you to persist parameters, authentication, and cookies across multiple requests. It also enables connection pooling via urllib3.future, which improves performance by reusing underlying TCP connections to the same host.

Cookie Persistence

Cookies received during a request in a session are automatically stored and sent in subsequent requests made with that same session instance.

Default Parameters

You can set default values for headers, authentication, and other parameters on the session object. These will be applied to every request made by that session. If a request method provides its own value for a parameter, it will override the session-level default.

Merging and Overriding

• Merging: Dictionaries passed to request methods (like headers or cookies) are merged with session-level values.
• Overriding: Method-level parameters override session parameters.
• Omission: To omit a specific key that exists at the session level from a single request, set its value to None in the method-level parameter.
• Non-persistence: Parameters passed directly to a request method (e.g., s.get(..., cookies={...})) are not persisted to the session for future requests.

# Sync example
s = niquests.Session()
s.auth = ('user', 'pass')
s.headers.update({'x-test': 'true'})

# 'x-test' (from session) and 'x-test2' (from method) are both sent
s.get('https://httpbin.org/headers', headers={'x-test2': 'true'})

When running under Pyodide, the browser's network stack handles connections, which imposes several limitations due to the browser sandbox:

• DNS: Handled by the browser. Custom resolvers, DNS-over-HTTPS, and Protocol toggles are ignored.
• TLS: Handled by the browser. verify and cert parameters are ignored; the browser uses its own certificate store. response.conn_info is unset.
• CORS: Applies. The remote server must include appropriate Access-Control-Allow-Origin headers.
• HTTP Version: response.http_version is None as the browser does not easily expose the negotiated protocol.
• Forbidden Headers: The browser forbids overriding headers like Host, Origin, Cookie, and Connection.
• Sockets: No HTTP+Unix sockets available.
• Connection Management: Pool sizing, HTTP version toggles, and multiplexing settings are ignored; the browser manages the pool.
• Redirection: No redirection history is accessible; disable autoredirect is not supported.
• Proxies: Not allowed/accessible via WASM/JS.
• Hooks & Extras: pre_send and early_response hooks are ignored. Extras like socks, ocsp, speedups, and zstd are not used.

When enabling multiplexed=True in an AsyncSession, you must call await s.gather() to avoid blocking the event loop and to ensure responses are fully processed before accessing them.

Warning: Accessing non-awaitable attributes or methods of a lazy AsyncResponse without first calling s.gather() will raise an error.

import niquests
import asyncio

async def main() -> None:
    responses = []

    async with niquests.AsyncSession(multiplexed=True) as s:
        responses.append(
            await s.get("https://httpbingo.org/get", stream=True)
        )
        responses.append(
            await s.get("https://httpbingo.org/get", stream=True)
        )

        print(responses)

        await s.gather()

        print(responses)

        for response in responses:
            async for chunk in await response.iter_content(16):
                print(chunk)

if __name__ == "__main__":
    asyncio.run(main())

Niquests supports class-based hooks via LifeCycleHook (synchronous) and AsyncLifeCycleHook (asynchronous). Unlike dictionary-based hooks, these allow for persistent state, better organization, and easier typing. You can implement specific lifecycle events by overriding methods such as pre_request, pre_send, on_upload, early_response, or response.

Warning: In synchronous multi-threaded mode, you are responsible for ensuring thread safety (e.g., via locking) if your LifeCycleHook shares state between threads.

import asyncio
from niquests import AsyncSession, AsyncLifeCycleHook

class ConnectionLogger(AsyncLifeCycleHook):
    async def pre_send(self, prepared_request, **kwargs) -> None:
        # Inspect the connection info before the request is sent
        print(f"Connected to: {prepared_request.conn_info}")

async def main():
    async with AsyncSession() as s:
        # Pass an instance of your hook class
        await s.get("https://one.one.one.one", hooks=ConnectionLogger())

if __name__ == "__main__":
    asyncio.run(main())