kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/ios/lock/builder.py

@@ -0,0 +1,393 @@
+"""Assemble a ``Lockfile`` from a validated ``Config`` (spec 02 §"Resolution semantics")."""
+
+from __future__ import annotations
+
+import dataclasses
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+from kivyforge import __version__
+from kivyforge.artifacts.verify import sha256_file
+from kivyforge.config.model import Config, SwiftPackageDep, XcframeworkDep
+from kivyforge.lock.find_links import (
+    FindLinksError,
+    find_links_resolution_hint,
+    resolve_find_links,
+    validate_find_links,
+    wheel_path_from_project_root,
+)
+from kivyforge.lock.model import (
+    LockedPackage,
+    LockedWheel,
+    PackageDep,
+    canonical_name,
+)
+from kivyforge.lock.reader import compute_pyproject_sha256
+
+from .model import (
+    LockedSwiftPackage,
+    Lockfile,
+    PythonXcframework,
+)
+from .python_meta import PythonOrgProvider, PythonXcframeworkProvider
+from .resolver import Resolver, ResolverError, get_resolver
+from .spm import (
+    ResolvedSwiftPackage,
+    SpmResolver,
+    SpmResolverError,
+    get_spm_resolver,
+)
+from .xcframework import XcframeworkResolverError, resolve_xcframeworks
+
+if TYPE_CHECKING:
+    from kivyforge.artifacts.download import Downloader
+
+
+class BuildError(Exception):
+    """A lock build failure surfaced with an actionable message."""
+
+
+def build_lockfile(
+    config: Config,
+    pyproject_text: str,
+    *,
+    project_root: Path | None = None,
+    resolver: Resolver | None = None,
+    python_provider: PythonXcframeworkProvider | None = None,
+    spm_resolver: SpmResolver | None = None,
+    xcframework_downloader: Downloader | None = None,
+    offline: bool = False,
+    now: datetime | None = None,
+) -> Lockfile:
+    if config.ios is None:
+        raise BuildError(
+            "pyproject.toml has no [tool.kivy.ios] table; nothing to lock."
+        )
+
+    resolver = resolver or get_resolver("pip")
+    python_provider = python_provider or PythonOrgProvider()
+    root = (project_root or Path.cwd()).resolve()
+
+    # [tool.kivy.ios.python].version is required (the loader raises a ConfigError
+    # when it is missing), so it is always set here. Never silently substitute a
+    # hidden default — that would pin an unexpected (and possibly unreleased)
+    # Python instead of surfacing the misconfig.
+    python_version = config.ios.python_version
+    if not python_version:
+        raise BuildError("missing required [tool.kivy.ios.python].version")
+    find_links_entries = config.ios.find_links
+    try:
+        validate_find_links(root, find_links_entries)
+    except FindLinksError as exc:
+        raise BuildError(str(exc)) from exc
+    find_links = resolve_find_links(root, find_links_entries)
+    py_info = python_provider.get(python_version, offline=offline)
+
+    # Rule 11: deployment_target must not be below the xcframework floor.
+    if _version_tuple(config.ios.deployment_target) < _version_tuple(py_info.ios_floor):
+        raise BuildError(
+            f"deployment_target {config.ios.deployment_target} is below the "
+            f"minimum iOS {py_info.ios_floor} required by Python "
+            f"{python_version}'s xcframework.\n"
+            f"  Raise [tool.kivy.ios].deployment_target to at least "
+            f"{py_info.ios_floor}."
+        )
+
+    direct = {canonical_name(_req_name(d)) for d in config.project.dependencies}
+    excluded = {canonical_name(e) for e in config.ios.exclude}
+
+    # Excluded names that are also direct requirements are silently dropped from
+    # the exclusion set — you can't exclude what you explicitly depend on.
+    excluded -= direct
+
+    try:
+        resolved = resolver.resolve(
+            list(config.project.dependencies),
+            python_version=python_version,
+            deployment_target=config.ios.deployment_target,
+            extra_index_urls=list(config.ios.extra_index_urls),
+            find_links=find_links,
+            offline=offline,
+            simulator_archs=tuple(config.ios.simulator_archs),
+        )
+    except ResolverError as exc:
+        hint = find_links_resolution_hint(
+            root,
+            find_links_entries,
+            pip_stderr=str(exc),
+        )
+        if hint:
+            raise BuildError(f"{exc}\n{hint}") from exc
+        raise BuildError(str(exc)) from exc
+
+    packages = []
+    for rp in resolved:
+        if canonical_name(rp.name) in excluded:
+            continue
+        wheels = tuple(
+            _locked_wheel_from_resolved(w, project_root=root) for w in rp.wheels
+        )
+        _check_slices_complete(
+            rp.name,
+            wheels,
+            config.ios.deployment_target,
+            config.ios.simulator_archs,
+        )
+        packages.append(
+            LockedPackage(
+                name=rp.name,
+                version=rp.version,
+                wheels=wheels,
+                requires_python=rp.requires_python,
+                dependencies=tuple(PackageDep(name=d) for d in rp.dependencies),
+                direct_requirement=canonical_name(rp.name) in direct,
+                source_index=rp.source_index,
+            )
+        )
+
+    xcframeworks = _resolve_native_xcframeworks(
+        config.ios.xcframeworks, xcframework_downloader, root, offline
+    )
+
+    swift_packages = _resolve_swift_packages(
+        config.ios.swift_packages, spm_resolver, root, offline
+    )
+
+    return Lockfile(
+        requires_python=config.project.requires_python or ">=3.15",
+        packages=tuple(packages),
+        python_xcframework=PythonXcframework(
+            version=py_info.version, url=py_info.url, sha256=py_info.sha256
+        ),
+        kivyforge_version=__version__,
+        generated_at=(now or datetime.now(UTC)).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        pyproject_sha256=compute_pyproject_sha256(pyproject_text),
+        tool_kivyforge_schema_version=config.ios.schema_version,
+        xcframeworks=tuple(xcframeworks),
+        swift_packages=tuple(swift_packages),
+    )
+
+
+def _resolve_native_xcframeworks(
+    declared: tuple[XcframeworkDep, ...],
+    downloader: Downloader | None,
+    project_root: Path,
+    offline: bool,
+):
+    """Resolve declared native xcframeworks; surface failures as ``BuildError``.
+
+    The resolver fetches/reads each archive, pins its SHA-256, and enumerates the
+    slices it ships, so the lock fully captures user-declared native SDKs instead
+    of silently dropping them.
+    """
+    try:
+        return resolve_xcframeworks(
+            declared,
+            project_root=project_root,
+            downloader=downloader,
+            offline=offline,
+        )
+    except XcframeworkResolverError as exc:
+        raise BuildError(str(exc)) from exc
+
+
+def _resolve_swift_packages(
+    declared: tuple[SwiftPackageDep, ...],
+    spm_resolver: SpmResolver | None,
+    project_root: Path,
+    offline: bool,
+) -> list[LockedSwiftPackage]:
+    """Resolve remote SPM packages to pins; assemble lock entries (sorted by name).
+
+    Local (``path``) packages need no resolution. The resolver is only built and
+    invoked when at least one remote package is declared, so a pure-wheel (or
+    local-only) project never requires the Swift toolchain.
+    """
+    if not declared:
+        return []
+    remote = [p for p in declared if p.url]
+    resolved: dict[str, ResolvedSwiftPackage] = {}
+    if remote:
+        resolver = spm_resolver or get_spm_resolver()
+        try:
+            for r in resolver.resolve(
+                remote, project_root=project_root, offline=offline
+            ):
+                resolved[r.name] = r
+        except SpmResolverError as exc:
+            raise BuildError(str(exc)) from exc
+
+    out: list[LockedSwiftPackage] = []
+    for pkg in declared:
+        pin = resolved.get(pkg.name)
+        if pkg.url and pin is None:
+            raise BuildError(
+                f"swift package {pkg.name!r} resolved to no revision; re-run lock "
+                f"with network access."
+            )
+        out.append(
+            LockedSwiftPackage(
+                name=pkg.name,
+                products=pkg.products,
+                url=pkg.url,
+                path=pkg.path,
+                requirement=pkg.requirement if pkg.url else None,
+                revision=pin.revision if pin else None,
+                version=pin.version if pin else None,
+                link=pkg.link,
+                embed=pkg.embed,
+            )
+        )
+    out.sort(key=lambda s: s.name)
+    return out
+
+
+def _locked_wheel_from_resolved(w, *, project_root: Path) -> LockedWheel:
+    url, path = _normalize_wheel_source(w.url, project_root=project_root)
+    sha256 = w.sha256
+    if not sha256 and path:
+        sha256 = sha256_file((project_root / path).resolve())
+    if not sha256:
+        raise BuildError(
+            f"could not determine SHA-256 for wheel {w.filename!r}; "
+            f"re-run lock with network access or check the vendored file."
+        )
+    return LockedWheel(
+        name=w.filename,
+        url=url,
+        path=path,
+        sha256=sha256,
+        upload_time=w.upload_time,
+        size=w.size,
+    )
+
+
+def _normalize_wheel_source(
+    url: str, *, project_root: Path
+) -> tuple[str | None, str | None]:
+    if url.startswith(("http://", "https://")):
+        return url, None
+    if url.startswith("file:"):
+        # url2pathname turns a file URL path into a native path on every host
+        # (e.g. "/C:/x" -> "C:\\x" on Windows), which plain unquote+Path does not.
+        local = Path(url2pathname(urlparse(url).path))
+    else:
+        local = Path(url)
+    resolved = local.resolve()
+    root = project_root.resolve()
+    try:
+        rel = wheel_path_from_project_root(root, resolved)
+    except FindLinksError as exc:
+        raise BuildError(
+            f"wheel resolved to {resolved}, which is outside the allowed "
+            f"find_links scope for project directory {root}.\n"
+            f"  Vendored wheels must live under the project directory, a "
+            f"sibling directory, or the enclosing repository "
+            f"(e.g. examples/wheels/ios/)."
+        ) from exc
+    return None, rel
+
+
+def _check_slices_complete(
+    name, wheels, deployment_target, simulator_archs=None
+) -> None:
+    """Fail fast if a compiled package is missing an iOS slice (spec 02).
+
+    The required slices are the device slice plus one per configured simulator
+    architecture (``[tool.kivy.ios].simulator_archs``), so a project that drops
+    ``x86_64`` is not held to a slice it no longer targets.
+
+    Compatibility rule: a wheel tagged ios_<M>_<N>_<arch>_<sdk> satisfies a
+    required slice when M.N <= deployment_target AND the arch+sdk suffix
+    matches exactly.  This mirrors select_wheel's logic: python.org's iOS
+    Python binary always tags wheels at its own minimum OS (currently 13.0)
+    regardless of IPHONEOS_DEPLOYMENT_TARGET used when compiling the extension.
+    """
+    if any(w.is_pure_python for w in wheels):
+        return  # pure-Python: single py3-none-any entry is complete
+
+    from .resolver import slice_suffixes
+
+    required = slice_suffixes(simulator_archs)
+    dt_parts = _version_tuple(deployment_target)
+    covered: set[str] = set()
+    for wheel in wheels:
+        tag = wheel.platform_tag  # e.g. "ios_13_0_arm64_iphoneos"
+        parts = tag.split("_")  # ["ios", "13", "0", "arm64", "iphoneos"]
+        if parts[0] != "ios" or len(parts) < 3:
+            continue
+        # Find where the arch+sdk suffix starts (last two underscore-joined segments).
+        for suffix in required:
+            if tag.endswith(f"_{suffix}"):
+                prefix_parts = tag[: -(len(suffix) + 1)].split("_")  # ["ios","13","0"]
+                try:
+                    wheel_ver = tuple(int(x) for x in prefix_parts[1:])
+                except ValueError:
+                    break
+                if wheel_ver <= dt_parts:
+                    covered.add(suffix)
+                break
+
+    missing_suffixes = set(required) - covered
+    if missing_suffixes:
+        dt = deployment_target.replace(".", "_")
+        missing_tags = sorted(f"ios_{dt}_{s}" for s in missing_suffixes)
+        raise BuildError(
+            f"{name} is missing iOS wheel slice(s): {', '.join(missing_tags)}.\n"
+            f"  A compiled package must publish every targeted iOS slice "
+            f"(device + each configured simulator arch) to be locked reproducibly."
+        )
+
+
+def semantic_equal(a: Lockfile, b: Lockfile) -> bool:
+    """Compare two lockfiles ignoring the volatile ``generated_at`` field.
+
+    Used by ``lock --check`` so a re-resolve that produces identical pins (but
+    a new timestamp) still reports "in sync".
+    """
+    return dataclasses.replace(a, generated_at="") == dataclasses.replace(
+        b, generated_at=""
+    )
+
+
+def diff_summary(old: Lockfile, new: Lockfile) -> list[str]:
+    """Human-readable summary of what changed between two locks (for --check)."""
+    out: list[str] = []
+    old_pkgs = {canonical_name(p.name): p for p in old.packages}
+    new_pkgs = {canonical_name(p.name): p for p in new.packages}
+    for name in sorted(new_pkgs.keys() - old_pkgs.keys()):
+        out.append(f"  + {new_pkgs[name].name} {new_pkgs[name].version} (added)")
+    for name in sorted(old_pkgs.keys() - new_pkgs.keys()):
+        out.append(f"  - {old_pkgs[name].name} {old_pkgs[name].version} (removed)")
+    for name in sorted(old_pkgs.keys() & new_pkgs.keys()):
+        if old_pkgs[name].version != new_pkgs[name].version:
+            out.append(
+                f"  ~ {new_pkgs[name].name}: "
+                f"{old_pkgs[name].version} -> {new_pkgs[name].version}"
+            )
+    if old.python_xcframework.version != new.python_xcframework.version:
+        out.append(
+            f"  ~ Python.xcframework: {old.python_xcframework.version} -> "
+            f"{new.python_xcframework.version}"
+        )
+    return out
+
+
+def _req_name(requirement: str) -> str:
+    from packaging.requirements import InvalidRequirement, Requirement
+
+    try:
+        return Requirement(requirement).name
+    except InvalidRequirement:
+        return requirement
+
+
+def _version_tuple(v: str) -> tuple[int, ...]:
+    parts = []
+    for chunk in v.split("."):
+        digits = "".join(c for c in chunk if c.isdigit())
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts)

