speedkit 0.1.0__py3-none-any.whl

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/__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/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"

speedkit/cli.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from speedkit.__meta__ import __version__
+from speedkit.client import Speedkit
+from speedkit.exceptions import SpeedkitError
+from speedkit.types import DEFAULT_ATTEMPTS, DEFAULT_TIMEOUT, PROVIDERS
+
+
+def main() -> None:
+    """Run a speed test and print the result as JSON."""
+    parser = argparse.ArgumentParser(
+        prog="speedkit",
+        description="Measure network speed and print the result as JSON.",
+    )
+    parser.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "-p",
+        "--provider",
+        choices=("auto", *PROVIDERS),
+        default="auto",
+        help="measurement source (default: %(default)s)",
+    )
+    parser.add_argument(
+        "-t",
+        "--timeout",
+        type=float,
+        default=DEFAULT_TIMEOUT,
+        help="time budget per provider in seconds (default: %(default)s)",
+    )
+    parser.add_argument(
+        "-a",
+        "--attempts",
+        type=int,
+        default=DEFAULT_ATTEMPTS,
+        help="maximum measurement attempts per provider (default: %(default)s)",
+    )
+    args = parser.parse_args()
+    try:
+        kit = Speedkit(args.provider, timeout=args.timeout, attempts=args.attempts)
+    except ValueError as exc:
+        parser.error(str(exc))
+    try:
+        result = kit.run()
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except SpeedkitError as exc:
+        sys.exit(f"speedkit: {exc}")
+    print(json.dumps(result.to_dict(), indent=2))
+
+
+if __name__ == "__main__":
+    main()

speedkit/client.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import typing as t
+from dataclasses import replace
+
+from speedkit.exceptions import SpeedkitError, SpeedtestError
+from speedkit.geoip import lookup
+from speedkit.providers import BaseProvider, LibrespeedProvider, OoklaProvider
+from speedkit.types import DEFAULT_ATTEMPTS, DEFAULT_TIMEOUT, PROVIDERS, Provider, SpeedtestResult
+
+if t.TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = ["Speedkit"]
+
+_PROVIDERS: t.Final[dict[Provider, type[BaseProvider]]] = {
+    "ookla": OoklaProvider,
+    "librespeed": LibrespeedProvider,
+}
+
+
+class Speedkit:
+    """Network speed measurement client.
+
+    Measures with the Ookla Speedtest CLI and falls back to LibreSpeed when
+    Speedtest is blocked or unavailable, then resolves the client network
+    info from a geo-IP service so results look the same either way.
+    """
+
+    def __init__(
+        self,
+        provider: Provider | t.Literal["auto"] = "auto",
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        attempts: int = DEFAULT_ATTEMPTS,
+        cache_dir: Path | None = None,
+    ) -> None:
+        """Initialize the client.
+
+        :param provider: Measurement source; ``"auto"`` tries Ookla first and falls
+            back to LibreSpeed, while a provider name pins that one.
+        :param timeout: Total time budget per provider run in seconds, covering
+            all measurement attempts.
+        :param attempts: Maximum measurement attempts per provider within the budget;
+            ``1`` disables retries.
+        :param cache_dir: Directory for cached CLI binaries; defaults to the user cache directory.
+        :raises ValueError: If ``provider`` is unknown or ``attempts`` is less than 1.
+        """
+        if provider != "auto" and provider not in PROVIDERS:
+            raise ValueError(f"unknown provider {provider!r}; choose from auto, {', '.join(PROVIDERS)}")
+        if attempts < 1:
+            raise ValueError("attempts must be at least 1")
+        self.provider = provider
+        self.timeout = timeout
+        self.attempts = attempts
+        self.cache_dir = cache_dir
+
+    def run(self) -> SpeedtestResult:
+        """Run the speed test.
+
+        :return: Measurement result, with client info from a geo-IP service when
+            one is reachable and from the measuring CLI otherwise.
+        :raises SpeedkitError: If the measurement fails — in ``"auto"`` mode,
+            after both providers have failed.
+        """
+        result = self._measure()
+        client = lookup()
+        return replace(result, client=client) if client else result
+
+    def _measure(self) -> SpeedtestResult:
+        """Measure with the pinned provider, or Ookla falling back to LibreSpeed."""
+        if self.provider != "auto":
+            return self._run(self.provider)
+        try:
+            return self._run("ookla")
+        except SpeedkitError as ookla_exc:
+            try:
+                return self._run("librespeed")
+            except SpeedkitError as librespeed_exc:
+                raise SpeedtestError(
+                    f"ookla: {ookla_exc}; librespeed: {librespeed_exc}",
+                    hint="check network access or set SPEEDKIT_OOKLA_BINARY / SPEEDKIT_LIBRESPEED_BINARY",
+                ) from librespeed_exc
+
+    def _run(self, provider: Provider) -> SpeedtestResult:
+        """Run one provider within the configured budget."""
+        return _PROVIDERS[provider](self.cache_dir).run(timeout=self.timeout, attempts=self.attempts)

