speedkit 0.1.0__tar.gz

speedkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ness
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

speedkit-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: speedkit
+Version: 0.1.0
+Summary: Python SDK for network speed testing — bandwidth, latency, and connection details in a single call.
+Author: nessshon
+Maintainer: nessshon
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nessshon/speedkit/
+Project-URL: Examples, https://github.com/nessshon/speedkit/tree/main/examples/
+Keywords: CLI,SDK,bandwidth,benchmark,internet speed,librespeed,network,ookla,speedtest
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: <3.15,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: mypy>=1.19.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Dynamic: license-file
+
+# 📦 Speedkit
+
+![Python Versions](https://img.shields.io/badge/Python-3.9%20--%203.14-black?color=FFE873&labelColor=3776AB)
+[![PyPI](https://img.shields.io/pypi/v/speedkit.svg?color=FFE873&labelColor=3776AB)](https://pypi.org/project/speedkit/)
+[![License](https://img.shields.io/github/license/nessshon/speedkit)](https://github.com/nessshon/speedkit/blob/main/LICENSE)
+
+### Python SDK for network speed testing
+
+Measures download, upload, and latency with the official [Ookla Speedtest CLI](https://www.speedtest.net/apps/cli)
+and falls back to [LibreSpeed](https://github.com/librespeed/speedtest-cli) when Speedtest is blocked or unavailable.
+
+**Features**
+
+- **Zero setup** — Ookla Speedtest first, LibreSpeed when it is blocked or fails.
+- **Automatic binaries** — downloaded and cached for your OS on first run.
+- **Nearby servers** — the lowest-latency server is picked automatically.
+- **Self-recovery** — failed attempts are retried, broken servers excluded.
+- **Uniform results** — same fields and units whichever provider ran; client info from geo-IP.
+
+## Installation
+
+```bash
+pip install speedkit
+```
+
+## Usage
+
+```python
+from speedkit import Speedkit
+
+kit = Speedkit()
+result = kit.run()
+
+print(f"download: {result.download / 1_000_000:.1f} Mbit/s")
+print(f"upload:   {result.upload / 1_000_000:.1f} Mbit/s")
+print(f"ping:     {result.ping:.1f} ms")
+
+data = result.to_dict()  # plain JSON-serializable dict
+```
+
+Or from the command line:
+
+```bash
+speedkit                  # auto: Ookla, then LibreSpeed
+speedkit -p librespeed    # pin one provider
+speedkit -t 180           # time budget per provider in seconds
+speedkit -a 1             # disable retries
+```
+
+`Speedkit()` needs no configuration; everything it accepts:
+
+```python
+kit = Speedkit(
+    provider="auto",   # "auto" | "ookla" | "librespeed" — a pinned provider never falls back
+    timeout=120,       # time budget per provider in seconds, covering all attempts
+    attempts=2,        # measurement attempts within the budget; 1 disables retries
+    cache_dir=None,    # where CLI binaries are cached; None = user cache directory
+)
+```
+
+## Result format
+
+`SpeedtestResult.to_dict()` returns `download`/`upload` in bits per second and `ping` in milliseconds:
+
+```json
+{
+  "client": {
+    "ip": "203.0.113.7",
+    "isp": "Example ISP",
+    "country": "ZZ",
+    "city": "Springfield"
+  },
+  "server": {
+    "url": "",
+    "name": "Springfield",
+    "country": "Freedonia",
+    "sponsor": "Example Sponsor",
+    "id": "1234",
+    "host": "speedtest.example.net:8080",
+    "latency": 0.681
+  },
+  "provider": "ookla",
+  "download": 293111520.0,
+  "upload": 292265640.0,
+  "ping": 0.681,
+  "timestamp": "2026-07-19T15:22:48Z",
+  "bytes_sent": 418465064,
+  "bytes_received": 426981996
+}
+```
+
+- `client` — from a geo-IP service, identical whichever provider measured.
+- `server` — the test server that provider picked; unreported fields stay at `""` / `0.0`.
+- `provider` — which measurer produced the result.
+
+## Geo-IP lookup
+
+Client details come from the first service that answers: `ipinfo.io` → `ipwho.is` → `ip-api.com`.
+
+- The lookup takes a fraction of a second.
+- If every service is unreachable, the measurement is still returned —
+  with whatever client info the CLI reported.
+
+> This sends your IP address to the geo-IP service that answers.
+
+## Binaries
+
+| Provider            | Version | Platforms                    |
+| ------------------- | ------- | ---------------------------- |
+| Ookla Speedtest CLI | 1.2.0   | Linux x86_64/aarch64, macOS  |
+| librespeed-cli      | 1.0.13  | Linux x86_64/aarch64, macOS  |
+
+Binaries are downloaded on first use and cached per platform:
+
+- Linux — `~/.cache/speedkit`
+- macOS — `~/Library/Caches/speedkit`
+
+Set `SPEEDKIT_OOKLA_BINARY` / `SPEEDKIT_LIBRESPEED_BINARY` to a path of a preinstalled
+binary to skip downloading entirely — useful for offline machines and locked-down networks.
+
+To pre-download the binaries at image build time (Docker, CI):
+
+```bash
+python -c "from speedkit.binaries import ookla_binary, librespeed_binary; ookla_binary(); librespeed_binary()"
+```
+
+> Running the Ookla provider passes `--accept-license --accept-gdpr`, which implies acceptance
+> of the [Ookla EULA](https://www.speedtest.net/about/eula) and privacy terms.
+
+## Errors
+
+Every error derives from `SpeedkitError` and carries an actionable hint:
+
+```python
+from speedkit import Speedkit, SpeedkitError
+
+try:
+    result = Speedkit().run()
+except SpeedkitError as error:
+    print(error)  # cause, and a hint on how to fix it
+```
+
+`UnsupportedPlatformError` — no prebuilt binary for this OS/arch; `BinaryDownloadError` —
+the binary could not be fetched; `SpeedtestError` — the measurement itself failed.
+
+## License
+
+This repository is distributed under the [MIT License](LICENSE).

speedkit-0.1.0/README.md

@@ -0,0 +1,148 @@
+# 📦 Speedkit
+
+![Python Versions](https://img.shields.io/badge/Python-3.9%20--%203.14-black?color=FFE873&labelColor=3776AB)
+[![PyPI](https://img.shields.io/pypi/v/speedkit.svg?color=FFE873&labelColor=3776AB)](https://pypi.org/project/speedkit/)
+[![License](https://img.shields.io/github/license/nessshon/speedkit)](https://github.com/nessshon/speedkit/blob/main/LICENSE)
+
+### Python SDK for network speed testing
+
+Measures download, upload, and latency with the official [Ookla Speedtest CLI](https://www.speedtest.net/apps/cli)
+and falls back to [LibreSpeed](https://github.com/librespeed/speedtest-cli) when Speedtest is blocked or unavailable.
+
+**Features**
+
+- **Zero setup** — Ookla Speedtest first, LibreSpeed when it is blocked or fails.
+- **Automatic binaries** — downloaded and cached for your OS on first run.
+- **Nearby servers** — the lowest-latency server is picked automatically.
+- **Self-recovery** — failed attempts are retried, broken servers excluded.
+- **Uniform results** — same fields and units whichever provider ran; client info from geo-IP.
+
+## Installation
+
+```bash
+pip install speedkit
+```
+
+## Usage
+
+```python
+from speedkit import Speedkit
+
+kit = Speedkit()
+result = kit.run()
+
+print(f"download: {result.download / 1_000_000:.1f} Mbit/s")
+print(f"upload:   {result.upload / 1_000_000:.1f} Mbit/s")
+print(f"ping:     {result.ping:.1f} ms")
+
+data = result.to_dict()  # plain JSON-serializable dict
+```
+
+Or from the command line:
+
+```bash
+speedkit                  # auto: Ookla, then LibreSpeed
+speedkit -p librespeed    # pin one provider
+speedkit -t 180           # time budget per provider in seconds
+speedkit -a 1             # disable retries
+```
+
+`Speedkit()` needs no configuration; everything it accepts:
+
+```python
+kit = Speedkit(
+    provider="auto",   # "auto" | "ookla" | "librespeed" — a pinned provider never falls back
+    timeout=120,       # time budget per provider in seconds, covering all attempts
+    attempts=2,        # measurement attempts within the budget; 1 disables retries
+    cache_dir=None,    # where CLI binaries are cached; None = user cache directory
+)
+```
+
+## Result format
+
+`SpeedtestResult.to_dict()` returns `download`/`upload` in bits per second and `ping` in milliseconds:
+
+```json
+{
+  "client": {
+    "ip": "203.0.113.7",
+    "isp": "Example ISP",
+    "country": "ZZ",
+    "city": "Springfield"
+  },
+  "server": {
+    "url": "",
+    "name": "Springfield",
+    "country": "Freedonia",
+    "sponsor": "Example Sponsor",
+    "id": "1234",
+    "host": "speedtest.example.net:8080",
+    "latency": 0.681
+  },
+  "provider": "ookla",
+  "download": 293111520.0,
+  "upload": 292265640.0,
+  "ping": 0.681,
+  "timestamp": "2026-07-19T15:22:48Z",
+  "bytes_sent": 418465064,
+  "bytes_received": 426981996
+}
+```
+
+- `client` — from a geo-IP service, identical whichever provider measured.
+- `server` — the test server that provider picked; unreported fields stay at `""` / `0.0`.
+- `provider` — which measurer produced the result.
+
+## Geo-IP lookup
+
+Client details come from the first service that answers: `ipinfo.io` → `ipwho.is` → `ip-api.com`.
+
+- The lookup takes a fraction of a second.
+- If every service is unreachable, the measurement is still returned —
+  with whatever client info the CLI reported.
+
+> This sends your IP address to the geo-IP service that answers.
+
+## Binaries
+
+| Provider            | Version | Platforms                    |
+| ------------------- | ------- | ---------------------------- |
+| Ookla Speedtest CLI | 1.2.0   | Linux x86_64/aarch64, macOS  |
+| librespeed-cli      | 1.0.13  | Linux x86_64/aarch64, macOS  |
+
+Binaries are downloaded on first use and cached per platform:
+
+- Linux — `~/.cache/speedkit`
+- macOS — `~/Library/Caches/speedkit`
+
+Set `SPEEDKIT_OOKLA_BINARY` / `SPEEDKIT_LIBRESPEED_BINARY` to a path of a preinstalled
+binary to skip downloading entirely — useful for offline machines and locked-down networks.
+
+To pre-download the binaries at image build time (Docker, CI):
+
+```bash
+python -c "from speedkit.binaries import ookla_binary, librespeed_binary; ookla_binary(); librespeed_binary()"
+```
+
+> Running the Ookla provider passes `--accept-license --accept-gdpr`, which implies acceptance
+> of the [Ookla EULA](https://www.speedtest.net/about/eula) and privacy terms.
+
+## Errors
+
+Every error derives from `SpeedkitError` and carries an actionable hint:
+
+```python
+from speedkit import Speedkit, SpeedkitError
+
+try:
+    result = Speedkit().run()
+except SpeedkitError as error:
+    print(error)  # cause, and a hint on how to fix it
+```
+
+`UnsupportedPlatformError` — no prebuilt binary for this OS/arch; `BinaryDownloadError` —
+the binary could not be fetched; `SpeedtestError` — the measurement itself failed.
+
+## License
+
+This repository is distributed under the [MIT License](LICENSE).

speedkit-0.1.0/pyproject.toml

@@ -0,0 +1,165 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "speedkit"
+description = "Python SDK for network speed testing — bandwidth, latency, and connection details in a single call."
+requires-python = ">=3.9,<3.15"
+authors = [
+    { name = "nessshon" },
+]
+maintainers = [
+    { name = "nessshon" },
+]
+dependencies = []
+keywords = [
+    "CLI",
+    "SDK",
+    "bandwidth",
+    "benchmark",
+    "internet speed",
+    "librespeed",
+    "network",
+    "ookla",
+    "speedtest",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Networking :: Monitoring",
+]
+dynamic = ["version"]
+readme = "README.md"
+license = "MIT"
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.19.0",
+    "pytest>=8.0",
+    "ruff>=0.8.0",
+]
+
+[project.scripts]
+speedkit = "speedkit.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/nessshon/speedkit/"
+Examples = "https://github.com/nessshon/speedkit/tree/main/examples/"
+
+[tool.setuptools.packages.find]
+include = ["speedkit", "speedkit.*"]
+
+[tool.setuptools.package-data]
+speedkit = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "speedkit.__meta__.__version__" }
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    # pydocstyle
+    "D",
+    # pycodestyle
+    "E", "W",
+    # pyflakes
+    "F",
+    # isort
+    "I",
+    # flake8-bugbear
+    "B",
+    # flake8-comprehensions
+    "C4",
+    # pyupgrade
+    "UP",
+    # flake8-simplify
+    "SIM",
+    # type-checking imports
+    "TCH",
+    # perflint
+    "PERF",
+    # flake8-debugger
+    "T10",
+    # flake8-print
+    "T20",
+    # flake8-pie
+    "PIE",
+    # pylint errors
+    "PLE",
+    # flake8-return
+    "RET",
+    # ruff-specific
+    "RUF",
+]
+ignore = [
+    # missing docstring in public module
+    "D100",
+    # missing docstring in public package
+    "D104",
+    # missing docstring in magic method
+    "D105",
+    # missing docstring in __init__
+    "D107",
+    # incorrect blank line before class
+    "D203",
+    # 1 blank line required between summary line and description
+    "D205",
+    # multi-line docstring summary should start at the second line
+    "D213",
+    # first word of the first line should be capitalized
+    "D403",
+    # first-party type-checking imports
+    "TC001",
+    # third-party type-checking imports
+    "TC002",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"speedkit/cli.py" = ["T201"]
+"examples/*" = ["D", "T20"]
+# SIM117: nested with statements are deliberate — parenthesized ones need Python 3.10.
+"tests/*" = ["D", "SIM117"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["speedkit"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.10"  # mypy dropped 3.9 analysis; real 3.9 support is verified by running the tests on 3.9
+strict = true
+pretty = true
+show_error_codes = true
+show_error_context = true
+namespace_packages = true
+follow_imports_for_stubs = true
+warn_unreachable = true
+enable_error_code = [
+    "ignore-without-code",
+    "redundant-cast",
+    "truthy-bool",
+]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

speedkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

speedkit-0.1.0/speedkit/__init__.py

@@ -0,0 +1,22 @@
+from speedkit.__meta__ import __version__
+from speedkit.client import Speedkit
+from speedkit.exceptions import (
+    BinaryDownloadError,
+    SpeedkitError,
+    SpeedtestError,
+    UnsupportedPlatformError,
+)
+from speedkit.types import Client, Provider, Server, SpeedtestResult
+
+__all__ = [
+    "BinaryDownloadError",
+    "Client",
+    "Provider",
+    "Server",
+    "Speedkit",
+    "SpeedkitError",
+    "SpeedtestError",
+    "SpeedtestResult",
+    "UnsupportedPlatformError",
+    "__version__",
+]

speedkit-0.1.0/speedkit/__meta__.py

@@ -0,0 +1,8 @@
+# Copyright (c) 2026 Shon Ness
+#
+# This source code is licensed under the MIT License found in the
+# LICENSE file in the root directory of this source tree.
+
+__version__ = "0.1.0"
+__author__ = "nessshon"
+__url__ = "https://github.com/nessshon/speedkit"

speedkit-0.1.0/speedkit/binaries.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import io
+import os
+import platform
+import sys
+import tarfile
+import typing as t
+from pathlib import Path
+
+from speedkit.exceptions import BinaryDownloadError, UnsupportedPlatformError
+from speedkit.utils import fetch
+
+__all__ = [
+    "LIBRESPEED_VERSION",
+    "OOKLA_VERSION",
+    "librespeed_binary",
+    "ookla_binary",
+]
+
+OOKLA_VERSION: t.Final[str] = "1.2.0"
+"""Pinned Ookla Speedtest CLI version."""
+
+LIBRESPEED_VERSION: t.Final[str] = "1.0.13"
+"""Pinned librespeed-cli version."""
+
+DOWNLOAD_TIMEOUT: t.Final[float] = 60.0
+"""Timeout in seconds for downloading a CLI binary."""
+
+_OOKLA_URL: t.Final[str] = "https://install.speedtest.net/app/cli/ookla-speedtest-{version}-{platform}.{ext}"
+_LIBRESPEED_URL: t.Final[str] = (
+    "https://github.com/librespeed/speedtest-cli/releases/download/v{version}/librespeed-cli_{version}_{platform}.{ext}"
+)
+
+_OOKLA_PLATFORMS: t.Final[dict[tuple[str, str], str]] = {
+    ("Linux", "x86_64"): "linux-x86_64",
+    ("Linux", "aarch64"): "linux-aarch64",
+    ("Darwin", "x86_64"): "macosx-universal",
+    ("Darwin", "arm64"): "macosx-universal",
+}
+_LIBRESPEED_PLATFORMS: t.Final[dict[tuple[str, str], str]] = {
+    ("Linux", "x86_64"): "linux_amd64",
+    ("Linux", "aarch64"): "linux_arm64",
+    ("Darwin", "x86_64"): "darwin_amd64",
+    ("Darwin", "arm64"): "darwin_arm64",
+}
+
+
+def ookla_binary(cache_dir: Path | None = None) -> Path:
+    """Return the Ookla Speedtest CLI binary path, downloading it on first use.
+
+    Honors the ``SPEEDKIT_OOKLA_BINARY`` environment variable override.
+
+    :param cache_dir: Directory for cached binaries; defaults to the user cache directory.
+    :return: Path to the executable binary.
+    :raises UnsupportedPlatformError: If no prebuilt binary exists for this platform.
+    :raises BinaryDownloadError: If downloading or extracting the binary fails.
+    """
+    override = os.environ.get("SPEEDKIT_OOKLA_BINARY")
+    if override:
+        return Path(override)
+    key = _platform_key(_OOKLA_PLATFORMS, brand="Ookla Speedtest CLI")
+    url = _OOKLA_URL.format(version=OOKLA_VERSION, platform=key, ext="tgz")
+    return _ensure(url, member="speedtest", subdir=f"ookla-{OOKLA_VERSION}", cache_dir=cache_dir)
+
+
+def librespeed_binary(cache_dir: Path | None = None) -> Path:
+    """Return the librespeed-cli binary path, downloading it on first use.
+
+    Honors the ``SPEEDKIT_LIBRESPEED_BINARY`` environment variable override.
+
+    :param cache_dir: Directory for cached binaries; defaults to the user cache directory.
+    :return: Path to the executable binary.
+    :raises UnsupportedPlatformError: If no prebuilt binary exists for this platform.
+    :raises BinaryDownloadError: If downloading or extracting the binary fails.
+    """
+    override = os.environ.get("SPEEDKIT_LIBRESPEED_BINARY")
+    if override:
+        return Path(override)
+    key = _platform_key(_LIBRESPEED_PLATFORMS, brand="librespeed-cli")
+    url = _LIBRESPEED_URL.format(version=LIBRESPEED_VERSION, platform=key, ext="tar.gz")
+    return _ensure(url, member="librespeed-cli", subdir=f"librespeed-{LIBRESPEED_VERSION}", cache_dir=cache_dir)
+
+
+def _platform_key(platforms: dict[tuple[str, str], str], *, brand: str) -> str:
+    """Map the current OS and architecture to a release asset key."""
+    system, machine = platform.system(), platform.machine()
+    key = platforms.get((system, machine))
+    if key is None:
+        raise UnsupportedPlatformError(
+            f"no prebuilt {brand} binary for {system}/{machine}",
+            hint="install it manually and set the SPEEDKIT_OOKLA_BINARY / SPEEDKIT_LIBRESPEED_BINARY variable",
+        )
+    return key
+
+
+def _ensure(url: str, *, member: str, subdir: str, cache_dir: Path | None) -> Path:
+    """Return the cached binary path, downloading and extracting it if missing."""
+    target = (cache_dir or _user_cache_dir()) / subdir / member
+    if target.exists():
+        return target
+    target.parent.mkdir(parents=True, exist_ok=True)
+    data = _extract(_download(url), url=url, member=member)
+    # PID-unique temp name: concurrent downloads must not write into one file.
+    temporary = target.with_name(f"{member}.{os.getpid()}.tmp")
+    temporary.write_bytes(data)
+    temporary.chmod(0o755)
+    temporary.replace(target)
+    return target
+
+
+def _download(url: str) -> bytes:
+    """Download a release archive and return its bytes."""
+    try:
+        return fetch(url, timeout=DOWNLOAD_TIMEOUT)
+    except OSError as exc:
+        raise BinaryDownloadError(
+            f"failed to download {url}: {exc}",
+            hint="check network access (`pip install certifi` fixes SSL certificate errors) "
+            "or point SPEEDKIT_OOKLA_BINARY / SPEEDKIT_LIBRESPEED_BINARY at a local binary",
+        ) from exc
+
+
+def _extract(data: bytes, *, url: str, member: str) -> bytes:
+    """Extract a single member from a ``.tgz``/``.tar.gz`` archive."""
+    try:
+        with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as bundle:
+            extracted = bundle.extractfile(member)
+            if extracted is None:
+                raise KeyError(member)
+            return extracted.read()
+    except (KeyError, tarfile.TarError) as exc:
+        raise BinaryDownloadError(f"failed to extract {member!r} from {url}: {exc}") from exc
+
+
+def _user_cache_dir() -> Path:
+    """Return the platform-specific user cache directory for speedkit."""
+    if sys.platform == "darwin":
+        base = Path("~/Library/Caches")
+    else:
+        base = Path(os.environ.get("XDG_CACHE_HOME", "~/.cache"))
+    return base.expanduser() / "speedkit"