kivyforge/platforms/ios/lock/markers.py

@@ -0,0 +1,69 @@
+"""The PEP 508 marker environment of the *target*, not the lock host (spec 02).
+
+pip's ``--platform`` decides which wheel *tags* are acceptable. It does **not**
+change how environment markers are evaluated: pip evaluates every
+``; sys_platform == "darwin"``-style marker against the interpreter running
+pip. Because iOS is always cross-resolved from macOS, that silently answers
+every marker as **macOS** — so a dependency gated on ``sys_platform ==
+"darwin"`` is wrongly pulled into an iOS lock, and one gated on
+``sys_platform == "ios"`` is wrongly dropped.
+
+That second case is the dangerous one: nothing fails at lock time, and the app
+is simply missing a dependency at runtime. Unlike the Android equivalent (where
+a Windows host produced a loud "no matching distribution" error), this failure
+is silent on the only supported host, so restricting the workflow to macOS does
+not fix it — the environment has to be described explicitly.
+
+Values follow CPython's own iOS build (PEP 730): ``sys.platform`` is ``"ios"``
+and ``platform.system()`` is ``"iOS"`` on both device and simulator. Markers
+carry no device/simulator distinction — that lives in
+``sys.implementation._multiarch``, which is not a marker name — so the two are
+told apart here only by ``platform_machine``.
+"""
+
+from __future__ import annotations
+
+
+class MarkerEnvironmentError(Exception):
+    """The target marker environment could not be described."""
+
+
+def machine_for_slice(slice_suffix: str) -> str:
+    """``arm64_iphoneos`` -> ``arm64``; ``x86_64_iphonesimulator`` -> ``x86_64``."""
+    if slice_suffix.endswith("_iphoneos"):
+        return slice_suffix[: -len("_iphoneos")]
+    if slice_suffix.endswith("_iphonesimulator"):
+        return slice_suffix[: -len("_iphonesimulator")]
+    raise MarkerEnvironmentError(
+        f"unrecognised iOS slice {slice_suffix!r}; expected an "
+        "``<arch>_iphoneos`` or ``<arch>_iphonesimulator`` suffix."
+    )
+
+
+def ios_marker_environment(*, python_version: str, slice_suffix: str) -> dict[str, str]:
+    """The PEP 508 environment a wheel would see on the given iOS slice.
+
+    ``python_version`` is the full runtime version (e.g. ``3.14.6``).
+    """
+    machine = machine_for_slice(slice_suffix)
+    parts = python_version.split(".")
+    if len(parts) < 2:
+        raise MarkerEnvironmentError(
+            f"python version {python_version!r} is not a full X.Y.Z version; "
+            "cannot describe the target marker environment."
+        )
+    return {
+        "implementation_name": "cpython",
+        "implementation_version": python_version,
+        "os_name": "posix",
+        "platform_machine": machine,
+        "platform_python_implementation": "CPython",
+        # Device kernel details are unknowable at lock time, and no sane wheel
+        # gates on them.
+        "platform_release": "",
+        "platform_system": "iOS",
+        "platform_version": "",
+        "python_full_version": python_version,
+        "python_version": ".".join(parts[:2]),
+        "sys_platform": "ios",
+    }