speedkit/exceptions.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import typing as t
+
+__all__ = [
+    "BinaryDownloadError",
+    "SpeedkitError",
+    "SpeedtestError",
+    "UnsupportedPlatformError",
+]
+
+
+class SpeedkitError(Exception):
+    """Base exception for speedkit."""
+
+    def __init__(self, *args: t.Any, hint: str | None = None) -> None:
+        super().__init__(*args)
+        self.hint = hint
+
+    def __str__(self) -> str:
+        message = super().__str__()
+        if self.hint:
+            return f"{message}\n  Hint: {self.hint}"
+        return message
+
+
+class UnsupportedPlatformError(SpeedkitError):
+    """No prebuilt CLI binary exists for the current platform."""
+
+
+class BinaryDownloadError(SpeedkitError):
+    """Downloading or extracting a CLI binary failed."""
+
+
+class SpeedtestError(SpeedkitError):
+    """A speed test run failed."""

speedkit/geoip.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+import re
+import typing as t
+
+from speedkit.types import Client
+from speedkit.utils import fetch
+
+__all__ = ["lookup"]
+
+GEOIP_TIMEOUT: t.Final[float] = 5.0
+"""Timeout in seconds for a single geo-IP service request."""
+
+# ipinfo.io reports the ISP as "AS64496 Example ISP"; the other services omit the prefix.
+_AS_PREFIX = re.compile(r"^AS\d+\s+")
+
+
+def lookup(timeout: float = GEOIP_TIMEOUT) -> Client | None:
+    """Resolve client network info from the first responding geo-IP service.
+
+    Services are tried in order and the first usable answer wins, so a rate-limited
+    or unreachable service costs one timeout rather than the whole lookup.
+
+    :param timeout: Timeout in seconds for a single service request.
+    :return: Client info, or ``None`` if no service answered usefully.
+    """
+    for url, parse in _SERVICES:
+        try:
+            data = json.loads(fetch(url, timeout=timeout))
+            client = parse(data) if isinstance(data, dict) else None
+        except (AttributeError, OSError, TypeError, ValueError):
+            continue
+        # Services echo the IP back even in error payloads, so require the ISP too.
+        if client and client.ip and client.isp:
+            return client
+    return None
+
+
+def _from_ipinfo(data: dict[str, t.Any]) -> Client:
+    """Map an ipinfo.io response."""
+    return Client(
+        ip=data.get("ip", ""),
+        isp=_AS_PREFIX.sub("", data.get("org", "")),
+        country=data.get("country", ""),
+        city=data.get("city", ""),
+    )
+
+
+def _from_ipwho(data: dict[str, t.Any]) -> Client:
+    """Map an ipwho.is response."""
+    return Client(
+        ip=data.get("ip", ""),
+        isp=data.get("connection", {}).get("isp", ""),
+        country=data.get("country_code", ""),
+        city=data.get("city", ""),
+    )
+
+
+def _from_ipapi(data: dict[str, t.Any]) -> Client:
+    """Map an ip-api.com response."""
+    return Client(
+        ip=data.get("query", ""),
+        isp=data.get("isp", ""),
+        country=data.get("countryCode", ""),
+        city=data.get("city", ""),
+    )
+
+
+# Ordered by preference: HTTPS without a key first, plain-HTTP ip-api.com last.
+_SERVICES: t.Final[tuple[tuple[str, t.Callable[[dict[str, t.Any]], Client]], ...]] = (
+    ("https://ipinfo.io/json", _from_ipinfo),
+    ("https://ipwho.is", _from_ipwho),
+    ("http://ip-api.com/json", _from_ipapi),
+)

