bytehaul

Python bindings for the bytehaul Rust download library.

中文使用文档

Requirements

  • Python 3.9+
  • Rust toolchain (for building from source)
  • uv

Commands below assume you are running them from the repository root.

Installation

From source (development)

uv sync --project bindings/python
cd bindings/python
uv run --project . maturin develop -m Cargo.toml

Build wheel

cd bindings/python
uv run --project . maturin build --release -m Cargo.toml

Usage

Simple download

import bytehaul

bytehaul.download("https://example.com/file.bin", output_path="output.bin")

# Let bytehaul decide the filename and place it in downloads/
bytehaul.download("https://example.com/file.bin", output_dir="downloads")

With options

bytehaul.download(
    "https://example.com/file.bin",
    output_path="output.bin",
    max_connections=8,
    max_download_speed=1_000_000,  # 1 MB/s
    headers={"Authorization": "Bearer token"},
)

Network settings

bytehaul.download(
    "https://example.com/file.bin",
    output_path="output.bin",
    proxy="http://127.0.0.1:7890",
    dns_servers=["1.1.1.1", "8.8.8.8:53"],
    doh_servers=["https://dns.google/dns-query"],
    enable_ipv6=False,
)

doh_servers expects HTTPS URLs. If you pass a hostname such as dns.google, bytehaul will use the system resolver once during client construction to bootstrap the DoH endpoint addresses.

Logging

# Enable debug logging on the convenience function
bytehaul.download(
    "https://example.com/file.bin",
    output_path="output.bin",
    log_level="debug",
)

# Or on the Downloader object
from bytehaul import Downloader

downloader = Downloader(log_level="info")

Valid levels: "off" (default), "error", "warn", "info", "debug", "trace".

Object API with progress and cancellation

from bytehaul import Downloader

downloader = Downloader(
    connect_timeout=15.0,
    dns_servers=["1.1.1.1"],
    doh_servers=["https://dns.google/dns-query"],
    enable_ipv6=False,
)
task = downloader.download(
    "https://example.com/large.bin",
    output_dir="downloads",
    proxy="http://127.0.0.1:7890",
)

# Poll progress
snap = task.progress()
print(
    f"State: {snap.state}, Downloaded: {snap.downloaded}, "
    f"Speed: {snap.speed:.0f} B/s, ETA: {snap.eta_secs}"
)

# Pause or cancel if needed
# task.pause()
# task.cancel()

# Wait for completion
task.wait()

Error handling

from bytehaul import download, DownloadFailedError, CancelledError, PausedError, ConfigError

try:
    download("https://example.com/file.bin", output_path="output.bin")
except ConfigError as e:
    print(f"Invalid parameter: {e}")
except PausedError:
    print("Download was paused")
except CancelledError:
    print("Download was cancelled")
except DownloadFailedError as e:
    print(f"Download failed: {e}")

API Reference

download(url, output_path=None, output_dir=None, **options)

Blocking convenience function. Downloads a file and returns when complete.

  • output_path: explicit filename or relative output path
  • output_dir: destination directory for explicit or auto-detected filenames
  • If output_path is omitted, bytehaul chooses Content-Disposition → URL path → download
  • Absolute output_path values are still accepted when output_dir is omitted

Downloader(connect_timeout=None, proxy=None, http_proxy=None, https_proxy=None, dns_servers=None, doh_servers=None, enable_ipv6=None)

Reusable downloader instance.

  • downloader.download(url, output_path=None, output_dir=None, **options) -> DownloadTask

Proxy settings passed to Downloader(...) act as defaults. You can override them per task by passing proxy, http_proxy, or https_proxy directly to downloader.download(...).

DownloadTask

Handle to a running download.

  • task.progress() -> ProgressSnapshot — current download progress
  • task.pause() — pause the download and persist resume metadata when available
  • task.cancel() — cancel the download
  • task.wait() — block until download completes (releases GIL)

ProgressSnapshot

Frozen snapshot of download progress.

Attribute Type Description
total_size int | None Total file size (if known)
downloaded int Bytes downloaded so far
state str "pending", "downloading", "completed", "failed", "cancelled", "paused"
speed float Recent-window speed in bytes/second
eta_secs float | None Estimated remaining seconds
elapsed_secs float | None Elapsed time in seconds

speed and eta_secs are computed from the same recent throughput window. speed is not a whole-download lifetime average, and eta_secs stays None until bytehaul has enough recent samples or a known total size.

Download options

Parameter Type Default
output_path str | Path | None None
output_dir str | Path | None None
headers dict[str, str] {}
max_connections int 4
connect_timeout float (secs) 30.0
read_timeout float (secs) 60.0
memory_budget int 67108864
file_allocation "none" | "prealloc" "prealloc"
resume bool True
piece_size int 1048576
min_split_size int 10485760
max_retries int 5
retry_base_delay float (secs) 1.0
retry_max_delay float (secs) 30.0
max_download_speed int 0 (unlimited)
checksum_sha256 str | None None
log_level str | None None ("off")

