kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/ios/lock/python_meta.py

@@ -0,0 +1,187 @@
+"""Resolve ``Python.xcframework`` metadata for the lock (spec 02 §python_xcframework).
+
+``kivyforge lock`` records the pinned Python.xcframework's URL + SHA-256 and
+uses its declared iOS floor to validate ``deployment_target`` (spec 01 rule
+11). The provider is an injection point so unit tests stay offline.
+
+The iOS deployment floor is read directly from ``Python.xcframework/Info.plist``
+inside the downloaded archive, so no per-version table needs manual maintenance.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import plistlib
+import tarfile
+import tempfile
+import time
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.verify import sha256_file
+
+# python.org publishes the official iOS xcframework from 3.15.0b1 onward.
+PYTHON_ORG_URL = "https://www.python.org/ftp/python/{version}/python-{version}-iOS-XCframework.tar.gz"
+
+_DOWNLOAD_ATTEMPTS = 4
+_RETRY_BACKOFF_SEC = (1.0, 2.0, 4.0)
+# Returned when the Info.plist is absent or cannot be parsed.
+_IOS_FLOOR_FALLBACK = "13.0"
+
+
+def python_org_ios_url(version: str) -> str:
+    """Return the python.org FTP URL for an iOS ``Python.xcframework`` archive.
+
+    Pre-releases (``3.15.0b2``, ``3.15.0rc1``, …) live under the base
+    ``/ftp/python/3.Y.0/`` directory; final releases use ``/ftp/python/X.Y.Z/``.
+    """
+    if _is_prerelease(version):
+        base = ".".join(version.split(".")[:2]) + ".0"
+        return (
+            f"https://www.python.org/ftp/python/{base}/"
+            f"python-{version}-iOS-XCframework.tar.gz"
+        )
+    return PYTHON_ORG_URL.format(version=version)
+
+
+def archive_filename(version: str) -> str:
+    return f"python-{version}-iOS-XCframework.tar.gz"
+
+
+def _is_prerelease(version: str) -> bool:
+    tail = version.split(".")[-1]
+    return any(tag in tail for tag in ("a", "b", "rc"))
+
+
+def read_ios_floor(archive_path: str | Path) -> str:
+    """Read ``MinimumOSVersion`` from ``Python.xcframework/Info.plist`` inside the tarball.
+
+    The XCFramework Info.plist carries an ``AvailableLibraries`` array; each
+    entry has a ``LibraryIdentifier`` (e.g. ``"ios-arm64"``) and a
+    ``MinimumOSVersion`` string.  We return the value for the ``ios-arm64``
+    slice, which is the device floor that kivyforge validates against.
+
+    Returns ``_IOS_FLOOR_FALLBACK`` if the plist is absent, malformed, or the
+    archive is not a valid tarball (e.g. a test fixture).
+    """
+    try:
+        with open(archive_path, "rb") as f:
+            return _read_ios_floor_from_fileobj(f)
+    except OSError:
+        return _IOS_FLOOR_FALLBACK
+
+
+def _read_ios_floor_from_fileobj(fileobj) -> str:
+    """Same as :func:`read_ios_floor`, but reads an already-open, seekable file.
+
+    ``_download`` reads it via its own live ``NamedTemporaryFile`` handle
+    rather than reopening the path — reopening a still-open ``NamedTemporaryFile``
+    by name is a documented POSIX-only guarantee (it silently fails on Windows).
+    """
+    try:
+        with tarfile.open(fileobj=fileobj, mode="r:gz") as tf:
+            for member in tf.getmembers():
+                if not member.name.endswith("Python.xcframework/Info.plist"):
+                    continue
+                f = tf.extractfile(member)
+                if f is None:
+                    continue
+                info = plistlib.load(f)
+                for lib in info.get("AvailableLibraries", []):
+                    if "ios-arm64" in lib.get("LibraryIdentifier", ""):
+                        return lib["MinimumOSVersion"]
+    except Exception:  # noqa: BLE001 — malformed archive, old format, etc.
+        pass
+    return _IOS_FLOOR_FALLBACK
+
+
+@dataclass(frozen=True)
+class PythonXcframeworkInfo:
+    version: str
+    url: str
+    sha256: str
+    ios_floor: str
+
+
+class PythonXcframeworkProvider(Protocol):
+    def get(self, version: str, *, offline: bool = False) -> PythonXcframeworkInfo: ...
+
+
+class PythonOrgProvider:
+    """Default provider: build the python.org URL and hash the artifact."""
+
+    def __init__(
+        self,
+        *,
+        url_template: str = PYTHON_ORG_URL,
+        cache: ArtifactCache | None = None,
+    ) -> None:
+        self._url_template = url_template
+        self._cache = cache or ArtifactCache()
+
+    def get(self, version: str, *, offline: bool = False) -> PythonXcframeworkInfo:
+        url = (
+            python_org_ios_url(version)
+            if self._url_template == PYTHON_ORG_URL
+            else self._url_template.format(version=version)
+        )
+        sha256, floor = self._resolve(url, version, offline=offline)
+        return PythonXcframeworkInfo(
+            version=version,
+            url=url,
+            sha256=sha256,
+            ios_floor=floor,
+        )
+
+    def _resolve(self, url: str, version: str, *, offline: bool) -> tuple[str, str]:
+        """Return ``(sha256, ios_floor)`` from cache or by downloading."""
+        filename = archive_filename(version)
+        cached = self._cache.find_by_filename(filename)
+        if cached is not None:
+            return sha256_file(cached), read_ios_floor(cached)
+
+        if offline:
+            raise PythonXcframeworkError(
+                f"Python.xcframework {version} is not in the artifact cache "
+                f"({filename}).\n"
+                f"  Run `kivyforge lock` online once, or `kivyforge build` to "
+                f"populate the cache, then retry with --offline."
+            )
+
+        return self._download(url, version)
+
+    def _download(self, url: str, version: str) -> tuple[str, str]:
+        """Download the archive; return ``(sha256, ios_floor)``."""
+        last_exc: OSError | None = None
+        for attempt in range(_DOWNLOAD_ATTEMPTS):
+            try:
+                digest = hashlib.sha256()
+                with tempfile.NamedTemporaryFile(suffix=".tar.gz") as tmp:
+                    with urllib.request.urlopen(url) as resp:  # noqa: S310
+                        for chunk in iter(lambda: resp.read(1 << 20), b""):
+                            digest.update(chunk)
+                            tmp.write(chunk)
+                    tmp.flush()
+                    tmp.seek(0)
+                    floor = _read_ios_floor_from_fileobj(tmp)
+                return digest.hexdigest(), floor
+            except OSError as exc:
+                last_exc = exc
+                if attempt < _DOWNLOAD_ATTEMPTS - 1:
+                    time.sleep(
+                        _RETRY_BACKOFF_SEC[min(attempt, len(_RETRY_BACKOFF_SEC) - 1)]
+                    )
+        assert last_exc is not None
+        raise PythonXcframeworkError(
+            f"could not fetch Python.xcframework {version} from {url}: {last_exc}\n"
+            f"  Check the version exists on python.org (3.15.0b1+) and that "
+            f"you are online. Transient network/SSL errors are retried "
+            f"{_DOWNLOAD_ATTEMPTS} times."
+        ) from last_exc
+
+
+class PythonXcframeworkError(Exception):
+    pass

kivyforge/platforms/ios/lock/reader.py

@@ -0,0 +1,191 @@
+"""Parse ``pylock.ios.toml`` back into a ``Lockfile`` and detect drift (spec 02).
+
+The neutral drift helpers (``LockError``, ``compute_pyproject_sha256``,
+``is_in_sync``) live in ``kivyforge.lock.reader``; this module adds the iOS
+``pylock.ios.toml`` parsing on top.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from kivyforge.lock.pep751 import parse_package as _parse_package
+from kivyforge.lock.reader import (
+    LockError,
+    compute_pyproject_sha256,
+    is_in_sync,
+)
+
+from .model import (
+    LOCK_VERSION,
+    TOOL_SCHEMA_VERSION,
+    LockedSwiftPackage,
+    LockedXcframework,
+    Lockfile,
+    PythonXcframework,
+)
+
+__all__ = [
+    "LockError",
+    "compute_pyproject_sha256",
+    "is_in_sync",
+    "load",
+    "loads",
+]
+
+# Highest major lock-version (PEP 751 top-level) this reader accepts.
+SUPPORTED_LOCK_VERSION_MAJOR = int(LOCK_VERSION.split(".", 1)[0])
+# Highest [tool.kivyforge].schema_version (the extension's own schema) accepted.
+SUPPORTED_TOOL_SCHEMA_VERSION = TOOL_SCHEMA_VERSION
+
+
+def loads(text: str) -> Lockfile:
+    """Parse ``pylock.ios.toml`` text into a ``Lockfile``.
+
+    ``kivyforge lock`` is the writer, so the reader's job is to fail *cleanly*
+    when the file is corrupt, hand-edited, or from a future schema — never to
+    leak a raw ``KeyError``/``TypeError``. Every shape failure surfaces as
+    ``LockError``.
+    """
+    try:
+        raw = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise LockError(f"pylock.ios.toml is not valid TOML: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise LockError("pylock.ios.toml must be a TOML table.")
+    try:
+        return _from_raw(raw)
+    except LockError:
+        raise
+    except (KeyError, TypeError, AttributeError, ValueError) as exc:
+        # A missing/mistyped field anywhere in the tree — name the trigger but
+        # don't leak the raw exception type to callers.
+        raise LockError(f"pylock.ios.toml is malformed: {exc!r}") from exc
+
+
+def load(path: str | Path) -> Lockfile:
+    return loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _from_raw(raw: dict) -> Lockfile:
+    lock_version = _check_lock_version(raw)
+
+    tool_raw = raw.get("tool", {})
+    if not isinstance(tool_raw, dict):
+        raise LockError("pylock.ios.toml [tool] must be a table.")
+    tool = tool_raw.get("kivyforge", {})
+    if not isinstance(tool, dict) or not tool:
+        raise LockError("pylock.ios.toml is missing the [tool.kivyforge] table.")
+
+    schema_version = _check_tool_schema_version(tool)
+    python_xcframework = _parse_python_xcframework(tool)
+
+    packages = tuple(_parse_package(p) for p in _as_list(raw, "packages"))
+    xcframeworks = tuple(_parse_xcframework(x) for x in _as_list(tool, "xcframeworks"))
+    swift_packages = tuple(
+        _parse_swift_package(s) for s in _as_list(tool, "swift_packages")
+    )
+
+    return Lockfile(
+        requires_python=raw.get("requires-python", ">=3.15"),
+        packages=packages,
+        python_xcframework=python_xcframework,
+        kivyforge_version=tool.get("kivyforge_version", ""),
+        generated_at=tool.get("generated_at", ""),
+        pyproject_sha256=tool.get("pyproject_sha256", ""),
+        tool_kivyforge_schema_version=tool.get("tool_kivyforge_schema_version", 1),
+        xcframeworks=xcframeworks,
+        swift_packages=swift_packages,
+        schema_version=schema_version,
+        lock_version=lock_version,
+        created_by=raw.get("created-by", "kivyforge"),
+        extras=tuple(raw.get("extras", [])),
+        dependency_groups=tuple(raw.get("dependency-groups", [])),
+        default_groups=tuple(raw.get("default-groups", [])),
+    )
+
+
+def _check_lock_version(raw: dict) -> str:
+    lock_version = raw.get("lock-version", LOCK_VERSION)
+    if not isinstance(lock_version, str):
+        raise LockError("pylock.ios.toml lock-version must be a string.")
+    major = lock_version.split(".", 1)[0]
+    if not major.isdigit():
+        raise LockError(
+            f"pylock.ios.toml lock-version {lock_version!r} is not a valid version."
+        )
+    if int(major) > SUPPORTED_LOCK_VERSION_MAJOR:
+        raise LockError(
+            f"pylock.ios.toml lock-version {lock_version} is newer than this "
+            f"kivyforge understands (max {SUPPORTED_LOCK_VERSION_MAJOR}.x). "
+            "Upgrade kivyforge."
+        )
+    return lock_version
+
+
+def _check_tool_schema_version(tool: dict) -> int:
+    schema_version = tool.get("schema_version", SUPPORTED_TOOL_SCHEMA_VERSION)
+    if not isinstance(schema_version, int) or isinstance(schema_version, bool):
+        raise LockError("[tool.kivyforge].schema_version must be an integer.")
+    if schema_version > SUPPORTED_TOOL_SCHEMA_VERSION:
+        raise LockError(
+            f"[tool.kivyforge].schema_version {schema_version} is newer than this "
+            f"kivyforge understands (max {SUPPORTED_TOOL_SCHEMA_VERSION}). "
+            "Upgrade kivyforge."
+        )
+    return schema_version
+
+
+def _parse_python_xcframework(tool: dict) -> PythonXcframework:
+    px = tool.get("python_xcframework")
+    if not isinstance(px, dict) or not px:
+        raise LockError(
+            "pylock.ios.toml is missing [tool.kivyforge.python_xcframework]."
+        )
+    for field in ("version", "url", "sha256"):
+        value = px.get(field)
+        if not isinstance(value, str) or not value:
+            raise LockError(
+                f"[tool.kivyforge.python_xcframework].{field} is missing or empty."
+            )
+    return PythonXcframework(version=px["version"], url=px["url"], sha256=px["sha256"])
+
+
+def _as_list(table: dict, key: str) -> list:
+    value = table.get(key, [])
+    if not isinstance(value, list):
+        raise LockError(f"pylock.ios.toml {key!r} must be an array of tables.")
+    return value
+
+
+def _parse_xcframework(x: dict) -> LockedXcframework:
+    return LockedXcframework(
+        name=x["name"],
+        version=x["version"],
+        sha256=x.get("sha256", ""),
+        slices=tuple(x.get("slices", [])),
+        url=x.get("url"),
+        path=x.get("path"),
+        archive_format=x.get("archive_format", "zip"),
+        archive_member=x.get("archive_member"),
+        privacy_manifest_path=x.get("privacy_manifest_path"),
+        link=bool(x.get("link", True)),
+        embed=bool(x.get("embed", True)),
+        source=x.get("source"),
+    )
+
+
+def _parse_swift_package(s: dict) -> LockedSwiftPackage:
+    requirement = s.get("requirement")
+    return LockedSwiftPackage(
+        name=s["name"],
+        products=tuple(s.get("products", [])),
+        url=s.get("url"),
+        path=s.get("path"),
+        requirement=dict(requirement) if requirement else None,
+        revision=s.get("revision"),
+        version=s.get("version"),
+        link=bool(s.get("link", True)),
+        embed=bool(s.get("embed", True)),
+    )

kivyforge/platforms/ios/lock/resolver.py

@@ -0,0 +1,304 @@
+"""iOS dependency resolver (spec 02 §"Resolution semantics").
+
+The resolver turns ``[project].dependencies`` into a fully-pinned set of
+per-slice iOS wheels, **host-independent** — every compiled package is pinned
+for the device slice (arm64) plus one slice per configured simulator
+architecture, regardless of the architecture of the host running ``lock``. The
+simulator architectures default to ``arm64`` + ``x86_64`` and are configurable
+via ``[tool.kivy.ios].simulator_archs`` (a project that no longer needs the
+Intel-host simulator can drop ``x86_64``).
+
+Host-independence covers *marker evaluation*, not just wheel tags. pip's
+``--platform`` selects acceptable tags but leaves ``sys_platform`` and friends
+describing the macOS host running pip, which would wrongly admit
+``sys_platform == "darwin"`` dependencies and — silently — drop
+``sys_platform == "ios"`` ones. Resolution therefore runs through
+``lock/_pip_shim.py``, which retargets ``packaging``'s marker environment at
+the iOS slice (see ``markers.py``) before handing off to pip.
+
+``pip`` is the backend (validated by the Phase 0 spike: see
+docs/dev/resolver-findings.md). The backend is abstracted behind the
+``Resolver`` protocol so unit tests can inject a fake resolver and stay hermetic.
+The platform-neutral pip helpers are shared from ``kivyforge.lock.resolver``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from kivyforge.lock import _pip_shim
+from kivyforge.lock._pip_shim import MARKER_ENV_VAR
+from kivyforge.lock.model import canonical_name
+from kivyforge.lock.resolver import (
+    MIN_PIP_VERSION,
+    abi_tags,
+    dep_names_for_environment,
+    pip_python_version,
+    pip_version,
+    version_str,
+)
+
+from .markers import ios_marker_environment
+
+# Run by path, not ``-m``: the shim imports nothing from kivyforge, so it also
+# works when resolving with an interpreter that only has pip installed.
+_SHIM = Path(_pip_shim.__file__)
+
+# iOS build slices (spec 02). The device slice is always arm64 — there is no
+# 32-bit iOS — while the simulator slices are driven by the project's configured
+# simulator architectures. ``DEFAULT_SIMULATOR_ARCHS`` mirrors
+# ``config.model.DEFAULT_SIMULATOR_ARCHS``; the builder always passes the
+# validated config value, so this default only serves direct/test callers. Tag
+# templates are formatted with the deployment target (dots -> underscores).
+DEVICE_SLICE_SUFFIX = "arm64_iphoneos"
+DEFAULT_SIMULATOR_ARCHS = ("arm64", "x86_64")
+
+
+class ResolverError(Exception):
+    """A resolution failure (missing slice, no matching wheel, backend error)."""
+
+
+@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
+
+
+def slice_suffixes(
+    simulator_archs: tuple[str, ...] | None = None,
+) -> tuple[str, ...]:
+    """The arch+sdk suffixes for the slices a build targets.
+
+    Always the device slice (arm64) plus one simulator slice per configured
+    simulator architecture. Single source of truth for both ``slice_tags`` (lock
+    resolution) and the builder's slice-coverage check.
+    """
+    archs = simulator_archs if simulator_archs is not None else DEFAULT_SIMULATOR_ARCHS
+    return (DEVICE_SLICE_SUFFIX, *(f"{arch}_iphonesimulator" for arch in archs))
+
+
+def slice_tags(
+    deployment_target: str,
+    simulator_archs: tuple[str, ...] | None = None,
+) -> tuple[str, ...]:
+    dt = deployment_target.replace(".", "_")
+    return tuple(f"ios_{dt}_{suffix}" for suffix in slice_suffixes(simulator_archs))
+
+
+class Resolver(Protocol):
+    def resolve(
+        self,
+        requirements: list[str],
+        *,
+        python_version: str,
+        deployment_target: str,
+        extra_index_urls: list[str],
+        find_links: list[str] | None = None,
+        offline: bool = False,
+        simulator_archs: tuple[str, ...] | None = None,
+    ) -> list[ResolvedPackage]:
+        """Resolve requirements to per-slice iOS wheels (all slices pinned)."""
+        ...
+
+
+class PipResolver:
+    """Default backend: stock pip cross-resolution via ``pip install --report``.
+
+    For each iOS slice we run pip in dry-run report mode with the slice's
+    platform tag; the JSON report yields each resolved wheel's URL + sha256.
+    Results are merged across slices into one ``ResolvedPackage`` per
+    distribution. A package missing any compiled slice raises ``ResolverError``
+    (fail fast at lock time, host-independent).
+    """
+
+    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,
+        deployment_target: str,
+        extra_index_urls: list[str],
+        find_links: list[str] | None = None,
+        offline: bool = False,
+        simulator_archs: tuple[str, ...] | None = None,
+    ) -> list[ResolvedPackage]:
+        if not requirements:
+            return []
+        self._require_modern_pip()
+        suffixes = slice_suffixes(simulator_archs)
+        tags = slice_tags(deployment_target, simulator_archs)
+        abis = abi_tags(python_version)
+        # name -> ResolvedPackage (merged across slices)
+        merged: dict[str, ResolvedPackage] = {}
+        seen_filenames: dict[str, set[str]] = {}
+
+        for suffix, tag in zip(suffixes, tags):
+            # Markers are evaluated for the *target* slice, not the macOS host
+            # running pip (see markers.py); platform_machine differs between
+            # the arm64 and x86_64 simulator slices.
+            environment = ios_marker_environment(
+                python_version=python_version, slice_suffix=suffix
+            )
+            report = self._run_report(
+                requirements,
+                python_version=python_version,
+                platform_tag=tag,
+                abis=abis,
+                extra_index_urls=extra_index_urls,
+                find_links=find_links or [],
+                offline=offline,
+                marker_environment=environment,
+            )
+            for item in report.get("install", []):
+                self._absorb(item, merged, seen_filenames, environment)
+
+        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 ResolverError(
+                f"kivyforge needs pip >= {version_str(MIN_PIP_VERSION)} to resolve "
+                f"iOS wheels, but {self._python} has pip {version_str(version)}.\n"
+                "  pip < 24.3 predates PEP 730 iOS platform tags, so compatible "
+                "wheels (e.g. ios_13_0_*) are reported as missing.\n"
+                f"  Upgrade it: {self._python} -m pip install --upgrade pip"
+            )
+
+    def _absorb(self, item, merged, seen_filenames, environment) -> 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"):
+            # sdist/vcs/directory are refused (spec 02): wheels only.
+            raise ResolverError(
+                f"{name} {version} resolved to a non-wheel source ({url}); "
+                "kivyforge installs only iOS wheels (no on-device 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_for_environment(
+                    meta.get("requires_dist", []), environment
+                ),
+            )
+            merged[key] = pkg
+            seen_filenames[key] = set()
+        elif version != pkg.version:
+            # pip resolves each iOS slice independently; if upstream only
+            # published some slices for a release, a later slice can resolve to
+            # a different version. Merging those would silently produce a
+            # lockfile that looks pinned but installs mismatched binaries across
+            # device and simulator. Fail fast, like the missing-slice case.
+            raise ResolverError(
+                f"{name} resolved to inconsistent versions across iOS slices: "
+                f"{pkg.version!r} and {version!r}. This usually means the slices "
+                "were published at different times upstream; kivyforge requires "
+                "every slice of a package to 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_tag: str,
+        abis: tuple[str, ...],
+        extra_index_urls: list[str],
+        find_links: list[str],
+        offline: bool,
+        marker_environment: dict[str, str],
+    ) -> dict:
+        with tempfile.TemporaryDirectory(prefix="kivy-lock-") as tmp:
+            report_path = Path(tmp) / "report.json"
+            # Not "-m pip": the shim retargets marker evaluation at the iOS
+            # slice first, then runs pip unchanged (see lock/_pip_shim.py).
+            cmd = [
+                self._python,
+                str(_SHIM),
+                "install",
+                "--dry-run",
+                "--ignore-installed",
+                "--only-binary=:all:",
+                "--python-version",
+                pip_python_version(python_version),
+                "--implementation",
+                "cp",
+                "--platform",
+                platform_tag,
+                "--target",
+                str(Path(tmp) / "target"),
+                "--report",
+                str(report_path),
+            ]
+            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)
+
+            env = dict(os.environ)
+            env[MARKER_ENV_VAR] = json.dumps(marker_environment)
+            proc = subprocess.run(cmd, capture_output=True, text=True, env=env)
+            if proc.returncode != 0:
+                raise ResolverError(
+                    f"pip could not resolve the iOS slice {platform_tag!r}.\n"
+                    f"  This usually means a dependency has no wheel for that "
+                    f"slice upstream.\n  pip said:\n{_indent(proc.stderr or proc.stdout)}"
+                )
+            try:
+                # pip writes the report as UTF-8; never trust the locale codec
+                # (cp1252 on Windows chokes on non-ASCII package metadata).
+                return json.loads(report_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError) as exc:
+                raise ResolverError(f"could not read pip report: {exc}") from exc
+
+
+def get_resolver(backend: str = "pip", **kwargs) -> Resolver:
+    if backend == "pip":
+        return PipResolver(**kwargs)
+    raise ResolverError(f"unknown resolver backend {backend!r} (expected pip)")
+
+
+def _indent(text: str) -> str:
+    return "\n".join(f"    {line}" for line in (text or "").splitlines())