kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/lock/wheelruntime/profile.py

@@ -0,0 +1,104 @@
+"""The per-platform lock *profile* for the wheel+runtime family.
+
+A profile is the small, platform-specific seam the generic builder/resolver
+depend on. It reads the platform's ``[tool.kivy.<platform>]`` overlay off the
+shared ``Config`` and answers: which variants to resolve, how a wheel tag maps to
+variants (the coverage rule), which runtime provider to use, and the
+platform-appropriate error/hint wording. Adding Linux/Windows/Android is writing
+one of these — no new builder, resolver, model, or serializer.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ...config.model import Config
+from .resolver import Variant, WheelResolver, get_wheel_resolver
+from .runtime import RuntimeProvider
+
+
+class PlatformLockProfile(ABC):
+    """Platform-specific inputs to the generic wheel+runtime lock engine."""
+
+    #: Platform name; the ``pylock.<platform>.toml`` infix + overlay key.
+    platform: str
+
+    @abstractmethod
+    def overlay(self, config: Config):
+        """The platform overlay object (e.g. ``config.macos``), or ``None``."""
+
+    @abstractmethod
+    def missing_overlay_error(self) -> str:
+        """Message when the overlay is absent (nothing to lock)."""
+
+    @abstractmethod
+    def python_version(self, config: Config) -> str:
+        """The bundled CPython version to pin."""
+
+    @abstractmethod
+    def variants(self, config: Config) -> tuple[Variant, ...]:
+        """The build variants to resolve (arch/ABI + pip ``--platform`` tag)."""
+
+    @abstractmethod
+    def wheel_covers(self, platform_tag: str, archs: tuple[str, ...]) -> set[str]:
+        """The subset of ``archs`` a wheel's platform tag satisfies.
+
+        A fat wheel (e.g. macOS ``universal2``) returns every arch; a per-arch
+        wheel returns its own; an unrelated tag returns the empty set.
+        """
+
+    def wheel_coverage(
+        self, wheel, archs: tuple[str, ...]
+    ) -> tuple[set[str], str | None]:
+        """Archs a resolved *wheel* covers, plus an optional non-fatal warning.
+
+        Default: the pure tag→arch rule (:meth:`wheel_covers`) with no warning.
+        A platform may override to gate coverage on the wheel's *source* — e.g.
+        Linux accepts a plain ``linux_*`` (no-glibc-promise) wheel only when it
+        was vendored via ``find_links``, and warns when it does.
+        """
+        return self.wheel_covers(wheel.platform_tag, archs), None
+
+    @abstractmethod
+    def runtime_provider(self, config: Config) -> RuntimeProvider:
+        """The default runtime provider for this platform."""
+
+    @abstractmethod
+    def coverage_error(self, name: str, missing: list[str]) -> str:
+        """Message when a compiled package is missing a required variant."""
+
+    @abstractmethod
+    def wheel_scope_hint(self) -> str:
+        """The vendored-wheel scope hint (platform-appropriate example path)."""
+
+    # --- fields with cross-platform defaults (overlay-name agnostic accessors) ---
+
+    def wheel_resolver(self) -> WheelResolver:
+        return get_wheel_resolver("pip")
+
+    def extra_index_urls(self, config: Config) -> tuple[str, ...]:
+        return tuple(getattr(self.overlay(config), "extra_index_urls", ()) or ())
+
+    def find_links(self, config: Config) -> tuple[str, ...]:
+        return tuple(getattr(self.overlay(config), "find_links", ()) or ())
+
+    def exclude(self, config: Config) -> tuple[str, ...]:
+        return tuple(getattr(self.overlay(config), "exclude", ()) or ())
+
+    def archs(self, config: Config) -> tuple[str, ...]:
+        return tuple(v.arch for v in self.variants(config))
+
+    def schema_version(self, config: Config) -> int:
+        return int(getattr(self.overlay(config), "schema_version", 1))
+
+    def declared_floor(self, config: Config) -> str | None:
+        """The user-declared OS floor to validate against the runtime floor."""
+        return None
+
+    def floor_error(
+        self, declared: str, runtime_floor: str, version: str
+    ) -> str:  # pragma: no cover - overridden where a floor exists
+        return (
+            f"the declared OS floor {declared} is below the {runtime_floor} floor "
+            f"required by the Python {version} runtime."
+        )

kivyforge/lock/wheelruntime/resolver.py

@@ -0,0 +1,248 @@
+"""Generic wheel resolver for the wheel+runtime family.
+
+Resolves ``[project].dependencies`` to fully-pinned wheels, host-independent: pip
+runs once per *variant* (an arch/ABI + its pip ``--platform`` tag) and the
+results are merged. A wheel that satisfies several variants (e.g. macOS
+``universal2``) is deduplicated by filename. The pip mechanics are identical to
+the iOS resolver (dry-run ``--report`` per platform tag); only the tag list — and
+the coverage rule, which lives in the platform profile — differ. The
+platform-neutral pip helpers are shared from ``kivyforge.lock.resolver``.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from ..model import canonical_name
+from ..resolver import (
+    MIN_PIP_VERSION,
+    _dep_names,
+    abi_tags,
+    pip_python_version,
+    pip_version,
+    version_str,
+)
+
+
+class WheelResolverError(Exception):
+    """A resolution failure (missing variant, non-wheel, backend error)."""
+
+
+@dataclass(frozen=True)
+class Variant:
+    """One build variant: an arch/ABI identifier + its pip ``--platform`` tag(s).
+
+    ``platform_tag`` is the primary/identity tag. ``extra_platform_tags`` lets a
+    variant request additional pip ``--platform`` tags in the *same* pip
+    invocation — Linux needs this because pip does not expand the manylinux
+    hierarchy from a single explicit ``--platform`` (see linux-spec), so the
+    profile passes the whole compatible tag ladder and pip resolves one
+    consistent version accepting a wheel matching any of them. macOS variants
+    carry a single tag (``extra_platform_tags`` empty).
+    """
+
+    arch: str
+    platform_tag: str
+    extra_platform_tags: tuple[str, ...] = ()
+
+    @property
+    def request_tags(self) -> tuple[str, ...]:
+        return (self.platform_tag, *self.extra_platform_tags)
+
+
+@dataclass(frozen=True)
+class ResolvedWheel:
+    filename: str
+    url: str
+    sha256: str
+    upload_time: str | None = None
+    size: int | None = None
+
+
+@dataclass
+class ResolvedPackage:
+    name: str
+    version: str
+    wheels: list[ResolvedWheel] = field(default_factory=list)
+    requires_python: str | None = None
+    dependencies: list[str] = field(default_factory=list)
+    source_index: str | None = None
+
+
+class WheelResolver(Protocol):
+    def resolve(
+        self,
+        requirements: list[str],
+        *,
+        python_version: str,
+        variants: tuple[Variant, ...],
+        extra_index_urls: list[str],
+        find_links: list[str] | None = None,
+        offline: bool = False,
+    ) -> list[ResolvedPackage]:
+        """Resolve requirements to wheels covering every requested variant."""
+        ...
+
+
+class PipWheelResolver:
+    """Default backend: stock pip cross-resolution via ``pip install --report``."""
+
+    def __init__(self, python_executable: str | None = None) -> None:
+        self._python = python_executable or sys.executable
+
+    def resolve(
+        self,
+        requirements: list[str],
+        *,
+        python_version: str,
+        variants: tuple[Variant, ...],
+        extra_index_urls: list[str],
+        find_links: list[str] | None = None,
+        offline: bool = False,
+    ) -> list[ResolvedPackage]:
+        if not requirements:
+            return []
+        self._require_modern_pip()
+        abis = abi_tags(python_version)
+        merged: dict[str, ResolvedPackage] = {}
+        seen_filenames: dict[str, set[str]] = {}
+
+        for variant in variants:
+            report = self._run_report(
+                requirements,
+                python_version=python_version,
+                platform_tags=variant.request_tags,
+                abis=abis,
+                extra_index_urls=extra_index_urls,
+                find_links=find_links or [],
+                offline=offline,
+            )
+            for item in report.get("install", []):
+                self._absorb(item, merged, seen_filenames)
+
+        return list(merged.values())
+
+    def _require_modern_pip(self) -> None:
+        version = pip_version(self._python)
+        if version is not None and version < MIN_PIP_VERSION:
+            raise WheelResolverError(
+                f"kivyforge needs pip >= {version_str(MIN_PIP_VERSION)} to resolve "
+                f"wheels, but {self._python} has pip {version_str(version)}.\n"
+                f"  Upgrade it: {self._python} -m pip install --upgrade pip"
+            )
+
+    def _absorb(self, item, merged, seen_filenames) -> None:
+        meta = item.get("metadata", {})
+        name = meta.get("name")
+        version = meta.get("version")
+        download = item.get("download_info", {})
+        url = download.get("url", "")
+        if not url.endswith(".whl"):
+            raise WheelResolverError(
+                f"{name} {version} resolved to a non-wheel source ({url}); "
+                "kivyforge installs only wheels (no on-host compile)."
+            )
+        archive = download.get("archive_info", {})
+        hashes = archive.get("hashes", {})
+        sha256 = hashes.get("sha256", "")
+        filename = url.rsplit("/", 1)[-1]
+        key = canonical_name(name)
+        pkg = merged.get(key)
+        if pkg is None:
+            pkg = ResolvedPackage(
+                name=name,
+                version=version,
+                requires_python=meta.get("requires_python"),
+                dependencies=_dep_names(meta.get("requires_dist", [])),
+            )
+            merged[key] = pkg
+            seen_filenames[key] = set()
+        elif version != pkg.version:
+            raise WheelResolverError(
+                f"{name} resolved to inconsistent versions across variants: "
+                f"{pkg.version!r} and {version!r}. Every variant of a package "
+                "must pin the same version."
+            )
+        if filename not in seen_filenames[key]:
+            seen_filenames[key].add(filename)
+            pkg.wheels.append(ResolvedWheel(filename=filename, url=url, sha256=sha256))
+
+    def _run_report(
+        self,
+        requirements: list[str],
+        *,
+        python_version: str,
+        platform_tags: tuple[str, ...],
+        abis: tuple[str, ...],
+        extra_index_urls: list[str],
+        find_links: list[str],
+        offline: bool,
+    ) -> dict:
+        with tempfile.TemporaryDirectory(prefix="kivy-wheel-lock-") as tmp:
+            report_path = Path(tmp) / "report.json"
+            cmd = [
+                self._python,
+                "-m",
+                "pip",
+                "install",
+                "--dry-run",
+                "--ignore-installed",
+                "--only-binary=:all:",
+                "--python-version",
+                pip_python_version(python_version),
+                "--implementation",
+                "cp",
+                "--target",
+                str(Path(tmp) / "target"),
+                "--report",
+                str(report_path),
+            ]
+            # pip accepts --platform multiple times; a wheel matching ANY of the
+            # tags is eligible while a single consistent version set is resolved.
+            for tag in platform_tags:
+                cmd += ["--platform", tag]
+            for abi in abis:
+                cmd += ["--abi", abi]
+            for index in extra_index_urls:
+                cmd += ["--extra-index-url", index]
+            for link in find_links:
+                cmd += ["--find-links", link]
+            if offline:
+                cmd += ["--no-index"]
+            cmd += list(requirements)
+
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+            if proc.returncode != 0:
+                tags = ", ".join(platform_tags)
+                raise WheelResolverError(
+                    f"pip could not resolve wheels for platform tag(s) {tags}.\n"
+                    f"  This usually means a dependency has no wheel for that "
+                    f"variant upstream.\n"
+                    f"  pip said:\n{_indent(proc.stderr or proc.stdout)}"
+                )
+            try:
+                return json.loads(report_path.read_text(encoding="utf-8"))
+            except (OSError, ValueError) as exc:
+                raise WheelResolverError(f"could not read pip report: {exc}") from exc
+
+
+def get_wheel_resolver(backend: str = "pip", **kwargs) -> WheelResolver:
+    if backend == "pip":
+        return PipWheelResolver(**kwargs)
+    raise WheelResolverError(f"unknown resolver backend {backend!r} (expected pip)")
+
+
+def _indent(text: str) -> str:
+    return "\n".join(f"    {line}" for line in (text or "").splitlines())

