Skip to main content

punkreq

punkreq is an async HTTP client for Python, built on top of httpunk.

Warning: punkreq is in an early stage and still work in progress.

Note: punkreq was built with substantial help from LLMs, under human supervision.

In a nutshell

  • Async only, with multiple runtime backends: import the client from the module matching your runtime – punkreq.asyncio or punkreq.tonio
  • HTTP/1.1 and HTTP/2, negotiated via TLS ALPN by default; HTTP/2 prior knowledge with http1=False
  • Connection pooling with keep-alive (h1) and multiplexing (h2)
  • Transparent response decompression: gzip and deflate everywhere, zstd on Python 3.14+, brotli with the punkreq[brotli] extra
  • Conservative automatic retries — only requests the server provably never processed (HTTP/2 graceful GOAWAY, refused streams, keep-alive races)
  • Opt-in cookie jar, basic/bearer auth, multipart uploads
  • HTTP proxies: HTTP_PROXY/HTTPS_PROXY/NO_PROXY environment support, CONNECT tunneling for https destinations.
  • Zero runtime dependencies beyond httpunk

Installation

pip install punkreq

Quickstart

import asyncio
from punkreq.asyncio import Client

async def main():
    async with Client(base_url="https://api.example.com") as client:
        response = await client.post("/items", json={"name": "widget"})
        response.raise_for_status()
        print(await response.json())

asyncio.run(main())

One-off requests without managing a client:

from punkreq import asyncio as punkreq

response = await punkreq.get("https://www.example.com")
print(response.status_code, response.headers["content-type"])

Responses resolve as soon as the head arrives; the body is read on demand — await response.read() / text() / json(), or streamed:

async with Client() as client:
    response = await client.get("https://example.com/large.bin")
    async for chunk in response.iter_bytes(chunk_size=65536):
        ...

Reading to the end releases the connection automatically. When you might stop early, use the request as a context manager so the response is always closed:

async with client.get("https://example.com/huge.ndjson") as response:
    async for line in response.iter_lines():
        if found(line):
            break  # the block exit closes the response and frees the connection

Configuration

import punkreq
from punkreq.asyncio import Client

client = Client(
    base_url="https://api.example.com",
    headers={"x-api-key": "..."},
    auth=("user", "pass"),                       # or punkreq.BearerAuth("token")
    cookies={},                                  # enables the cookie jar (off by default)
    timeout=punkreq.Timeout(5.0, total=30.0),    # no timeouts by default
    limits=punkreq.Limits(max_connections=100),
    proxy="http://proxy.internal:3128",          # env vars honored by default
    verify=True,                                 # bool | CA bundle path | ssl.SSLContext
)

By default: redirects on (max 10), no timeouts, no cookie jar unless requested, HTTP/2 enabled, 90s keep-alive expiry, unlimited connections.

Timeout has four independent fields — total (a deadline for the whole request, redirects included), connect, read and pool. There is no write timeout: request bodies are written full-duplex from background tasks, so total is the bound for slow uploads.

Backends

punkreq never asks for a backend at call sites — pick it by import:

from punkreq.asyncio import Client   # asyncio, available everywhere
from punkreq.tonio import Client     # tonio, free-threaded CPython >= 3.14 on Unix

License

punkreq is released under the BSD License.

Metadata

Release files for punkreq 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for punkreq 0.3.0
File Size Uploaded Provenance Actions
punkreq-0.3.0.tar.gz 66.9 kB With provenance Details for punkreq-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for punkreq 0.3.0
File Interpreter ABI Platform Actions
punkreq-0.3.0-py3-none-any.whl Python 3 none any Details for punkreq-0.3.0-py3-none-any.whl

Total release size: 117.0 kB

Release files / punkreq-0.3.0.tar.gz

Download URL punkreq-0.3.0.tar.gz
Size 66.9 kB
Tags Source
SHA-256 checksum
How to use checksums
79d853c7cacfb2c5b9238ffc602160119173a2995acf86fa67b50a896693388b
BLAKE2b-256 checksum
How to use checksums
6dc2966789fc0d52b649eb43adc3525bb50696ab41a12725bd246bf3afa5e705
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Release files / punkreq-0.3.0-py3-none-any.whl

Download URL punkreq-0.3.0-py3-none-any.whl
Size 50.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1ac4e774132aab367479be59d30210e67b05d62922528525125e1f5ca46995af
BLAKE2b-256 checksum
How to use checksums
0979e407869471a1657e075aad28d23ac4b7973199aab0390653dbd89a60b39a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

Security for punkreq 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for punkreq-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page