speedkit/providers.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import time
+import typing as t
+from abc import ABC, abstractmethod
+from datetime import datetime, timezone
+
+from speedkit.binaries import librespeed_binary, ookla_binary
+from speedkit.exceptions import SpeedtestError
+from speedkit.types import Client, Provider, Server, SpeedtestResult
+
+if t.TYPE_CHECKING:
+    from pathlib import Path
+
+__all__ = [
+    "BaseProvider",
+    "LibrespeedProvider",
+    "OoklaProvider",
+]
+
+
+class BaseProvider(ABC):
+    """Base class for speed test providers backed by a CLI binary."""
+
+    provider: t.ClassVar[Provider]
+
+    def __init__(self, cache_dir: Path | None = None) -> None:
+        self._cache_dir = cache_dir
+
+    def run(self, timeout: float, attempts: int = 1) -> SpeedtestResult:
+        """Run the speed test and return the parsed result.
+
+        :param timeout: Total time budget in seconds, shared by all attempts.
+        :param attempts: Maximum number of measurement attempts.
+        :return: Measurement result.
+        :raises SpeedtestError: If every attempt fails or the budget runs out.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            attempts -= 1
+            try:
+                return self._measure(self._command(), timeout=deadline - time.monotonic())
+            except SpeedtestError as exc:
+                remaining = deadline - time.monotonic()
+                if attempts <= 0 or remaining <= 0:
+                    raise
+                self._note_failure(exc, timeout=remaining)
+
+    def _note_failure(self, error: SpeedtestError, *, timeout: float) -> None:  # noqa: B027
+        """React to a failed attempt before the next one; does nothing by default."""
+
+    def _measure(self, command: list[str], *, timeout: float) -> SpeedtestResult:
+        """Execute a measurement command and parse its output."""
+        stdout = self._execute(command, timeout=timeout)
+        try:
+            return self._parse(stdout)
+        except (AttributeError, KeyError, IndexError, TypeError, ValueError) as exc:
+            raise SpeedtestError(f"unexpected output: {exc}") from exc
+
+    def _execute(self, command: list[str], *, timeout: float) -> str:
+        """Run a CLI command and return its stdout, raising ``SpeedtestError`` on failure."""
+        try:
+            process = subprocess.run(
+                command,
+                capture_output=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=timeout,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise SpeedtestError(str(exc)) from exc
+        if process.returncode != 0:
+            detail = self._error(process.stderr)
+            message = f"exited with code {process.returncode}"
+            raise SpeedtestError(f"{message}: {detail}" if detail else message)
+        return process.stdout
+
+    @abstractmethod
+    def _command(self) -> list[str]:
+        """Build the CLI command to execute."""
+
+    @abstractmethod
+    def _parse(self, stdout: str) -> SpeedtestResult:
+        """Parse the CLI JSON output into a result."""
+
+    @staticmethod
+    def _error(stderr: str) -> str:
+        """Extract a human-readable error message from the CLI stderr."""
+        return stderr.strip()
+
+
+class OoklaProvider(BaseProvider):
+    """Speed test via the official Ookla Speedtest CLI.
+
+    Running it implies acceptance of the Ookla EULA and GDPR terms:
+    the ``--accept-license`` and ``--accept-gdpr`` flags are passed automatically.
+    """
+
+    provider = "ookla"
+
+    def _command(self) -> list[str]:
+        """Build the Ookla Speedtest CLI command."""
+        return [str(ookla_binary(self._cache_dir)), "--format=json", "--accept-license", "--accept-gdpr"]
+
+    def _parse(self, stdout: str) -> SpeedtestResult:
+        """Parse ``speedtest --format=json`` output."""
+        data = json.loads(stdout)
+        server = data.get("server", {})
+        interface = data.get("interface", {})
+        latency = float(data.get("ping", {}).get("latency", 0.0))
+        host, port = server.get("host", ""), server.get("port", "")
+        return SpeedtestResult(
+            download=float(data["download"]["bandwidth"]) * 8.0,
+            upload=float(data["upload"]["bandwidth"]) * 8.0,
+            ping=latency,
+            server=Server(
+                name=server.get("location", ""),
+                country=server.get("country", ""),
+                sponsor=server.get("name", ""),
+                id=str(server.get("id", "")),
+                host=f"{host}:{port}" if host and port else host,
+                latency=latency,
+            ),
+            timestamp=_utc_now(),
+            bytes_sent=int(data["upload"].get("bytes", 0)),
+            bytes_received=int(data["download"].get("bytes", 0)),
+            client=Client(
+                ip=interface.get("externalIp", ""),
+                isp=data.get("isp", ""),
+            ),
+            provider=self.provider,
+        )
+
+    @staticmethod
+    def _error(stderr: str) -> str:
+        """Extract the error message from Ookla's JSON log lines on stderr."""
+        for line in reversed(stderr.splitlines()):
+            entry = _json_line(line)
+            if entry and entry.get("level") == "error":
+                return str(entry.get("message") or stderr.strip())
+        return stderr.strip()
+
+
+class LibrespeedProvider(BaseProvider):
+    """Speed test via the LibreSpeed CLI.
+
+    The CLI probes the public LibreSpeed server list and picks the
+    lowest-latency server nearby.
+    """
+
+    provider = "librespeed"
+
+    def __init__(self, cache_dir: Path | None = None) -> None:
+        super().__init__(cache_dir)
+        self._excluded: list[int] = []
+
+    def _command(self) -> list[str]:
+        """Build the librespeed-cli command."""
+        command = [str(librespeed_binary(self._cache_dir)), "--json"]
+        for server in self._excluded:
+            command += ["--exclude", str(server)]
+        return command
+
+    def _parse(self, stdout: str) -> SpeedtestResult:
+        """Parse ``librespeed-cli --json`` output."""
+        results = json.loads(stdout)
+        if not results:
+            raise SpeedtestError(
+                "librespeed-cli returned no results",
+                hint="the LibreSpeed servers may be unreachable from this network",
+            )
+        data = results[0]
+        server = data.get("server", {})
+        client = data.get("client", {})
+        ping = float(data.get("ping", 0.0))
+        return SpeedtestResult(
+            download=float(data["download"]) * 1_000_000.0,
+            upload=float(data["upload"]) * 1_000_000.0,
+            ping=ping,
+            server=Server(
+                url=server.get("url", ""),
+                name=server.get("name", ""),
+                latency=ping,
+            ),
+            timestamp=_utc_now(),
+            bytes_sent=int(data.get("bytes_sent", 0)),
+            bytes_received=int(data.get("bytes_received", 0)),
+            client=Client(
+                ip=client.get("ip", ""),
+                isp=client.get("org", ""),
+                country=client.get("country", ""),
+            ),
+            provider=self.provider,
+        )
+
+    def _note_failure(self, error: SpeedtestError, *, timeout: float) -> None:
+        """Exclude the failed server from the next attempt, when identifiable.
+
+        Half-dead servers in the public list can win selection yet fail the
+        measurement; without the exclusion a retry would pick them again.
+        """
+        match = _ERROR_URL.search(str(error))
+        if match is None:
+            return
+        try:
+            listing = self._execute([str(librespeed_binary(self._cache_dir)), "--list"], timeout=timeout)
+        except SpeedtestError:
+            return
+        for entry in _LIST_LINE.finditer(listing):
+            if match["host"] in entry["url"]:
+                self._excluded.append(int(entry["id"]))
+                return
+
+
+# Host of the failed server, taken from a CLI error like: Get "https://host/backend/...": timeout
+_ERROR_URL = re.compile(r'https?://(?P<host>[^/\s"]+)')
+
+# librespeed-cli --list line: "101: Springfield, Freedonia (Example Host) (https://example.net/)  [Sponsor: ...]"
+_LIST_LINE = re.compile(r"^(?P<id>\d+): .+ \((?P<url>https?://[^)]+)\)", re.MULTILINE)
+
+
+def _json_line(line: str) -> dict[str, t.Any] | None:
+    """Parse one line as a JSON object, returning ``None`` on failure."""
+    try:
+        data = json.loads(line)
+    except ValueError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _utc_now() -> str:
+    """Return the current time as an ISO 8601 UTC string with a ``Z`` suffix."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

speedkit/types.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import typing as t
+from dataclasses import asdict, dataclass
+
+__all__ = [
+    "DEFAULT_ATTEMPTS",
+    "DEFAULT_TIMEOUT",
+    "PROVIDERS",
+    "Client",
+    "Provider",
+    "Server",
+    "SpeedtestResult",
+]
+
+DEFAULT_TIMEOUT: t.Final[float] = 120.0
+"""Default time budget of a single provider run in seconds."""
+
+DEFAULT_ATTEMPTS: t.Final[int] = 2
+"""Default maximum number of measurement attempts per provider."""
+
+Provider = t.Literal["ookla", "librespeed"]
+"""Measurement source that produced a result."""
+
+PROVIDERS: t.Final[tuple[Provider, ...]] = t.get_args(Provider)
+"""All providers, in the order ``"auto"`` tries them."""
+
+
+@dataclass(frozen=True)
+class Server:
+    """Test server info.
+
+    Fields a provider does not report are left at neutral defaults.
+    """
+
+    url: str = ""
+    name: str = ""
+    country: str = ""
+    sponsor: str = ""
+    id: str = ""
+    host: str = ""
+    latency: float = 0.0
+
+
+@dataclass(frozen=True)
+class Client:
+    """Client connection info, resolved from a geo-IP service.
+
+    Fields the service does not report are left at neutral defaults.
+    """
+
+    ip: str = ""
+    isp: str = ""
+    country: str = ""
+    """Two-letter ISO country code, such as ``RU``."""
+    city: str = ""
+
+
+@dataclass(frozen=True)
+class SpeedtestResult:
+    """Speed test measurement result.
+
+    ``download`` and ``upload`` are in bits per second, ``ping`` in milliseconds.
+    """
+
+    client: Client
+    server: Server
+    provider: Provider
+
+    download: float
+    upload: float
+    ping: float
+    timestamp: str
+    bytes_sent: int
+    bytes_received: int
+
+    def to_dict(self) -> dict[str, t.Any]:
+        """Return the result as a plain JSON-serializable dict.
+
+        :return: Dict with a fixed key set and order, identical for every provider.
+        """
+        return asdict(self)

speedkit/utils.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import http.client
+import ssl
+import urllib.request
+
+__all__ = ["fetch"]
+
+
+def fetch(url: str, timeout: float) -> bytes:
+    """Fetch a URL and return the raw response body.
+
+    :param url: URL to fetch.
+    :param timeout: Timeout in seconds.
+    :return: Raw response body.
+    :raises OSError: If the request fails, including broken HTTP framing.
+    """
+    try:
+        with urllib.request.urlopen(url, timeout=timeout, context=_ssl_context()) as response:
+            data: bytes = response.read()
+        return data
+    except http.client.HTTPException as exc:
+        # Truncated bodies and bad status lines are not OSError; normalize for callers.
+        raise OSError(str(exc)) from exc
+
+
+def _ssl_context() -> ssl.SSLContext:
+    """Return an SSL context, preferring certifi's CA bundle when installed."""
+    try:
+        import certifi
+    except ImportError:
+        return ssl.create_default_context()
+    return ssl.create_default_context(cafile=certifi.where())