kivyforge/lock/wheelruntime/runtime.py

@@ -0,0 +1,161 @@
+"""Swappable Python-runtime providers for the wheel+runtime family.
+
+A ``RuntimeProvider`` resolves a CPython version + arch set to concrete, pinned
+per-arch archives and normalizes them (downstream) to a canonical relocatable
+layout the bundler consumes. Hiding the *source* behind this seam means switching
+from ``python-build-standalone`` (PBS) to python.org's future relocatable builds
+is a re-lock, not a rewrite.
+
+``PbsProvider`` is the generic PBS implementation, parameterized by an
+arch→target-triple map so each platform (macOS darwin triples now, Linux triples
+later) is a one-line specialization. PBS embeds a dated release tag in every
+asset filename, so the concrete URL + SHA-256 are discovered via an injectable
+``MetadataFetcher`` (keeping the selection logic hermetically testable); the real
+GitHub-backed fetcher is validated at the phase stop.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from .model import PythonRuntime, RuntimeArtifact
+
+PBS_PROVIDER_NAME = "python-build-standalone"
+
+# Per-provider archive layout: the sub-directory an extracted runtime archive
+# places its canonical relocatable CPython tree under. Staging (macOS/Linux)
+# consults this by the runtime's recorded ``provider`` field instead of assuming
+# a fixed layout, so the bundler depends only on the canonical contract and a
+# new provider is registered here in one place (spec 07).
+_PROVIDER_ARCHIVE_ROOTS = {
+    PBS_PROVIDER_NAME: "python",
+}
+
+
+def normalized_runtime_root(provider: str, extracted: Path) -> Path:
+    """Return the canonical relocatable CPython root within *extracted*.
+
+    Encapsulates each provider's archive layout so bundlers never hard-code a
+    specific provider's internals. Raises :class:`RuntimeProviderError` for an
+    unregistered provider or an archive that does not match its expected layout.
+    """
+    try:
+        root_name = _PROVIDER_ARCHIVE_ROOTS[provider]
+    except KeyError:
+        raise RuntimeProviderError(
+            f"no runtime staging layout registered for provider {provider!r}; "
+            f"known providers: {', '.join(sorted(_PROVIDER_ARCHIVE_ROOTS))}."
+        ) from None
+    root = extracted / root_name
+    if not root.is_dir():
+        raise RuntimeProviderError(
+            f"the extracted runtime is missing the expected top-level "
+            f"{root_name}/ directory required by the {provider!r} runtime provider."
+        )
+    return root
+
+
+class RuntimeProviderError(Exception):
+    """A runtime could not be resolved (unknown arch, missing asset, offline)."""
+
+
+@dataclass(frozen=True)
+class ReleaseAsset:
+    """One resolved downloadable archive for a single arch."""
+
+    url: str
+    sha256: str
+    archive_format: str = "tar.gz"
+
+
+class MetadataFetcher(Protocol):
+    """Resolves a (version, target triple) to a concrete asset (URL + SHA-256)."""
+
+    def fetch(
+        self, version: str, target_triple: str, *, offline: bool = False
+    ) -> ReleaseAsset: ...
+
+
+class RuntimeProvider(Protocol):
+    name: str
+
+    def resolve(
+        self, version: str, archs: tuple[str, ...], *, offline: bool = False
+    ) -> PythonRuntime: ...
+
+
+class PbsProvider:
+    """python-build-standalone provider, parameterized by an arch→triple map."""
+
+    name = PBS_PROVIDER_NAME
+
+    def __init__(
+        self,
+        triples: dict[str, str],
+        metadata_fetcher: MetadataFetcher | None = None,
+        *,
+        floor: str | None = None,
+    ) -> None:
+        self._triples = triples
+        # The default GitHub-backed fetcher is created lazily so tests that
+        # inject a fake never import the network layer.
+        self._fetcher = metadata_fetcher
+        self._floor = floor
+
+    def resolve(
+        self, version: str, archs: tuple[str, ...], *, offline: bool = False
+    ) -> PythonRuntime:
+        if not archs:
+            raise RuntimeProviderError("no architectures requested for the runtime")
+        unknown = [a for a in archs if a not in self._triples]
+        if unknown:
+            valid = ", ".join(sorted(self._triples))
+            raise RuntimeProviderError(
+                f"python-build-standalone has no build for arch(es) {unknown}; "
+                f"valid values are: {valid}."
+            )
+        fetcher = self._fetcher or _default_fetcher()
+        artifacts: list[RuntimeArtifact] = []
+        for arch in archs:
+            triple = self._triples[arch]
+            try:
+                asset = fetcher.fetch(version, triple, offline=offline)
+            except RuntimeProviderError:
+                raise
+            except Exception as exc:  # noqa: BLE001 — normalize fetcher failures
+                raise RuntimeProviderError(
+                    f"could not resolve a python-build-standalone {version} build "
+                    f"for {arch} ({triple}): {exc}"
+                ) from exc
+            artifacts.append(
+                RuntimeArtifact(
+                    arch=arch,
+                    url=asset.url,
+                    sha256=asset.sha256,
+                    archive_format=asset.archive_format,
+                )
+            )
+        return PythonRuntime(
+            provider=self.name,
+            version=version,
+            artifacts=tuple(artifacts),
+            floor=self._floor,
+        )
+
+
+def pbs_asset_glob(version: str, target_triple: str) -> str:
+    """The PBS ``install_only`` archive filename pattern for a version + triple.
+
+    PBS embeds a dated release tag (e.g.
+    ``cpython-3.15.0+20250115-aarch64-apple-darwin-install_only.tar.gz``); this
+    returns the tag-globbed stem the metadata lookup matches.
+    """
+    return f"cpython-{version}+*-{target_triple}-install_only.tar.gz"
+
+
+def _default_fetcher() -> MetadataFetcher:
+    from .pbs_github import GithubPbsMetadataFetcher
+
+    return GithubPbsMetadataFetcher()