max_retries counts additional retries after the initial request/transfer attempt; 0 disables retries. Single-connection body failures resume from the writer's flushed contiguous prefix, while Range or object-metadata mismatches reset the file before restarting.

Valid log_level values: "off", "error", "warn", "info", "debug", "trace" (case-insensitive).

Network options

Use these on Downloader(...) to set defaults, or pass proxy, http_proxy, and https_proxy directly to downloader.download(...) or the blocking download(...) helper.

Parameter Type Default
proxy str | None None
http_proxy str | None None
https_proxy str | None None
dns_servers list[str] | None None
doh_servers list[str] | None None
enable_ipv6 bool | None True

Running tests

uv sync --project bindings/python
cd bindings/python
uv run --project . maturin develop -m Cargo.toml
uv run --project . pytest tests/ -v

Building wheels for release

Single platform:

cd bindings/python
uv run --project . maturin build --release -m Cargo.toml

Cross-platform (via CI):

# Linux x86_64 + aarch64, macOS x86_64 + arm64, Windows x86_64
# Use maturin's GitHub Actions: https://github.com/PyO3/maturin-action

The project uses abi3-py39, so a single wheel per platform covers all Python 3.9+ versions.

License

MIT. See the repository LICENSE file.

Project links

Data verified by PyPI on Sep 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.6)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for triwinds from gravatar.com triwinds

GitHub Statistics

Data verified by PyPI on Sep 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.9

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bytehaul-0.2.1.tar.gz (216.2 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

bytehaul-0.2.1-cp39-abi3-win_amd64.whl (2.9 MB view details)

Uploaded CPython 3.9+Windows x86-64

bytehaul-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.4 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

bytehaul-0.2.1-cp39-abi3-macosx_11_0_arm64.whl (3.1 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

bytehaul-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl (3.1 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file bytehaul-0.2.1.tar.gz.

File metadata

  • Download URL: bytehaul-0.2.1.tar.gz
  • Upload date:
  • Size: 216.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bytehaul-0.2.1.tar.gz
Algorithm Hash digest
SHA256 b9ce9d4b7f8ade4f090eea2ca0433bf783c8fae9b46e23cfb28d4c6712750673
MD5 1a2e64353feb20b6a311a445ae992c2e
BLAKE2b-256 1af86acdc079ecd873a7bb0f2eb436d4b1a51f8f7ab5696930313afbfce1047d

See more details on using hashes here.

Provenance

The following attestation bundles were made for bytehaul-0.2.1.tar.gz:

Publisher: publish-pypi.yml on triwinds/bytehaul

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bytehaul-0.2.1-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: bytehaul-0.2.1-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 2.9 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bytehaul-0.2.1-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 86a5179c188b64934983f29eb40946b2d052bf9883fc98544d9e6f33c7678472
MD5 fd20df7302b7c49c43c174996669445e
BLAKE2b-256 b0792b66245ccf8db3e6302ddae048baf2a7dfc4f5031479c89f84bc2ac240e3

See more details on using hashes here.

Provenance

The following attestation bundles were made for bytehaul-0.2.1-cp39-abi3-win_amd64.whl:

Publisher: publish-pypi.yml on triwinds/bytehaul

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bytehaul-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for bytehaul-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 71c5d6d9e1250b62c44e06ec73eecbdb800a87c5f08d8d2dd869c24c7c0a33da
MD5 4d7cec34ce6eeef348a03be5389a3507
BLAKE2b-256 45153d544ac9331599faed865cc4999578921173d5a8946b0d32e17a62e08ce5

See more details on using hashes here.

Provenance

The following attestation bundles were made for bytehaul-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish-pypi.yml on triwinds/bytehaul

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bytehaul-0.2.1-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for bytehaul-0.2.1-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3f7eb327a8ba775d8526c9b2e255311470c88222a4d4d96c2c3ce67c7f4a6349
MD5 ce35ae10676f9f72800d1ef9168ae81e
BLAKE2b-256 e1338494c8b3d639ca665421d55cbe0d44e171a9b9f91e0f8537ad3a51d387c1

See more details on using hashes here.

Provenance

The following attestation bundles were made for bytehaul-0.2.1-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: publish-pypi.yml on triwinds/bytehaul

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bytehaul-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for bytehaul-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 710433296dc53e19ea2630f947b46225335649a8c67d3b8bd4c74387cbcade30
MD5 a6c2037e614fb86d6676efe2c4cea788
BLAKE2b-256 966df16de52da690d7961fc512c88188ff1f45779d60517ca9a40c6a8eb5a11b

See more details on using hashes here.

Provenance

The following attestation bundles were made for bytehaul-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: publish-pypi.yml on triwinds/bytehaul

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.6

5 files

0.2.5

5 files

0.2.4

5 files

0.2.3

5 files

0.2.2

5 files

This release

0.2.1 This release

5 files

0.2.0

5 files

0.1.9

5 files

0.1.8

5 files

0.1.7

5 files

0.1.6

5 files

0.1.5

5 files

0.1.4

5 files

0.1.3

5 files

0.1.2

5 files

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