tlsreq

English | 简体中文

A single Session / AsyncSession API over four TLS-capable HTTP stacks:

curl_cffi · wreq · niquests + xutls · httpx + xutls

Change backend and impersonate. Request code stays the same.

Install

pip install tlsreq                 # httpx + h2 + brotli + zstd + xutls
pip install "tlsreq[niquests]"     # or wreq / curl_cffi / all

pip install tlsreq pulls the default httpx stack: HTTP/2 (h2), br/zstd body decoding, and Chrome 152 TLS via xutls.

xutls import name is still utls. Do not also install the upstream utls package — both provide the utls module. To upgrade later: pip install -U xutls.

Quick start

import asyncio
from tlsreq import AsyncSession, Session, niquests, wreq

async def main():
    async with AsyncSession(
        backend=niquests,
        impersonate=niquests.chrome152,
        proxy="http://user:pass@host:port",
        timeout=30,
        extra={"pool_maxsize": 1},
    ) as s:
        r = await s.get("https://tls.peet.ws/api/all")
        print(r.status_code, r.http_version, r.cookies)
        print(r.json()["tls"]["ja4"])

        r = await s.post(
            "https://example.com/login",
            data=b"user=a&pass=b",
            headers={"content-type": "application/x-www-form-urlencoded"},
            header_order=["user-agent", "accept", "content-type"],
        )
        print(r.status_code, r.text)

asyncio.run(main())

with Session(wreq, wreq.chrome154, proxy="http://127.0.0.1:7890") as s:
    r = s.get("https://example.com")
    print(r.status_code, r.headers)

The native client is on session.raw when you need a backend-specific knob.

Backends

Unknown backend or impersonate values raise. There is no silent fallback to another profile.

chrome / chromestable map to that backend’s current default. Fingerprints are attributes on the library object, so the editor lists only that library: Session(wreq, wreq.chrome154), Session(httpx, httpx.chrome152), Session(curl_cffi, curl_cffi.chrome150). wreq includes chrome154, firefox152, safari26_4, edge148, opera131, and okhttp5. httpx and niquests, along with nirequest, nirequests, and nio, have the eight xutls presets (chrome131, chrome142, chrome146, chrome148, chrome150, chrome152, chrome, chromestable). curl, cffi, and curl_cffi share the curl_cffi list. Session(wreq, "chrome154") and Session("wreq", "chrome154") still run. A quoted fingerprint string does not offer that list. Session(impersonate=...) defaults to httpx.

httpx / niquests offer both HTTP/2 and HTTP/1.1. The protocol is chosen from the negotiated TLS ALPN (h2 vs http/1.1); an HTTP/1.1-only origin falls back instead of failing.

Chrome 152 (niquests / httpx)

These two backends apply Chrome 152 HTTP/2 framing on top of xutls ClientHello impersonation:

Checked against tls.peet.ws.

curl_cffi and wreq use their own stacks; they do not take this HTTP/2 patch.

API

Session / AsyncSession

Session(
    backend: Backend[Imp] | str = httpx,
    impersonate: Imp | None = None,
    *,
    proxy: str | None = None,
    timeout: float = 30,
    verify: bool = True,
    headers: Mapping[str, str] | None = None,
    cookies: Mapping[str, str] | None = None,
    allow_redirects: bool = True,
    extra: dict[str, Any] | None = None,
)

httpx, niquests, wreq, and curl_cffi are Backend objects exported by tlsreq. Import the one you pass in, then pass one of its fingerprint attributes: Session(wreq, wreq.chrome154). AsyncSession has the same signature.

Context-manager safe. AsyncSession methods are coroutines.

Requests

get / post / put / patch / delete / head / options all call request.

extra on the session is merged into the underlying constructor; extra on a request is merged into that call. Later keys win.

Response

Body is fully read when the response is wrapped. .text and .json() are synchronous on both Session types.

session.cookies is the cookie jar as a dict. session.set_cookies(dict, url=None) writes into it.

License

MIT