speedtest-cli-ng 0.1.1__py3-none-any.whl

speedtest/__init__.py

@@ -0,0 +1,15 @@
+"""
+speedtest-cli: Next generation CLI for testing internet bandwidth using speedtest.net
+
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("speedtest-cli-ng")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__date__ = "2026-06-10"
+__author__ = "Michał Korczak"
+__licence__ = "Apache License, Version 2.0"

speedtest/__main__.py

@@ -0,0 +1,40 @@
+"""
+The main entry point. Invoke as `speedtest-cli` or `python -m speedtest`.
+"""
+
+import sys
+
+from speedtest.cli.main import shell
+from speedtest.exceptions import SpeedtestException
+from speedtest.utils.logger import logger
+from speedtest.utils.status import ExitStatus
+
+
+def main() -> int:
+    """Execute the CLI and return an integer exit status."""
+
+    try:
+        exit_status = shell()
+
+        return int(exit_status)
+
+    except KeyboardInterrupt:
+        logger.error("Stopped by user")
+        return ExitStatus.ERROR_CTRL_C.value
+
+    except SpeedtestException as e:
+        code = getattr(e, "code", ExitStatus.ERROR.value)
+
+        if code not in (ExitStatus.SUCCESS.value, ExitStatus.ERROR_CTRL_C.value):
+            msg = str(e) or repr(e)
+            logger.error(f"ERROR: {msg}")
+
+        return int(code)
+
+    except Exception as e:
+        logger.exception("An unexpected error occurred.", e)
+        return ExitStatus.ERROR.value
+
+
+if __name__ == "__main__":
+    sys.exit(main())

speedtest/cli/commands.py

@@ -0,0 +1,120 @@
+"""
+Wraps the core Speedtest logic into CLI actions.
+"""
+
+import threading
+
+from speedtest.cli.output import convert_speed
+from speedtest.client import Speedtest
+from speedtest.exceptions import (
+    ConfigRetrievalError,
+    NoMatchedServer,
+    ServersRetrievalError,
+    SpeedtestCLIError,
+)
+from speedtest.http.errors import HTTP_ERRORS
+from speedtest.utils.logger import logger
+from speedtest.utils.status import ExitStatus
+
+__all__ = [
+    "get_speedtest_instance",
+    "handle_server_list",
+    "run_transfer_tests",
+    "select_server",
+]
+
+# Exception groupings for cleaner try/except blocks
+CONFIG_EXCEPTIONS = (*tuple(HTTP_ERRORS), ConfigRetrievalError)
+SERVER_EXCEPTIONS = (*tuple(HTTP_ERRORS), ServersRetrievalError)
+
+
+def get_speedtest_instance(
+    source: str | None,
+    timeout: float,
+    threads: int | None,
+    shutdown_event: threading.Event,
+) -> Speedtest:
+    """Initialize the Speedtest core and fetch initial configurations."""
+
+    try:
+        return Speedtest(
+            source_address=source,
+            timeout=timeout,
+            threads=threads,
+            shutdown_event=shutdown_event,
+        )
+    except CONFIG_EXCEPTIONS as e:
+        logger.error("Cannot retrieve speedtest configuration")
+        raise SpeedtestCLIError(e) from e
+
+
+def handle_server_list(st: Speedtest) -> int:
+    """Handle the --list argument by printing nearby servers and exiting."""
+
+    try:
+        st.get_servers()
+    except SERVER_EXCEPTIONS as e:
+        logger.error("Cannot retrieve speedtest server list")
+        raise SpeedtestCLIError(e) from e
+
+    try:
+        for _, servers in sorted(st.servers.items()):
+            for server in servers:
+                line = (
+                    f"{server.get('id', 0):>5}) {server.get('sponsor', 'Unknown')} "
+                    f"({server.get('name', 'Unknown')}, {server.get('country', 'Unknown')}) "
+                    f"[{server.get('d', 0.0):.2f} km]"
+                )
+                print(line)
+    except BrokenPipeError:
+        pass
+
+    return ExitStatus.SUCCESS.value
+
+
+def select_server(st: Speedtest, server: int | None = None) -> None:
+    """Fetch servers and filter down to the best candidate."""
+
+    logger.info("Retrieving speedtest.net server list...")
+    try:
+        st.get_servers(server=server)
+    except NoMatchedServer as e:
+        raise e
+    except SERVER_EXCEPTIONS as e:
+        logger.error("Cannot retrieve speedtest server list")
+        raise SpeedtestCLIError(e) from e
+
+    if server is not None:
+        logger.info("Retrieving information for the selected server...")
+    else:
+        logger.info("Selecting best server based on ping...")
+
+    st.get_best_server()
+
+
+def run_transfer_tests(
+    st: Speedtest,
+    no_download: bool = False,
+    no_upload: bool = False,
+    units: tuple[str, int] = ("bits", 1),
+) -> None:
+    """Execute download and upload test sequences."""
+
+    results = st.results
+    unit_name, unit_divisor = units
+
+    if no_download:
+        logger.info("Skipping download test")
+    else:
+        logger.info("Testing download speed")
+        st.download()
+        download_speed = convert_speed(results.download, unit_divisor)
+        logger.info(f"Download: {download_speed:.2f} M{unit_name}/s")
+
+    if no_upload:
+        logger.info("Skipping upload test")
+    else:
+        logger.info("Testing upload speed")
+        st.upload()
+        upload_speed = convert_speed(results.upload, unit_divisor)
+        logger.info(f"Upload: {upload_speed:.2f} M{unit_name}/s")

speedtest/cli/main.py

@@ -0,0 +1,108 @@
+"""
+The main entry point of the CLI shell.
+"""
+
+import argparse
+import signal
+import threading
+from typing import Any
+
+from speedtest.cli.commands import (
+    get_speedtest_instance,
+    handle_server_list,
+    run_transfer_tests,
+    select_server,
+)
+from speedtest.cli.output import csv_header, display_results
+from speedtest.cli.parser import parse_args
+from speedtest.exceptions import SpeedtestCLIError
+from speedtest.utils.logger import logger, setup_logging
+from speedtest.utils.status import ExitStatus
+
+__all__ = ["shell"]
+
+
+def _register_shutdown_handler() -> threading.Event:
+    """Register a SIGINT handler and return the associated shutdown event."""
+
+    shutdown_event = threading.Event()
+
+    def _handler(signum: int, frame: Any) -> None:
+        shutdown_event.set()
+        logger.warning("\nStopping speedtest-cli...")
+        raise KeyboardInterrupt
+
+    signal.signal(signal.SIGINT, _handler)
+    return shutdown_event
+
+
+def _validate_args(args: argparse.Namespace) -> None:
+    """Perform pre-flight validation on CLI arguments."""
+
+    if args.no_download and args.no_upload:
+        raise SpeedtestCLIError("Cannot supply both --no-download and --no-upload")
+
+
+def shell() -> int:
+    """Run the full speedtest.net test orchestrator."""
+
+    args = parse_args()
+
+    is_quiet: bool = args.csv or args.json or args.csv_header
+    setup_logging(debug=args.debug, quiet=is_quiet)
+
+    _validate_args(args)
+
+    if args.csv_header:
+        return csv_header(args.csv_delimiter)
+
+    # Setup graceful shutdown for threads
+    shutdown_event = _register_shutdown_handler()
+
+    threads = 1 if args.single else args.threads
+
+    # Initialize Core Pipeline
+    logger.info("Retrieving speedtest.net configuration...")
+
+    st = get_speedtest_instance(
+        source=args.source,
+        timeout=args.timeout,
+        threads=threads,
+        shutdown_event=shutdown_event,
+    )
+
+    # Handle early-exit commands
+    if args.list:
+        return handle_server_list(st)
+
+    # Execute Standard Pipeline
+    client_cfg = st.config.get("client", {})
+    logger.info(
+        f"Testing from {client_cfg.get('isp', 'Unknown ISP')} "
+        f"({client_cfg.get('ip', 'Unknown IP')})..."
+    )
+
+    select_server(st, server=args.server)
+
+    server_cfg = st.results.server
+    logger.info(
+        f"Hosted by {server_cfg.get('sponsor', 'Unknown')} "
+        f"({server_cfg.get('name', 'Unknown')}) "
+        f"[{server_cfg.get('d', 0.0):.2f} km]: {st.results.ping:.4f} ms"
+    )
+
+    run_transfer_tests(
+        st,
+        no_download=args.no_download,
+        no_upload=args.no_upload,
+        units=args.units,
+    )
+    display_results(
+        results=st.results,
+        csv_format=args.csv,
+        json_format=args.json,
+        csv_delimiter=args.csv_delimiter,
+        share=args.share,
+    )
+
+    return ExitStatus.SUCCESS.value

speedtest/cli/output.py

@@ -0,0 +1,46 @@
+"""
+Handles formatting, printing, and CSV/JSON output.
+"""
+
+from speedtest.engine.results import SpeedtestResults
+from speedtest.utils.logger import logger
+from speedtest.utils.status import ExitStatus
+
+__all__ = ["convert_speed", "csv_header", "display_results"]
+
+
+def convert_speed(speed_bps: float, unit_divisor: int) -> float:
+    """Convert speed from bits per second to the requested unit (e.g., Mega/s)."""
+
+    return (speed_bps / 1_000_000) / unit_divisor
+
+
+def csv_header(delimiter: str = ",") -> int:
+    """Print the CSV Headers and return a successful exit status."""
+
+    print(SpeedtestResults.csv_header(delimiter=delimiter))
+    return ExitStatus.SUCCESS.value
+
+
+def display_results(
+    results: SpeedtestResults,
+    csv_format: bool = False,
+    json_format: bool = False,
+    csv_delimiter: str = ",",
+    share: bool = False,
+) -> None:
+    """Render the final output to the user based on requested format (JSON, CSV, Text)."""
+
+    logger.debug(f"Results:\n{results.to_dict()!r}")
+
+    share_link = None
+    if share:
+        share_link = results.share()
+
+    if csv_format:
+        print(results.csv(delimiter=csv_delimiter))
+    elif json_format:
+        print(results.json())
+
+    if share and not (csv_format or json_format):
+        print(f"Share results: {share_link}")

speedtest/cli/parser.py

@@ -0,0 +1,130 @@
+"""
+Handles CLI arguments and validation.
+"""
+
+import argparse
+
+from speedtest import __version__
+
+__all__ = ["parse_args"]
+
+
+def _single_char_delimiter(value: str) -> str:
+    """Argparse type validator to ensure a delimiter is exactly one character."""
+
+    if len(value) != 1:
+        raise argparse.ArgumentTypeError(
+            f"CSV delimiter must be a single character, got: {value!r}"
+        )
+    return value
+
+
+def parse_args() -> argparse.Namespace:
+    """Function to handle building and parsing of command line arguments."""
+
+    description = (
+        "Next generation CLI for testing internet bandwidth using speedtest.net.\n"
+        "--------------------------------------------------------------------------\n"
+        "https://github.com/Omikorin/speedtest-cli"
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="speedtest-cli",
+        description=description,
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    core_group = parser.add_argument_group("Core Options")
+    core_group.add_argument(
+        "-l",
+        "--list",
+        action="store_true",
+        help="Show available speedtest.net servers sorted by distance.",
+    )
+    core_group.add_argument(
+        "-s",
+        "--server",
+        type=int,
+        help="Specify a server id to test against.",
+    )
+
+    transfer_group = parser.add_argument_group("Transfer Modifiers")
+    transfer_group.add_argument(
+        "--no-download",
+        action="store_true",
+        help="Do not perform the download test.",
+    )
+    transfer_group.add_argument(
+        "--no-upload",
+        action="store_true",
+        help="Do not perform the upload test.",
+    )
+
+    threads_group = transfer_group.add_mutually_exclusive_group()
+    threads_group.add_argument(
+        "-t",
+        "--threads",
+        type=int,
+        help="Set the number of concurrent connections instead of using downloaded config.",
+    )
+    threads_group.add_argument(
+        "--single",
+        action="store_true",
+        help="Use one concurrent connection. Simulates a typical file transfer.",
+    )
+
+    output_group = parser.add_argument_group("Output Options")
+    output_group.add_argument(
+        "--share",
+        action="store_true",
+        help="Generate and provide a URL to the speedtest.net share results image.",
+    )
+    output_group.add_argument(
+        "--bytes",
+        dest="units",
+        action="store_const",
+        const=("byte", 8),
+        default=("bit", 1),
+        help=(
+            "Display values in bytes instead of bits. "
+            "Does not affect image generation or JSON/CSV output."
+        ),
+    )
+
+    format_group = output_group.add_mutually_exclusive_group()
+    format_group.add_argument(
+        "--csv",
+        action="store_true",
+        help=(
+            "Suppress verbose output, only show basic information "
+            "in CSV format. Speeds listed in bit/s."
+        ),
+    )
+    format_group.add_argument(
+        "--json",
+        action="store_true",
+        help=(
+            "Suppress verbose output, only show basic information "
+            "in JSON format. Speeds listed in bit/s."
+        ),
+    )
+
+    output_group.add_argument(
+        "--csv-delimiter",
+        default=",",
+        type=_single_char_delimiter,
+        help="Single character delimiter to use in CSV output.",
+    )
+    output_group.add_argument(
+        "--csv-header", action="store_true", help="Print CSV headers and exit."
+    )
+
+    conn_group = parser.add_argument_group("Connection Options")
+    conn_group.add_argument(
+        "--source", type=str, help="Bind a source IP address to use for connections."
+    )
+    conn_group.add_argument("--timeout", default=10.0, type=float, help="HTTP timeout in seconds.")
+    conn_group.add_argument("--debug", action="store_true", help="Show verbose debugging output.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    return parser.parse_args()

speedtest/client.py

@@ -0,0 +1,144 @@
+import threading
+from typing import Any
+
+from speedtest.engine.config import fetch_config
+from speedtest.engine.results import SpeedtestResults
+from speedtest.engine.servers import fetch_servers, get_best_server
+from speedtest.engine.transfer import run_download_test, run_upload_test
+from speedtest.exceptions import NoMatchedServer, SpeedtestCLIError
+from speedtest.http.handlers import build_opener
+
+__all__ = ["Speedtest"]
+
+
+class Speedtest:
+    """Class for performing standard speedtest.net testing operations."""
+
+    def __init__(
+        self,
+        config: dict[str, Any] | None = None,
+        source_address: str | None = None,
+        timeout: float = 10.0,
+        shutdown_event: threading.Event | None = None,
+        threads: int | None = None,
+    ):
+        self._source_address = source_address
+        self._timeout = timeout
+        self._shutdown_event = shutdown_event or threading.Event()
+        self._threads = threads
+
+        self._opener = build_opener(source_address, timeout)
+
+        # Fetch default configuration and safely merge optional overrides
+        self.config = fetch_config(self._opener) or {}
+        if config:
+            self.config.update(config)
+
+        self.lat_lon = self.config.get("lat_lon") or (0.0, 0.0)
+
+        # Core state data structures
+        self.servers: dict[float, list[dict[str, Any]]] = {}
+        self.closest: list[dict[str, Any]] = []
+        self._best: dict[str, Any] = {}
+
+        self.results = SpeedtestResults(
+            client=self.config.get("client", {}),
+            opener=self._opener,
+        )
+
+    @property
+    def best(self) -> dict[str, Any]:
+        """Lazy-loaded property to retrieve the best available server."""
+
+        if not self._best:
+            self.get_best_server()
+        return self._best
+
+    def get_servers(self, server: int | None = None) -> dict[float, list[dict[str, Any]]]:
+        """
+        Fetch the server list from speedtest.net, sort them by distance,
+        and optionally filter down to a specific server ID.
+        """
+
+        ignore = self.config.get("ignore_servers", [])
+
+        self.servers = fetch_servers(
+            opener=self._opener,
+            lat_lon=self.lat_lon,
+            ignore_servers=ignore,
+        )
+
+        # Flatten the distance-grouped dict into a clean linear list sorted by proximity
+        sorted_distances = sorted(self.servers.keys())
+        self.closest = [srv for distance in sorted_distances for srv in self.servers[distance]]
+
+        # Filter by a specific server ID if requested
+        if server is not None:
+            self.closest = [s for s in self.closest if int(s.get("id", 0)) == server]
+
+            if not self.closest:
+                raise NoMatchedServer(f"No server matched the ID: {server}")
+
+        return self.servers
+
+    def get_best_server(self, limit: int = 5) -> dict[str, Any]:
+        """Determine the lowest-latency server by pinging the top `limit` closest options."""
+
+        if not self.closest:
+            self.get_servers()
+
+        if not self.closest:
+            raise SpeedtestCLIError("No servers available to test against.")
+
+        # Isolate the closest N servers to avoid wasting execution time pinging distant servers
+        candidates = self.closest[:limit]
+
+        self._best = get_best_server(candidates, self._opener)
+
+        if not self._best:
+            raise SpeedtestCLIError("Failed to identify a valid best server.")
+
+        self.results.server = self._best
+        self.results.ping = self._best.get("latency_ms", 0.0)
+
+        return self._best
+
+    def download(self) -> float:
+        """Test concurrent download speed against the chosen optimal server."""
+
+        best_url = self.best.get("url")
+        if not best_url:
+            raise SpeedtestCLIError("The best selected server is missing a valid URL.")
+
+        bytes_received, download_speed = run_download_test(
+            best_server_url=best_url,
+            config=self.config,
+            opener=self._opener,
+            shutdown_event=self._shutdown_event,
+            threads=self._threads,
+        )
+
+        self.results.bytes_received = bytes_received
+        self.results.download = download_speed
+
+        return self.results.download
+
+    def upload(self) -> float:
+        """Test concurrent upload speed against the chosen optimal server."""
+
+        best_url = self.best.get("url")
+        if not best_url:
+            raise SpeedtestCLIError("The best selected server is missing a valid URL.")
+
+        bytes_sent, upload_speed = run_upload_test(
+            best_server_url=best_url,
+            config=self.config,
+            opener=self._opener,
+            shutdown_event=self._shutdown_event,
+            threads=self._threads,
+        )
+
+        self.results.bytes_sent = bytes_sent
+        self.results.upload = upload_speed
+
+        return self.results.upload