relenv 0.21.1__py3-none-any.whl → 0.22.0__py3-none-any.whl

relenv/common.py

@@ -1,24 +1,42 @@
-# Copyright 2023-2025 Broadcom.
-# SPDX-License-Identifier: Apache-2
+# Copyright 2022-2025 Broadcom.
+# SPDX-License-Identifier: Apache-2.0
 """
 Common classes and values used around relenv.
 """
+from __future__ import annotations
+
 import http.client
+import json
 import logging
 import os
 import pathlib
 import platform
 import queue
 import selectors
+import shutil
 import subprocess
 import sys
 import tarfile
 import textwrap
 import threading
 import time
+from typing import (
+    IO,
+    Any,
+    BinaryIO,
+    Callable,
+    Iterable,
+    Literal,
+    Mapping,
+    Optional,
+    Union,
+    cast,
+)
 
 # relenv package version
-__version__ = "0.21.1"
+__version__ = "0.22.0"
+
+log = logging.getLogger(__name__)
 
 MODULE_DIR = pathlib.Path(__file__).resolve().parent
 
@@ -30,6 +48,83 @@ DARWIN = "darwin"
 
 MACOS_DEVELOPMENT_TARGET = "10.15"
 
+TOOLCHAIN_CACHE_ENV = "RELENV_TOOLCHAIN_CACHE"
+_TOOLCHAIN_MANIFEST = ".toolchain-manifest.json"
+
+
+# 8 GiB archives are not unusual; stick to metadata to fingerprint them.
+def _archive_metadata(path: pathlib.Path) -> dict[str, Union[str, int]]:
+    stat = path.stat()
+    return {
+        "archive": str(path.resolve()),
+        "size": stat.st_size,
+        "mtime": stat.st_mtime_ns,
+    }
+
+
+def _toolchain_cache_root() -> Optional[pathlib.Path]:
+    override = os.environ.get(TOOLCHAIN_CACHE_ENV)
+    if override:
+        if override.strip().lower() == "none":
+            return None
+        return pathlib.Path(override).expanduser()
+    cache_home = os.environ.get("XDG_CACHE_HOME")
+    if cache_home:
+        base = pathlib.Path(cache_home)
+    else:
+        base = pathlib.Path.home() / ".cache"
+    return base / "relenv" / "toolchains"
+
+
+def _toolchain_manifest_path(toolchain_path: pathlib.Path) -> pathlib.Path:
+    return toolchain_path / _TOOLCHAIN_MANIFEST
+
+
+def _load_toolchain_manifest(path: pathlib.Path) -> Optional[Mapping[str, Any]]:
+    if not path.exists():
+        return None
+    try:
+        with path.open(encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    return data
+
+
+def _manifest_matches(manifest: Mapping[str, Any], metadata: Mapping[str, Any]) -> bool:
+    return (
+        manifest.get("archive") == metadata.get("archive")
+        and manifest.get("size") == metadata.get("size")
+        and manifest.get("mtime") == metadata.get("mtime")
+    )
+
+
+def _write_toolchain_manifest(
+    toolchain_path: pathlib.Path, metadata: Mapping[str, Any]
+) -> None:
+    manifest_path = _toolchain_manifest_path(toolchain_path)
+    try:
+        with manifest_path.open("w", encoding="utf-8") as handle:
+            json.dump(metadata, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+    except OSError as exc:  # pragma: no cover - permissions edge cases
+        log.warning(
+            "Unable to persist toolchain manifest at %s: %s", manifest_path, exc
+        )
+
+
+def toolchain_root_dir() -> pathlib.Path:
+    """Return the root directory used for cached toolchains."""
+    if sys.platform != "linux":
+        return DATA_DIR
+    root = _toolchain_cache_root()
+    if root is None:
+        return DATA_DIR / "toolchain"
+    return root
+
+
 REQUEST_HEADERS = {"User-Agent": f"relenv {__version__}"}
 
 CHECK_HOSTS = (
@@ -61,8 +156,9 @@ DATA_DIR = pathlib.Path(os.environ.get("RELENV_DATA", DEFAULT_DATA_DIR)).resolve
 SHEBANG_TPL_LINUX = textwrap.dedent(
     """#!/bin/sh
 "true" ''''
+# shellcheck disable=SC2093
 "exec" "$(dirname "$(readlink -f "$0")"){}" "$0" "$@"
-'''
+' '''
 """
 )
 
@@ -82,8 +178,10 @@ do
 done
 PHYS_DIR=$(pwd -P)
 REALPATH=$PHYS_DIR/$TARGET_FILE
+# shellcheck disable=SC2093
 "exec" "$(dirname "$REALPATH")"{} "$REALPATH" "$@"
-'''"""
+' '''
+"""
 )
 
 if sys.platform == "linux":
@@ -92,23 +190,141 @@ else:
     SHEBANG_TPL = SHEBANG_TPL_MACOS
 
 
-log = logging.getLogger(__name__)
-
-
 class RelenvException(Exception):
     """
     Base class for exeptions generated from relenv.
     """
 
 
-def format_shebang(python, tpl=SHEBANG_TPL):
+# Validation Errors
+class ValidationError(RelenvException):
+    """Base class for validation-related errors.
+
+    Raised when data validation fails (checksums, signatures, etc.).
+    This follows CPython's convention of having intermediate base classes
+    for related exception types.
+    """
+
+
+class ChecksumValidationError(ValidationError):
+    """Raised when file checksum verification fails.
+
+    This typically indicates file corruption or tampering. The error message
+    should include the expected and actual checksums when available.
+
+    Example:
+        raise ChecksumValidationError(
+            f"Checksum mismatch for {filename}: "
+            f"expected {expected}, got {actual}"
+        )
+    """
+
+
+class SignatureValidationError(ValidationError):
+    """Raised when GPG signature verification fails.
+
+    This indicates that a downloaded file's cryptographic signature
+    does not match the expected signature, suggesting tampering or
+    an incomplete download.
+
+    Example:
+        raise SignatureValidationError(
+            f"GPG signature verification failed for {filename}"
+        )
+    """
+
+
+# Download Errors
+class DownloadError(RelenvException):
+    """Raised when downloading a file from a URL fails.
+
+    This encompasses network errors, HTTP errors, and other issues
+    that prevent successfully retrieving a remote resource.
+
+    Example:
+        raise DownloadError(f"Failed to download {url}: {reason}")
+    """
+
+
+# Configuration Errors
+class ConfigurationError(RelenvException):
+    """Raised when required configuration is missing or invalid.
+
+    This typically occurs during build setup when recipes are incomplete
+    or environment variables are not properly set.
+
+    Example:
+        raise ConfigurationError(
+            "Python recipe is missing download configuration"
+        )
+    """
+
+
+# Platform Errors
+class PlatformError(RelenvException):
+    """Raised when operating on an unsupported platform.
+
+    Relenv supports Linux, macOS, and Windows. This exception is raised
+    when attempting operations that are platform-specific or when running
+    on an unsupported platform.
+
+    Example:
+        raise PlatformError(f"Unsupported platform: {sys.platform}")
+    """
+
+
+# Build Errors
+class BuildCommandError(RelenvException):
+    """Raised when a build command execution fails.
+
+    This indicates that a subprocess (compiler, linker, etc.) returned
+    a non-zero exit code during the build process.
+
+    Example:
+        raise BuildCommandError(
+            f"Build command failed: {' '.join(cmd)}"
+        )
+    """
+
+
+class MissingDependencyError(RelenvException):
+    """Raised when a required build dependency is not found.
+
+    This typically occurs when expected files, directories, or system
+    packages are missing from the build environment.
+
+    Example:
+        raise MissingDependencyError(
+            f"Unable to locate {dependency_name}"
+        )
+    """
+
+
+# Environment Errors
+class RelenvEnvironmentError(RelenvException):
+    """Raised when there are issues with the relenv environment.
+
+    This occurs when operations require being inside a relenv environment
+    but the current environment is not properly configured.
+
+    Example:
+        raise RelenvEnvironmentError(
+            "Not in a relenv environment"
+        )
+    """
+
+
+def format_shebang(python: str, tpl: str = SHEBANG_TPL) -> str:
     """
     Return a formatted shebang.
     """
-    return tpl.format(python).strip() + "\n"
+    shebang = tpl.format(python).strip()
+    if shebang.endswith("'''"):
+        return shebang + "\n\n"
+    return shebang + "\n"
 
 
-def build_arch():
+def build_arch() -> str:
     """
     Return the current machine.
     """
@@ -116,7 +332,9 @@ def build_arch():
     return machine.lower()
 
 
-def work_root(root=None):
+def work_root(
+    root: Optional[Union[str, os.PathLike[str]]] = None,
+) -> pathlib.Path:
     """
     Get the root directory that all other relenv working directories should be based on.
 
@@ -133,7 +351,9 @@ def work_root(root=None):
     return base
 
 
-def work_dir(name, root=None):
+def work_dir(
+    name: str, root: Optional[Union[str, os.PathLike[str]]] = None
+) -> pathlib.Path:
     """
     Get the absolute path to the relenv working directory of the given name.
 
@@ -161,17 +381,17 @@ class WorkDirs:
     :type root: str
     """
 
-    def __init__(self, root):
-        self.root = root
-        self.data = DATA_DIR
-        self.toolchain_config = work_dir("toolchain", self.root)
-        self.toolchain = work_dir("toolchain", DATA_DIR)
-        self.build = work_dir("build", DATA_DIR)
-        self.src = work_dir("src", DATA_DIR)
-        self.logs = work_dir("logs", DATA_DIR)
-        self.download = work_dir("download", DATA_DIR)
-
-    def __getstate__(self):
+    def __init__(self: "WorkDirs", root: Union[str, os.PathLike[str]]) -> None:
+        self.root: pathlib.Path = pathlib.Path(root)
+        self.data: pathlib.Path = DATA_DIR
+        self.toolchain_config: pathlib.Path = work_dir("toolchain", self.root)
+        self.toolchain: pathlib.Path = toolchain_root_dir()
+        self.build: pathlib.Path = work_dir("build", DATA_DIR)
+        self.src: pathlib.Path = work_dir("src", DATA_DIR)
+        self.logs: pathlib.Path = work_dir("logs", DATA_DIR)
+        self.download: pathlib.Path = work_dir("download", DATA_DIR)
+
+    def __getstate__(self: "WorkDirs") -> dict[str, pathlib.Path]:
         """
         Return an object used for pickling.
 
@@ -187,7 +407,7 @@ class WorkDirs:
             "download": self.download,
         }
 
-    def __setstate__(self, state):
+    def __setstate__(self: "WorkDirs", state: Mapping[str, pathlib.Path]) -> None:
         """
         Unwrap the object returned from unpickling.
 
@@ -203,7 +423,9 @@ class WorkDirs:
         self.download = state["download"]
 
 
-def work_dirs(root=None):
+def work_dirs(
+    root: Optional[Union[str, os.PathLike[str]]] = None,
+) -> WorkDirs:
     """
     Returns a WorkDirs instance based on the given root.
 
@@ -216,41 +438,76 @@ def work_dirs(root=None):
     return WorkDirs(work_root(root))
 
 
-def get_toolchain(arch=None, root=None):
+def get_toolchain(
+    arch: Optional[str] = None,
+    root: Optional[Union[str, os.PathLike[str]]] = None,
+) -> Optional[pathlib.Path]:
     """
     Get a the toolchain directory, specific to the arch if supplied.
 
+    On Linux, this function will extract the toolchain from ppbt if needed.
+    If the toolchain already exists, it will be returned even if ppbt is
+    not available (e.g., when running tests on non-Linux platforms that
+    patch sys.platform to "linux"). This allows using existing toolchains
+    without requiring ppbt to be installed.
+
     :param arch: The architecture to get the toolchain for
     :type arch: str
     :param root: The root of the relenv working directories to search in
     :type root: str
 
-    :return: The directory holding the toolchain
+    :return: The directory holding the toolchain, or None if on Linux and
+             the toolchain doesn't exist and ppbt is unavailable
     :rtype: ``pathlib.Path``
     """
+    del root  # Kept for backward compatibility; location driven by DATA_DIR
     os.makedirs(DATA_DIR, exist_ok=True)
     if sys.platform != "linux":
-        return DATA_DIR
-
-    TOOLCHAIN_ROOT = DATA_DIR / "toolchain"
-    TOOLCHAIN_PATH = TOOLCHAIN_ROOT / get_triplet()
-    if TOOLCHAIN_PATH.exists():
-        return TOOLCHAIN_PATH
+        return toolchain_root_dir()
 
-    ppbt = None
+    toolchain_root = toolchain_root_dir()
+    triplet = get_triplet(machine=arch)
+    toolchain_path = toolchain_root / triplet
+    metadata: Optional[Mapping[str, Any]] = None
+    if toolchain_path.exists():
+        metadata = _load_toolchain_manifest(_toolchain_manifest_path(toolchain_path))
 
     try:
-        import ppbt.common
+        from importlib import import_module
+
+        ppbt_common = import_module("ppbt.common")
     except ImportError:
-        pass
+        # If toolchain already exists, use it even without ppbt
+        return toolchain_path if toolchain_path.exists() else None
+    archive_attr = getattr(ppbt_common, "ARCHIVE", None)
+    extract = getattr(ppbt_common, "extract_archive", None)
+    if archive_attr is None or not callable(extract):
+        raise RelenvException("ppbt.common missing ARCHIVE or extract_archive")
+
+    toolchain_root.mkdir(parents=True, exist_ok=True)
+    archive_path = pathlib.Path(archive_attr)
+    archive_meta = _archive_metadata(archive_path)
+
+    if (
+        toolchain_path.exists()
+        and metadata
+        and _manifest_matches(metadata, archive_meta)
+    ):
+        return toolchain_path
 
-    if ppbt:
-        TOOLCHAIN_ROOT.mkdir(exist_ok=True)
-        ppbt.common.extract_archive(str(TOOLCHAIN_ROOT), str(ppbt.common.ARCHIVE))
-        return TOOLCHAIN_PATH
+    if toolchain_path.exists():
+        shutil.rmtree(toolchain_path)
+
+    extract(str(toolchain_root), str(archive_path))
+    if not toolchain_path.exists():
+        raise RelenvException(
+            f"Toolchain archive {archive_path} did not produce {toolchain_path}"
+        )
+    _write_toolchain_manifest(toolchain_path, archive_meta)
+    return toolchain_path
 
 
-def get_triplet(machine=None, plat=None):
+def get_triplet(machine: Optional[str] = None, plat: Optional[str] = None) -> str:
     """
     Get the target triplet for the specified machine and platform.
 
@@ -277,10 +534,10 @@ def get_triplet(machine=None, plat=None):
     elif plat == "linux":
         return f"{machine}-linux-gnu"
     else:
-        raise RelenvException(f"Unknown platform {plat}")
+        raise PlatformError(f"Unknown platform {plat}")
 
 
-def plat_from_triplet(plat):
+def plat_from_triplet(plat: str) -> str:
     """
     Convert platform from build to the value of sys.platform.
     """
@@ -290,26 +547,27 @@ def plat_from_triplet(plat):
         return "darwin"
     elif plat == "win":
         return "win32"
-    raise RelenvException(f"Unkown platform {plat}")
+    raise PlatformError(f"Unkown platform {plat}")
 
 
-def list_archived_builds():
+def list_archived_builds() -> list[tuple[str, str, str]]:
     """
     Return a list of version, architecture and platforms for builds.
     """
-    builds = []
-    dirs = work_dirs(DATA_DIR)
-    for root, dirs, files in os.walk(dirs.build):
-        for file in files:
-            if file.endswith(".tar.xz"):
-                file = file[:-7]
-                version, triplet = file.split("-", 1)
+    builds: list[tuple[str, str, str]] = []
+    working_dirs = work_dirs(DATA_DIR)
+    for root_dir, dirnames, filenames in os.walk(working_dirs.build):
+        del dirnames  # unused
+        for filename in filenames:
+            if filename.endswith(".tar.xz"):
+                base_name = filename[:-7]
+                version, triplet = base_name.split("-", 1)
                 arch, plat = triplet.split("-", 1)
                 builds.append((version, arch, plat))
     return builds
 
 
-def archived_build(triplet=None):
+def archived_build(triplet: Optional[str] = None) -> pathlib.Path:
     """
     Finds a the location of an archived build.
 
@@ -326,7 +584,9 @@ def archived_build(triplet=None):
     return dirs.build / archive
 
 
-def extract_archive(to_dir, archive):
+def extract_archive(
+    to_dir: Union[str, os.PathLike[str]], archive: Union[str, os.PathLike[str]]
+) -> None:
     """
     Extract an archive to a specific location.
 
@@ -335,19 +595,30 @@ def extract_archive(to_dir, archive):
     :param archive: The archive to extract
     :type archive: str
     """
-    if archive.endswith("tgz"):
+    archive_path = pathlib.Path(archive)
+    archive_str = str(archive_path)
+    to_path = pathlib.Path(to_dir)
+    TarReadMode = Literal["r:gz", "r:xz", "r:bz2", "r"]
+    read_type: TarReadMode = "r"
+    if archive_str.endswith(".tgz"):
+        log.debug("Found tgz archive")
         read_type = "r:gz"
-    elif archive.endswith("xz"):
+    elif archive_str.endswith(".tar.gz"):
+        log.debug("Found tar.gz archive")
+        read_type = "r:gz"
+    elif archive_str.endswith(".xz"):
+        log.debug("Found xz archive")
         read_type = "r:xz"
-    elif archive.endswith("bz2"):
+    elif archive_str.endswith(".bz2"):
+        log.debug("Found bz2 archive")
         read_type = "r:bz2"
     else:
-        read_type = "r"
-    with tarfile.open(archive, read_type) as t:
-        t.extractall(to_dir)
+        log.warning("Found unknown archive type: %s", archive_path)
+    with tarfile.open(str(archive_path), mode=read_type) as tar:
+        tar.extractall(str(to_path))
 
 
-def get_download_location(url, dest):
+def get_download_location(url: str, dest: Union[str, os.PathLike[str]]) -> str:
     """
     Get the full path to where the url will be downloaded to.
 
@@ -359,10 +630,10 @@ def get_download_location(url, dest):
     :return: The path to where the url will be downloaded to
     :rtype: str
     """
-    return os.path.join(dest, os.path.basename(url))
+    return os.path.join(os.fspath(dest), os.path.basename(url))
 
 
-def check_url(url, timestamp=None, timeout=30):
+def check_url(url: str, timestamp: Optional[float] = None, timeout: float = 30) -> bool:
     """
     Check that the url returns a 200.
     """
@@ -393,52 +664,79 @@ def check_url(url, timestamp=None, timeout=30):
     return True
 
 
-def fetch_url(url, fp, backoff=3, timeout=30):
+def fetch_url(
+    url: str,
+    fp: BinaryIO,
+    backoff: int = 3,
+    timeout: float = 30,
+    progress_callback: Optional[Callable[[int, int], None]] = None,
+) -> None:
     """
     Fetch the contents of a url.
 
     This method will store the contents in the given file like object.
+
+    :param progress_callback: Optional callback(downloaded_bytes, total_bytes)
+    :type progress_callback: Optional[Callable[[int, int], None]]
     """
     # Late import so we do not import hashlib before runtime.bootstrap is called.
     import urllib.error
     import urllib.request
 
     last = time.time()
-    if backoff < 1:
-        backoff = 1
-    n = 0
-    while n < backoff:
-        n += 1
+    attempts = max(backoff, 1)
+    response: http.client.HTTPResponse | None = None
+    for attempt in range(1, attempts + 1):
         try:
-            fin = urllib.request.urlopen(url, timeout=timeout)
+            response = urllib.request.urlopen(url, timeout=timeout)
+            break
         except (
             urllib.error.HTTPError,
             urllib.error.URLError,
             http.client.RemoteDisconnected,
         ) as exc:
-            if n >= backoff:
+            if attempt >= attempts:
                 raise RelenvException(f"Error fetching url {url} {exc}")
             log.debug("Unable to connect %s", url)
-            time.sleep(n * 10)
+            time.sleep(attempt * 10)
+    if response is None:
+        raise RelenvException(f"Unable to open url {url}")
     log.info("url opened %s", url)
+
+    # Get content length from headers
+    content_length = 0
     try:
-        total = 0
+        content_length_str = response.headers.get("Content-Length")
+        if content_length_str:
+            content_length = int(content_length_str)
+            log.info("Content-Length: %d bytes", content_length)
+            # Report initial state to callback
+            if progress_callback:
+                progress_callback(0, content_length)
+    except (ValueError, TypeError):
+        log.debug("Could not parse Content-Length header")
+
+    try:
+        downloaded = 0
         size = 1024 * 300
-        block = fin.read(size)
+        block = response.read(size)
         while block:
-            total += size
+            block_size = len(block)
+            downloaded += block_size
             if time.time() - last > 10:
-                log.info("%s > %d", url, total)
+                log.info("%s > %d", url, downloaded)
                 last = time.time()
             fp.write(block)
-            block = fin.read(10240)
+            # Report progress
+            if progress_callback and content_length > 0:
+                progress_callback(downloaded, content_length)
+            block = response.read(10240)
     finally:
-        fin.close()
-        # fp.close()
+        response.close()
     log.info("Download complete %s", url)
 
 
-def fetch_url_content(url, backoff=3, timeout=30):
+def fetch_url_content(url: str, backoff: int = 3, timeout: float = 30) -> str:
     """
     Fetch the contents of a url.
 
@@ -446,55 +744,47 @@ def fetch_url_content(url, backoff=3, timeout=30):
     """
     # Late import so we do not import hashlib before runtime.bootstrap is called.
     import gzip
-    import io
     import urllib.error
     import urllib.request
 
-    fp = io.BytesIO()
-
-    last = time.time()
-    if backoff < 1:
-        backoff = 1
-    n = 0
-    while n < backoff:
-        n += 1
+    attempts = max(backoff, 1)
+    response: http.client.HTTPResponse | None = None
+    for attempt in range(1, attempts + 1):
         try:
-            fin = urllib.request.urlopen(url, timeout=timeout)
+            response = urllib.request.urlopen(url, timeout=timeout)
+            break
         except (
             urllib.error.HTTPError,
             urllib.error.URLError,
             http.client.RemoteDisconnected,
         ) as exc:
-            if n >= backoff:
+            if attempt >= attempts:
                 raise RelenvException(f"Error fetching url {url} {exc}")
             log.debug("Unable to connect %s", url)
-            time.sleep(n * 10)
+            time.sleep(attempt * 10)
+    if response is None:
+        raise RelenvException(f"Unable to open url {url}")
     log.info("url opened %s", url)
     try:
-        total = 0
-        size = 1024 * 300
-        block = fin.read(size)
-        while block:
-            total += size
-            if time.time() - last > 10:
-                log.info("%s > %d", url, total)
-                last = time.time()
-            fp.write(block)
-            block = fin.read(10240)
+        data = response.read()
+        encoding = response.headers.get("content-encoding", "").lower()
     finally:
-        fin.close()
-        # fp.close()
+        response.close()
+    if encoding == "gzip":
+        log.debug("Found gzipped content")
+        data = gzip.decompress(data)
     log.info("Download complete %s", url)
-    fp.seek(0)
-    info = fin.info()
-    if "content-encoding" in info:
-        if info["content-encoding"] == "gzip":
-            log.debug("Found gzipped content")
-            fp = gzip.GzipFile(fileobj=fp)
-    return fp.read().decode()
+    return data.decode()
 
 
-def download_url(url, dest, verbose=True, backoff=3, timeout=60):
+def download_url(
+    url: str,
+    dest: Union[str, os.PathLike[str]],
+    verbose: bool = True,
+    backoff: int = 3,
+    timeout: float = 60,
+    progress_callback: Optional[Callable[[int, int], None]] = None,
+) -> str:
     """
     Download the url to the provided destination.
 
@@ -506,6 +796,8 @@ def download_url(url, dest, verbose=True, backoff=3, timeout=60):
     :type dest: str
     :param verbose: Print download url and destination to stdout
     :type verbose: bool
+    :param progress_callback: Optional callback(downloaded_bytes, total_bytes)
+    :type progress_callback: Optional[Callable[[int, int], None]]
 
     :raises urllib.error.HTTPError: If the url was unable to be downloaded
 
@@ -514,22 +806,24 @@ def download_url(url, dest, verbose=True, backoff=3, timeout=60):
     """
     local = get_download_location(url, dest)
     if verbose:
-        print(f"Downloading {url} -> {local}")
-    fout = open(local, "wb")
+        log.debug(f"Downloading {url} -> {local}")
     try:
-        fetch_url(url, fout, backoff, timeout)
+        with open(local, "wb") as fout:
+            fetch_url(url, fout, backoff, timeout, progress_callback)
     except Exception as exc:
         if verbose:
-            print(f"Unable to download: {url} {exc}", file=sys.stderr, flush=True)
+            log.error("Unable to download: %s\n%s", url, exc)
         try:
             os.unlink(local)
         except OSError:
             pass
         raise
+    finally:
+        log.debug(f"Finished downloading {url} -> {local}")
     return local
 
 
-def runcmd(*args, **kwargs):
+def runcmd(*args: Any, **kwargs: Any) -> subprocess.Popen[str]:
     """
     Run a command.
 
@@ -541,7 +835,9 @@ def runcmd(*args, **kwargs):
 
     :raises RelenvException: If the command finishes with a non zero exit code
     """
-    log.debug("Running command: %s", " ".join(args[0]))
+    if not args:
+        raise RelenvException("No command provided to runcmd")
+    log.debug("Running command: %s", " ".join(map(str, args[0])))
     # if "stdout" not in kwargs:
     kwargs["stdout"] = subprocess.PIPE
     # if "stderr" not in kwargs:
@@ -551,44 +847,63 @@ def runcmd(*args, **kwargs):
     if sys.platform != "win32":
 
         p = subprocess.Popen(*args, **kwargs)
+        stdout_stream = p.stdout
+        stderr_stream = p.stderr
+        if stdout_stream is None or stderr_stream is None:
+            p.wait()
+            raise RelenvException("Process pipes are unavailable")
         # Read both stdout and stderr simultaneously
         sel = selectors.DefaultSelector()
-        sel.register(p.stdout, selectors.EVENT_READ)
-        sel.register(p.stderr, selectors.EVENT_READ)
+        sel.register(stdout_stream, selectors.EVENT_READ)
+        sel.register(stderr_stream, selectors.EVENT_READ)
         ok = True
         while ok:
             for key, val1 in sel.select():
-                line = key.fileobj.readline()
+                del val1  # unused
+                stream = cast(IO[str], key.fileobj)
+                line = stream.readline()
                 if not line:
                     ok = False
                     break
                 if line.endswith("\n"):
                     line = line[:-1]
-                if key.fileobj is p.stdout:
+                if stream is stdout_stream:
                     log.info(line)
                 else:
                     log.error(line)
 
     else:
 
-        def enqueue_stream(stream, queue, type):
-            NOOP = object()
-            for line in iter(stream.readline, NOOP):
-                if line is NOOP or line == "":
+        def enqueue_stream(
+            stream: IO[str],
+            item_queue: "queue.Queue[tuple[int | str, str]]",
+            kind: int,
+        ) -> None:
+            last_line = ""
+            for line in iter(stream.readline, ""):
+                if line == "":
                     break
-                if line:
-                    queue.put((type, line))
-            log.debug("stream close %r %r", type, line)
+                item_queue.put((kind, line))
+                last_line = line
+            log.debug("stream close %r %r", kind, last_line)
             stream.close()
 
-        def enqueue_process(process, queue):
+        def enqueue_process(
+            process: subprocess.Popen[str],
+            item_queue: "queue.Queue[tuple[int | str, str]]",
+        ) -> None:
             process.wait()
-            queue.put(("x", "x"))
+            item_queue.put(("x", ""))
 
         p = subprocess.Popen(*args, **kwargs)
-        q = queue.Queue()
-        to = threading.Thread(target=enqueue_stream, args=(p.stdout, q, 1))
-        te = threading.Thread(target=enqueue_stream, args=(p.stderr, q, 2))
+        stdout_stream = p.stdout
+        stderr_stream = p.stderr
+        if stdout_stream is None or stderr_stream is None:
+            p.wait()
+            raise RelenvException("Process pipes are unavailable")
+        q: "queue.Queue[tuple[int | str, str]]" = queue.Queue()
+        to = threading.Thread(target=enqueue_stream, args=(stdout_stream, q, 1))
+        te = threading.Thread(target=enqueue_stream, args=(stderr_stream, q, 2))
         tp = threading.Thread(target=enqueue_process, args=(p, q))
         te.start()
         to.start()
@@ -610,11 +925,15 @@ def runcmd(*args, **kwargs):
 
     p.wait()
     if p.returncode != 0:
-        raise RelenvException("Build cmd '{}' failed".format(" ".join(args[0])))
+        raise BuildCommandError("Build cmd '{}' failed".format(" ".join(args[0])))
     return p
 
 
-def relative_interpreter(root_dir, scripts_dir, interpreter):
+def relative_interpreter(
+    root_dir: Union[str, os.PathLike[str]],
+    scripts_dir: Union[str, os.PathLike[str]],
+    interpreter: Union[str, os.PathLike[str]],
+) -> pathlib.Path:
     """
     Return a relativized path to the given scripts_dir and interpreter.
     """
@@ -632,7 +951,7 @@ def relative_interpreter(root_dir, scripts_dir, interpreter):
     return relscripts / relinterp
 
 
-def makepath(*paths):
+def makepath(*paths: Union[str, os.PathLike[str]]) -> tuple[str, str]:
     """
     Make a normalized path name from paths.
     """
@@ -644,31 +963,33 @@ def makepath(*paths):
     return dir, os.path.normcase(dir)
 
 
-def addpackage(sitedir, name):
+def addpackage(sitedir: str, name: Union[str, os.PathLike[str]]) -> list[str] | None:
     """
     Add editable package to path.
     """
     import io
     import stat
 
-    fullname = os.path.join(sitedir, name)
-    paths = []
+    fullname = os.path.join(sitedir, os.fspath(name))
+    paths: list[str] = []
     try:
         st = os.lstat(fullname)
     except OSError:
-        return
-    if (getattr(st, "st_flags", 0) & stat.UF_HIDDEN) or (
-        getattr(st, "st_file_attributes", 0) & stat.FILE_ATTRIBUTE_HIDDEN
+        return None
+    file_attr_hidden = getattr(stat, "FILE_ATTRIBUTE_HIDDEN", 0)
+    uf_hidden = getattr(stat, "UF_HIDDEN", 0)
+    if (getattr(st, "st_flags", 0) & uf_hidden) or (
+        getattr(st, "st_file_attributes", 0) & file_attr_hidden
     ):
         # print(f"Skipping hidden .pth file: {fullname!r}")
-        return
+        return None
     # print(f"Processing .pth file: {fullname!r}")
     try:
         # locale encoding is not ideal especially on Windows. But we have used
         # it for a long time. setuptools uses the locale encoding too.
         f = io.TextIOWrapper(io.open_code(fullname), encoding="locale")
     except OSError:
-        return
+        return None
     with f:
         for n, line in enumerate(f):
             if line.startswith("#"):
@@ -698,11 +1019,11 @@ def addpackage(sitedir, name):
     return paths
 
 
-def sanitize_sys_path(sys_path_entries):
+def sanitize_sys_path(sys_path_entries: Iterable[str]) -> list[str]:
     """
     Sanitize `sys.path` to only include paths relative to the onedir environment.
     """
-    __sys_path = []
+    __sys_path: list[str] = []
     __valid_path_prefixes = tuple(
         {
             pathlib.Path(sys.prefix).resolve(),
@@ -723,6 +1044,8 @@ def sanitize_sys_path(sys_path_entries):
     for known_path in __sys_path[:]:
         for _ in pathlib.Path(known_path).glob("__editable__.*.pth"):
             paths = addpackage(known_path, _)
+            if not paths:
+                continue
             for p in paths:
                 if p not in __sys_path:
                     __sys_path.append(p)
@@ -734,23 +1057,26 @@ class Version:
     Version comparisons.
     """
 
-    def __init__(self, data):
-        self.major, self.minor, self.micro = self.parse_string(data)
-        self._data = data
+    def __init__(self, data: str) -> None:
+        major, minor, micro = self.parse_string(data)
+        self.major: int = major
+        self.minor: Optional[int] = minor
+        self.micro: Optional[int] = micro
+        self._data: str = data
 
-    def __str__(self):
+    def __str__(self: "Version") -> str:
         """
         Version as string.
         """
-        _ = f"{self.major}"
+        result = f"{self.major}"
         if self.minor is not None:
-            _ += f".{self.minor}"
+            result += f".{self.minor}"
             if self.micro is not None:
-                _ += f".{self.micro}"
+                result += f".{self.micro}"
         # XXX What if minor was None but micro was an int.
-        return _
+        return result
 
-    def __hash__(self):
+    def __hash__(self: "Version") -> int:
         """
         Hash of the version.
 
@@ -759,7 +1085,7 @@ class Version:
         return hash((self.major, self.minor, self.micro))
 
     @staticmethod
-    def parse_string(data):
+    def parse_string(data: str) -> tuple[int, Optional[int], Optional[int]]:
         """
         Parse a version string into major, minor, and micro integers.
         """
@@ -773,10 +1099,12 @@ class Version:
         else:
             raise RuntimeError("Too many parts to  parse")
 
-    def __eq__(self, other):
+    def __eq__(self: "Version", other: object) -> bool:
         """
         Equality comparisons.
         """
+        if not isinstance(other, Version):
+            return NotImplemented
         mymajor = 0 if self.major is None else self.major
         myminor = 0 if self.minor is None else self.minor
         mymicro = 0 if self.micro is None else self.micro
@@ -785,10 +1113,12 @@ class Version:
         micro = 0 if other.micro is None else other.micro
         return mymajor == major and myminor == minor and mymicro == micro
 
-    def __lt__(self, other):
+    def __lt__(self: "Version", other: object) -> bool:
         """
         Less than comparrison.
         """
+        if not isinstance(other, Version):
+            return NotImplemented
         mymajor = 0 if self.major is None else self.major
         myminor = 0 if self.minor is None else self.minor
         mymicro = 0 if self.micro is None else self.micro
@@ -804,10 +1134,12 @@ class Version:
                 return True
         return False
 
-    def __le__(self, other):
+    def __le__(self: "Version", other: object) -> bool:
         """
         Less than or equal to comparrison.
         """
+        if not isinstance(other, Version):
+            return NotImplemented
         mymajor = 0 if self.major is None else self.major
         myminor = 0 if self.minor is None else self.minor
         mymicro = 0 if self.micro is None else self.micro
@@ -820,14 +1152,18 @@ class Version:
                     return True
         return False
 
-    def __gt__(self, other):
+    def __gt__(self: "Version", other: object) -> bool:
         """
         Greater than comparrison.
         """
+        if not isinstance(other, Version):
+            return NotImplemented
         return not self.__le__(other)
 
-    def __ge__(self, other):
+    def __ge__(self: "Version", other: object) -> bool:
         """
         Greater than or equal to comparrison.
         """
+        if not isinstance(other, Version):
+            return NotImplemented
         return not self.__lt__(other)