speedkit-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,17 @@
+speedkit/__init__.py,sha256=V_2XiPr97l9eCqPFv5CNRWPr8Wbvc8AIItPv6zXbl2o,497
+speedkit/__meta__.py,sha256=pzYIq6M1N-karCmP525iivCKOZIJdhc2POP0lSCep_s,253
+speedkit/binaries.py,sha256=xikSMDifxRlFyTMqHMYy6C7CeNX6gKCyi6oSB6qH-3E,5581
+speedkit/cli.py,sha256=cDhoZhth7uwrwHe1TUuYgQntSdj5krvPpOaOYCqjkto,1606
+speedkit/client.py,sha256=98NGhf13aL0_VxGO_l7cel6q4r1btOUql6fYnRbpF4c,3481
+speedkit/exceptions.py,sha256=GX3dxSWuxswY4J5FmI-01a5tysFi54Lx96DoXE9sf8w,829
+speedkit/geoip.py,sha256=2a0F8VBGrQnXYviw_W1sxQg7V4rQLZ-uxbVI6y9sxiM,2399
+speedkit/providers.py,sha256=ImZbe_iinpF3o3iYnrhJ38K-gnI0p-nE9r0PjaH-_nk,8821
+speedkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+speedkit/types.py,sha256=U2A9KhPz7NXF3RzkENtMg561DxOhrSBu7meJ9-xi_qI,1855
+speedkit/utils.py,sha256=NihSDDuYoErc5iuf9ZjD2-84X8g70LZdwkZQCjkaA9I,1017
+speedkit-0.1.0.dist-info/licenses/LICENSE,sha256=1YwwehUDcIl8EO2mm1P8V0ZVxAG6JkBkbJdRJU__GBo,1061
+speedkit-0.1.0.dist-info/METADATA,sha256=wi_YI_-nJBcSf7VlS-Ff8gKjmOQbPUf9RxkJ_sZZbxg,6221
+speedkit-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+speedkit-0.1.0.dist-info/entry_points.txt,sha256=cmOjvs5Hs1siTNV0VOtICzN_kVaAOepZDSwDuU2u9Iw,47
+speedkit-0.1.0.dist-info/top_level.txt,sha256=GWxIZSNQULWKGXo-5HfC9AKXQD9klBoEiZpuDd5NUuQ,9
+speedkit-0.1.0.dist-info/RECORD,,

speedkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

speedkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+speedkit = speedkit.cli:main

speedkit-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+speedkit