pyhaul is a lightweight Python library that provides safe, resumable HTTP downloads around all popular Python HTTP libraries. Pure Python, zero required dependencies, provides automatic byte-ranged request negotiation, crash-safe atomic file handling, plus it handles all the weird HTTP protocol edge cases correctly so you never end up with a partial or corrupt file on disk. Full documentation

How pyhaul works:

• Bring your own session (requests, httpx, aiohttp, urllib3, and niquests fully supported today in both sync and true async modes).
• pyhaul borrows your existing HTTP session and handles byte-range negotiation, crash-safe checkpointing, and validation. One call to haul() = one request. It either succeeds, or it saves progress so the next call resumes.
• The destination file will not exist until download is complete. Incomplete data lives in a .part file; on completion it is atomically moved into place.
• Interrupted downloads resume when possible. Kill the process, lose the network — the next haul() picks up from the last durable byte.
• If the remote resource changes, a retry will not corrupt. ETag-based validation detects changes between attempts.
• Your HTTP client is borrowed, not owned. pyhaul never creates, configures, or closes sessions.
• Transport errors pass through unwrapped. httpx.ReadTimeout stays httpx.ReadTimeout, so you should be able to drop it into your existing codebase.

How to use pyhaul

pyhaul has zero required dependencies. Pick an HTTP client extra that matches what you already use:

pip install pyhaul[httpx] # or requests, or aiohttp, or urllib3, or niquests

The entire API surface fits in one function: haul() (or haul_async() for async code). Pass a URL, your HTTP client, and a destination path:

import httpx
from pyhaul import haul

with httpx.Client() as client:
    result = haul("https://example.com/big.zip", client, dest="big.zip")
    print(f"done: sha256={result.sha256[:16]}…")

haul() either returns a CompleteHaul (which means full file was downloaded and is present on disk at dest), or it throws either a PartialHaulError (an error the library knows is retryable, with a nested native error inside it) or some other kind of (probably non-retryable) error.

What happens on interruption

If the download is interrupted — network drop, process kill, Ctrl-C — two sidecar files remain on disk:

• big.zip.part — the bytes downloaded so far
• big.zip.part.ctrl — a binary checkpoint with the cursor position, ETag, and block-level hashes

The destination file (big.zip) does not exist at this point. There is no state where a partially-written file sits at the final path.

Resume

To resume, call haul() again with the same arguments. pyhaul reads the checkpoint and negotiates an HTTP Range request for the tail of the object. When the checkpoint holds a strong ETag, pyhaul also sends If-Range with that validator as well (we differentiate between weak or missing validators exactly the way the HTTP spec requires). Assuming validation doesn't fail, pyhaul then appends from where it left off:

# Just call haul() again — it resumes automatically
result = haul("https://example.com/big.zip", client, dest="big.zip")

If the remote file changed between attempts, pyhaul detects the ETag mismatch and restarts from byte 0 — no silent corruption.

Add retry logic

One haul() = one HTTP request. When the stream ends early, pyhaul raises PartialHaulError and saves progress. Bring your own retry logic, async processing loops, rate limiting, etc. You can add tenacity around it like you would your own stuff.

import time
from pyhaul import haul, PartialHaulError, HaulState

state = HaulState()

with httpx.Client() as client:
    for attempt in range(1, 11):
        try:
            result = haul(
                "https://example.com/big.zip",
                client,
                dest="big.zip",
                state=state,
            )
            print(f"done: {state.valid_length:,} bytes")
            break
        except PartialHaulError as exc:
            print(f"attempt {attempt}: {exc.reason} "
                  f"({state.valid_length:,} bytes so far)")
            time.sleep(min(2**attempt, 30))

HaulState is an optional mutable bag updated in-place throughout the download — useful for progress reporting, paint a TUI or GUI, or deciding whether to adapt retry.

Track progress

Pass optional on_progress function to get called after each chunk lands on disk:

def show_progress(state: HaulState) -> None:
    if state.reported_length:
        pct = state.valid_length / state.reported_length * 100
        print(f"\r{pct:.1f}%", end="", flush=True)

result = haul(url, client, dest="big.zip", state=state, on_progress=show_progress)