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

async def main():
    async with AsyncSession(
        backend="niquests",
        impersonate="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", "chrome149", 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. wreq also accepts its native names (Firefox151, Safari18_5, Edge148, Opera131, OkHttp5, …). curl_cffi accepts firefox, safari, edge, chrome_android, tor, and the library’s versioned profiles.

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: BackendName = "httpx",
    impersonate: ImpersonateName | 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,
)

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