kivyforge/platforms/ios/lock/model.py

@@ -0,0 +1,95 @@
+"""In-memory model of ``pylock.ios.toml`` (spec 02).
+
+PEP 751-shaped ``[[packages]]`` plus the iOS ``[tool.kivyforge]`` extension
+(``python_xcframework``, xcframeworks, swift_packages). These dataclasses are
+produced by the builder/resolver and serialized by ``writer``. The shared
+``[[packages]]`` model (``LockedPackage``/``LockedWheel``) lives in
+``kivyforge.lock.model``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from kivyforge.lock.model import LOCK_VERSION, LockedPackage
+
+CREATED_BY = "kivyforge"
+TOOL_SCHEMA_VERSION = 1
+DEFAULT_REQUIRES_PYTHON = ">=3.15"
+
+
+@dataclass(frozen=True)
+class PythonXcframework:
+    version: str
+    url: str
+    sha256: str
+
+
+@dataclass(frozen=True)
+class LockedXcframework:
+    """One ``[[tool.kivyforge.xcframeworks]]`` entry."""
+
+    name: str
+    version: str
+    sha256: str
+    slices: tuple[str, ...]
+    url: str | None = None
+    path: str | None = None
+    archive_format: str = "zip"
+    archive_member: str | None = None
+    privacy_manifest_path: str | None = None
+    link: bool = True
+    embed: bool = True
+    source: str | None = None
+
+    def __post_init__(self) -> None:
+        if bool(self.url) == bool(self.path):
+            raise ValueError(
+                f"xcframework {self.name!r} must have exactly one of url/path"
+            )
+
+
+@dataclass(frozen=True)
+class LockedSwiftPackage:
+    """One ``[[tool.kivyforge.swift_packages]]`` entry (spec 07).
+
+    Unlike xcframeworks, kivyforge computes no output hash here: Xcode owns the
+    SPM lifecycle, so reproducibility is the pinned ``revision`` (+ the generated
+    ``Package.resolved``). Exactly one of ``url`` (remote) or ``path`` (local) is
+    set; ``requirement``/``revision``/``version`` are remote-only.
+    """
+
+    name: str
+    products: tuple[str, ...]
+    url: str | None = None
+    path: str | None = None
+    requirement: dict[str, object] | None = None
+    revision: str | None = None
+    version: str | None = None
+    link: bool = True
+    embed: bool = True
+
+    def __post_init__(self) -> None:
+        if bool(self.url) == bool(self.path):
+            raise ValueError(
+                f"swift package {self.name!r} must have exactly one of url/path"
+            )
+
+
+@dataclass(frozen=True)
+class Lockfile:
+    requires_python: str
+    packages: tuple[LockedPackage, ...]
+    python_xcframework: PythonXcframework
+    kivyforge_version: str
+    generated_at: str
+    pyproject_sha256: str
+    tool_kivyforge_schema_version: int
+    xcframeworks: tuple[LockedXcframework, ...] = ()
+    swift_packages: tuple[LockedSwiftPackage, ...] = ()
+    schema_version: int = TOOL_SCHEMA_VERSION
+    lock_version: str = LOCK_VERSION
+    created_by: str = CREATED_BY
+    extras: tuple[str, ...] = ()
+    dependency_groups: tuple[str, ...] = ()
+    default_groups: tuple[str, ...] = ()