kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/__init__.py

@@ -0,0 +1,9 @@
+"""kivyforge: a declarative iOS bundler for Kivy apps.
+
+kivyforge 3.0 reads a user-authored ``pyproject.toml`` (PEP 621 ``[project]``
+plus ``[tool.kivy]`` / ``[tool.kivy.ios]``), resolves a PEP 751
+``pylock.ios.toml`` build manifest, and materializes it into a generated
+Xcode project. See ``docs/proposals`` for the full specification.
+"""
+
+__version__ = "3.0.0.dev0"

kivyforge/artifacts/__init__.py

@@ -0,0 +1,41 @@
+"""kivyforge artifact layer: fetch/cache/verify, wheels, frameworks, runtimes (spec 03)."""
+
+from __future__ import annotations
+
+from .cache import ArtifactCache
+from .download import Downloader, DownloadError, UrllibDownloader, fetch_artifact
+from .frameworks import (
+    FrameworkConflict,
+    copy_wheel_frameworks,
+    extract_xcframework_archive,
+)
+from .runtime import (
+    PythonOrgRuntime,
+    PythonRuntime,
+    RuntimeArtifact,
+    get_runtime,
+)
+from .verify import HashMismatch, sha256_bytes, sha256_file, verify_file
+from .wheels import BuildSlice, WheelSelectionError, select_wheel
+
+__all__ = [
+    "ArtifactCache",
+    "DownloadError",
+    "Downloader",
+    "UrllibDownloader",
+    "fetch_artifact",
+    "FrameworkConflict",
+    "copy_wheel_frameworks",
+    "extract_xcframework_archive",
+    "PythonOrgRuntime",
+    "PythonRuntime",
+    "RuntimeArtifact",
+    "get_runtime",
+    "HashMismatch",
+    "sha256_bytes",
+    "sha256_file",
+    "verify_file",
+    "BuildSlice",
+    "WheelSelectionError",
+    "select_wheel",
+]

kivyforge/artifacts/cache.py

@@ -0,0 +1,81 @@
+"""Content-addressed artifact cache (spec 03).
+
+Artifacts (wheels, xcframework archives, Python.xcframework) are cached by
+SHA-256 in a per-user, OS-appropriate cache directory so repeated builds and
+``--no-cache`` opt-outs are cheap and deterministic. The cache key is the
+content hash, so a tampered/replaced upstream artifact can never silently
+satisfy a cache hit for a different hash.
+
+The cache root follows each host's convention: ``~/Library/Caches/kivyforge``
+on macOS, ``$XDG_CACHE_HOME/kivyforge`` (default ``~/.cache/kivyforge``) on
+Linux and other Unixes, and ``%LOCALAPPDATA%\\kivyforge\\Cache`` on Windows.
+"""
+
+from __future__ import annotations
+
+import os
+import platform as _platform
+import shutil
+from pathlib import Path
+
+APP_NAME = "kivyforge"
+
+
+def _default_cache_root() -> Path:
+    """The per-user artifact cache directory for the current host OS."""
+    system = _platform.system()
+    if system == "Darwin":
+        return Path.home() / "Library" / "Caches" / APP_NAME / "artifacts"
+    if system == "Windows":
+        base = os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local")
+        return Path(base) / APP_NAME / "Cache" / "artifacts"
+    # Linux and other Unixes: the XDG Base Directory spec.
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    base = Path(xdg) if xdg else (Path.home() / ".cache")
+    return base / APP_NAME / "artifacts"
+
+
+DEFAULT_CACHE_ROOT = _default_cache_root()
+
+
+class ArtifactCache:
+    def __init__(self, root: str | Path | None = None) -> None:
+        self.root = DEFAULT_CACHE_ROOT if root is None else Path(root)
+
+    def path_for(self, sha256: str, filename: str) -> Path:
+        # Shard by the first two hex chars to keep directories small.
+        return self.root / sha256[:2] / f"{sha256}-{filename}"
+
+    def get(self, sha256: str, filename: str) -> Path | None:
+        candidate = self.path_for(sha256, filename)
+        return candidate if candidate.is_file() else None
+
+    def find_by_filename(self, filename: str) -> Path | None:
+        """Return a cached artifact path matching ``{sha256}-{filename}``, if any."""
+        if not self.root.is_dir():
+            return None
+        suffix = f"-{filename}"
+        for shard in self.root.iterdir():
+            if not shard.is_dir():
+                continue
+            for path in shard.iterdir():
+                if path.is_file() and path.name.endswith(suffix):
+                    return path
+        return None
+
+    def put_file(self, src: str | Path, sha256: str, filename: str) -> Path:
+        dest = self.path_for(sha256, filename)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        if not dest.is_file():
+            shutil.copyfile(src, dest)
+        return dest
+
+    def put_bytes(self, data: bytes, sha256: str, filename: str) -> Path:
+        dest = self.path_for(sha256, filename)
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(data)
+        return dest
+
+    def clear(self) -> None:
+        if self.root.is_dir():
+            shutil.rmtree(self.root)

kivyforge/artifacts/collect.py

@@ -0,0 +1,354 @@
+"""Collect lockfile artifacts into the staging tree (build steps 2-5, spec 06).
+
+Downloads/verifies the Python.xcframework, installs pinned wheels into
+``pip-deps/``, copies wheel-embedded ``.frameworks/`` into ``Frameworks/``, and
+extracts user-declared native xcframeworks. The subprocess runner is injectable
+so the orchestration can be unit-tested without invoking pip.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+
+from ..bundle.pycompile import PycompileError, byte_compile, select_compiler
+from ..config.model import DesktopBuildSettings
+from ..lock.model import LockedWheel
+from ..platforms.ios.lock.model import Lockfile
+from .cache import ArtifactCache
+from .download import Downloader, fetch_artifact
+from .frameworks import (
+    PlacedFramework,
+    copy_wheel_frameworks,
+    extract_xcframework_archive,
+)
+from .wheels import BuildSlice, select_wheel
+
+
+class CollectError(Exception):
+    pass
+
+
+def pip_install_command(
+    wheel_files: list[str],
+    *,
+    target_dir: str,
+    platform_tag: str,
+    python_version: str,
+    abi: str,
+    python_executable: str | None = None,
+) -> list[str]:
+    """Build the pip cross-install command (spec 05 step 4); no re-resolution."""
+    py = python_executable or sys.executable
+    cmd = [
+        py,
+        "-m",
+        "pip",
+        "install",
+        "--no-deps",
+        "--only-binary=:all:",
+        "--platform",
+        platform_tag,
+        "--python-version",
+        python_version,
+        "--abi",
+        abi,
+        "--implementation",
+        "cp",
+        "--target",
+        target_dir,
+    ]
+    cmd += wheel_files
+    return cmd
+
+
+def collect_artifacts(
+    lock: Lockfile,
+    layout,
+    *,
+    build_slices: list[BuildSlice],
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    downloader: Downloader | None = None,
+    no_cache: bool = False,
+    runner=subprocess.run,
+    python_executable: str | None = None,
+    release: bool = False,
+    build_settings: DesktopBuildSettings | None = None,
+    echo: Callable[[str], None] = lambda msg: None,
+) -> None:
+    cache = cache or ArtifactCache()
+
+    # Python.xcframework is multi-slice and slice-independent, so it is fetched
+    # once regardless of how many pip-deps slices we populate. pip-deps itself is
+    # installed per slice (device/simulator never share .so files): a bare
+    # `kivyforge build` passes both slices so either Xcode destination builds
+    # without a re-run, while a targeted build passes only its slice.
+    _install_python_xcframework(
+        lock, layout, cache=cache, downloader=downloader, no_cache=no_cache
+    )
+    # Wheel-embedded frameworks are multi-slice xcframeworks; union them across
+    # slices (dedup by name) so user-declared natives below don't clobber them.
+    # Shared registry of staged frameworks (name -> provenance + content hash).
+    # Threaded across every pip-deps slice and into native xcframework
+    # extraction so identical duplicates dedupe and conflicting ones fail loudly.
+    staged: dict[str, PlacedFramework] = {}
+    for build_slice in build_slices:
+        slice_pip_deps = layout.pip_deps_for_slice(build_slice.target)
+        _install_wheels(
+            lock,
+            layout,
+            slice_pip_deps=slice_pip_deps,
+            build_slice=build_slice,
+            project_root=project_root,
+            cache=cache,
+            downloader=downloader,
+            no_cache=no_cache,
+            runner=runner,
+            python_executable=python_executable,
+        )
+        _compile_pip_deps(
+            slice_pip_deps,
+            python_version=lock.python_xcframework.version,
+            release=release,
+            build_settings=build_settings,
+            echo=echo,
+        )
+        _stamp_collected(slice_pip_deps)
+        copy_wheel_frameworks(slice_pip_deps, layout.frameworks, existing=staged)
+    _install_native_xcframeworks(
+        lock,
+        layout,
+        staged=staged,
+        project_root=project_root,
+        cache=cache,
+        downloader=downloader,
+        no_cache=no_cache,
+    )
+
+
+def _stamp_collected(slice_pip_deps: Path) -> None:
+    """Mark a pip-deps slice as collected.
+
+    The Build Python run script uses this marker — not directory emptiness — to
+    tell "collected, no third-party deps" (valid: an app with an empty pip-deps
+    slice) from "never collected" (error: wrong/uncollected Xcode destination).
+    It lives beside the slice dir so it is never rsync'd into the app bundle.
+    """
+    marker = slice_pip_deps.parent / f"{slice_pip_deps.name}.collected"
+    marker.write_text("", encoding="utf-8")
+
+
+def _setting_applies(value: bool | str, *, release: bool) -> bool:
+    """A ``build_settings`` tri-state resolved for the build being produced."""
+    if isinstance(value, bool):
+        return value
+    return release  # DESKTOP_RELEASE_ONLY
+
+
+def _compile_pip_deps(
+    slice_pip_deps: Path,
+    *,
+    python_version: str,
+    release: bool,
+    build_settings: DesktopBuildSettings | None,
+    echo: Callable[[str], None],
+) -> None:
+    """Byte-compile/strip a collected pip-deps slice, per ``build_settings``.
+
+    Mirrors each desktop backend's own ``_resolve_byte_compile`` (macOS/Linux/
+    Windows ``bundle.py``), with one iOS-specific simplification: the
+    Python.xcframework ships no standalone interpreter binary to shell out to
+    (it's a linkable library, not an executable), so the "staged interpreter"
+    rung of the compiler ladder never applies here — it always falls straight
+    to "this process's interpreter, if its CPython minor matches the target",
+    or degrades.
+    """
+    settings = build_settings or DesktopBuildSettings()
+    if not _setting_applies(settings.byte_compile, release=release):
+        return
+    compiler = select_compiler(
+        staged_interpreter=Path(), native=False, python_version=python_version
+    )
+    if compiler is None:
+        message = (
+            f"this project ships CPython {python_version}, and no CPython of "
+            "that minor could be found to byte-compile with (a .pyc is only "
+            "loadable by the exact CPython minor that wrote it)"
+        )
+        if settings.byte_compile is True:
+            raise CollectError(
+                "[tool.kivy.ios.python.build_settings].byte_compile = true but "
+                f"{message}.\n"
+                "  Install a matching CPython, or set byte_compile = false."
+            )
+        echo(f"[stage] not byte-compiling pip-deps: {message}.")
+        return
+    strip_source = _setting_applies(settings.strip_source, release=release)
+    with_what = " ".join(compiler) if compiler else "this interpreter"
+    echo(
+        f"[stage] byte-compiling pip-deps with {with_what}"
+        + (" (.pyc only)" if strip_source else "")
+    )
+    try:
+        byte_compile(
+            [slice_pip_deps],
+            compiler=compiler,
+            strip_source=strip_source,
+            stripdir=slice_pip_deps,
+        )
+    except PycompileError as exc:
+        raise CollectError(
+            f"{exc}\n  Fix it, or set "
+            "[tool.kivy.ios.python.build_settings].byte_compile = false."
+        ) from exc
+
+
+def _install_python_xcframework(lock, layout, *, cache, downloader, no_cache) -> None:
+    px = lock.python_xcframework
+    filename = px.url.rsplit("/", 1)[-1]
+    archive = fetch_artifact(
+        name=f"Python.xcframework {px.version}",
+        sha256=px.sha256,
+        filename=filename,
+        url=px.url,
+        cache=cache,
+        downloader=downloader,
+        no_cache=no_cache,
+    )
+    dest = layout.python_xcframework
+    if dest.exists():
+        shutil.rmtree(dest)
+    with tempfile.TemporaryDirectory(prefix="kivy-pyxc-") as tmp:
+        tmp_dir = Path(tmp)
+        with tarfile.open(archive, "r:gz") as tf:
+            # filter="data" rejects path traversal, absolute paths, and
+            # unsafe special files (Python 3.12+ / PEP 706).
+            tf.extractall(tmp_dir, filter="data")
+        found = next(
+            (p for p in tmp_dir.rglob("Python.xcframework") if p.is_dir()), None
+        )
+        if found is None:
+            raise CollectError(
+                "Python.xcframework not found inside downloaded archive."
+            )
+        shutil.copytree(found, dest)
+
+
+def _install_wheels(
+    lock,
+    layout,
+    *,
+    slice_pip_deps,
+    build_slice,
+    project_root,
+    cache,
+    downloader,
+    no_cache,
+    runner,
+    python_executable,
+) -> None:
+    with tempfile.TemporaryDirectory(prefix="kivy-wheels-") as tmp:
+        stage = Path(tmp)
+        wheel_files: list[str] = []
+        selected_wheels: list[LockedWheel] = []
+        for pkg in lock.packages:
+            wheel = select_wheel(pkg, build_slice)
+            selected_wheels.append(wheel)
+            local = fetch_artifact(
+                name=f"{pkg.name} {pkg.version}",
+                sha256=wheel.sha256,
+                filename=wheel.name,
+                url=wheel.url,
+                path=wheel.path,
+                project_root=project_root,
+                cache=cache,
+                downloader=downloader,
+                no_cache=no_cache,
+            )
+            # Cache entries are content-addressed ({sha256}-{name}); pip rejects
+            # that filename, so stage each wheel under its canonical PEP 427 name.
+            staged = stage / wheel.name
+            if local.resolve() != staged.resolve():
+                shutil.copy2(local, staged)
+            wheel_files.append(str(staged))
+        if not wheel_files:
+            return
+        # Each collect always starts from a clean slate so no stale .so
+        # files from a previous slice accumulate in the slice-specific dir.
+        if slice_pip_deps.is_dir():
+            shutil.rmtree(slice_pip_deps)
+        slice_pip_deps.mkdir(parents=True, exist_ok=True)
+        abi = "cp" + "".join(lock.python_xcframework.version.split(".")[:2])
+        # Use the selected wheels' actual platform tag for pip's --platform.
+        # The wheel tag reflects the Python binary's compile-time minimum OS
+        # (e.g. ios_13_0 from python.org's cp315 binary), which may be lower
+        # than the project's deployment_target.  pip requires --platform to
+        # match the wheel being installed, so use the selected native wheel's
+        # tag rather than the computed build_slice tag.
+        pip_platform = _native_platform_tag(selected_wheels, build_slice)
+        cmd = pip_install_command(
+            wheel_files,
+            target_dir=str(slice_pip_deps),
+            platform_tag=pip_platform,
+            python_version=".".join(lock.python_xcframework.version.split(".")[:2]),
+            abi=abi,
+            python_executable=python_executable,
+        )
+        proc = runner(cmd, capture_output=True, text=True)
+        if proc.returncode != 0:
+            raise CollectError(
+                f"pip install of pinned wheels failed:\n{proc.stderr or proc.stdout}"
+            )
+        # pip --target creates a bin/ of host-platform console scripts.
+        # Strip it immediately — these macOS executables cannot run on iOS
+        # and should not appear in the Xcode project tree or app bundle.
+        bin_dir = slice_pip_deps / "bin"
+        if bin_dir.is_dir():
+            shutil.rmtree(bin_dir)
+
+
+def _install_native_xcframeworks(
+    lock, layout, *, staged, project_root, cache, downloader, no_cache
+) -> None:
+    for xc in lock.xcframeworks:
+        filename = (xc.url or xc.path or xc.name).rsplit("/", 1)[-1]
+        archive = fetch_artifact(
+            name=xc.name,
+            sha256=xc.sha256,
+            filename=filename,
+            url=xc.url,
+            path=xc.path,
+            project_root=project_root,
+            cache=cache,
+            downloader=downloader,
+            no_cache=no_cache,
+        )
+        extract_xcframework_archive(
+            archive,
+            layout.frameworks,
+            name=xc.name,
+            archive_format=xc.archive_format,
+            archive_member=xc.archive_member,
+            existing=staged,
+        )
+
+
+def _native_platform_tag(selected: list[LockedWheel], slice_: BuildSlice) -> str:
+    """Return the pip --platform tag to use for the selected wheels.
+
+    All native wheels in a single build are produced by the same Python binary
+    and therefore share the same platform tag (e.g. ios_13_0_arm64_iphoneos).
+    Using the wheel's actual tag (rather than the project deployment_target tag)
+    ensures pip accepts the wheel even when the wheel's min-OS is lower than the
+    project's deployment_target.
+    """
+    for wheel in selected:
+        if not wheel.is_pure_python:
+            return wheel.platform_tag
+    return slice_.platform_tag

kivyforge/artifacts/download.py

@@ -0,0 +1,125 @@
+"""Fetch + verify + cache artifacts by URL or repo-relative path (spec 03).
+
+A single ``fetch_artifact`` entry point handles the three lockfile sources:
+``url`` (download), local ``path`` (vendored), and cache hits. Every byte that
+enters the build is SHA-256-verified against the lockfile pin before use.
+
+The network fetch is injectable (``Downloader``) so unit tests stay hermetic.
+"""
+
+from __future__ import annotations
+
+import tempfile
+import urllib.request
+from pathlib import Path, PurePosixPath
+from typing import Protocol
+
+from ..lock.find_links import FindLinksError, wheel_path_from_project_root
+from .cache import ArtifactCache
+from .verify import HashMismatch, sha256_file, verify_file
+
+
+class DownloadError(Exception):
+    pass
+
+
+class Downloader(Protocol):
+    def fetch_to(self, url: str, dest: Path) -> None: ...
+
+
+class UrllibDownloader:
+    def fetch_to(self, url: str, dest: Path) -> None:
+        try:
+            with urllib.request.urlopen(url) as resp, open(dest, "wb") as out:  # noqa: S310
+                for chunk in iter(lambda: resp.read(1 << 20), b""):
+                    out.write(chunk)
+        except (OSError, ValueError) as exc:
+            raise DownloadError(f"failed to download {url}: {exc}") from exc
+
+
+def fetch_artifact(
+    *,
+    name: str,
+    sha256: str,
+    filename: str,
+    url: str | None = None,
+    path: str | None = None,
+    project_root: Path | None = None,
+    cache: ArtifactCache | None = None,
+    downloader: Downloader | None = None,
+    no_cache: bool = False,
+) -> Path:
+    """Return a verified local path for an artifact (url xor path).
+
+    * ``url``  — cache-first download, then SHA-256 verify.
+    * ``path`` — repo-relative (resolved against ``project_root``); verified in
+      place. Absolute paths or paths escaping the project are rejected.
+    """
+    if bool(url) == bool(path):
+        raise DownloadError(f"{name}: exactly one of url/path is required")
+
+    if path is not None:
+        return _resolve_local(
+            name=name, path=path, sha256=sha256, project_root=project_root
+        )
+
+    if url is None:
+        # xor check above guarantees one of url/path; path branch already returned.
+        raise DownloadError(f"{name}: exactly one of url/path is required")
+
+    cache = cache or ArtifactCache()
+    downloader = downloader or UrllibDownloader()
+
+    if not no_cache:
+        cached = cache.get(sha256, filename)
+        if cached is not None and _cache_hit_intact(cached, sha256, name=name):
+            return cached
+
+    with tempfile.TemporaryDirectory(prefix="kivy-dl-") as tmp:
+        staged = Path(tmp) / filename
+        downloader.fetch_to(url, staged)
+        verify_file(staged, sha256, name=name, source=url)
+        return cache.put_file(staged, sha256, filename)
+
+
+def _cache_hit_intact(cached: Path, sha256: str, *, name: str) -> bool:
+    """Re-verify a cache hit before trusting it (spec 03 "every byte verified").
+
+    The cache key is only the *filename* (``{sha256}-{name}``); it is not proof
+    that the bytes on disk still match. A non-atomic ``copyfile`` killed mid-write
+    leaves a truncated file at the hash-named path, and the cache dir is
+    user-writable (bit-rot/tampering). On a mismatch we drop the corrupt entry
+    and return False so the caller re-downloads rather than feeding bad bytes
+    into the build.
+    """
+    try:
+        verify_file(cached, sha256, name=name, source=str(cached))
+    except HashMismatch:
+        cached.unlink(missing_ok=True)
+        return False
+    return True
+
+
+def _resolve_local(
+    *, name: str, path: str, sha256: str, project_root: Path | None
+) -> Path:
+    if PurePosixPath(path).is_absolute() or Path(path).is_absolute():
+        raise DownloadError(
+            f"{name}: lockfile path {path!r} is absolute; only repo-relative "
+            f"paths are allowed (they resolve identically on every clone)."
+        )
+    root = (project_root or Path.cwd()).resolve()
+    resolved = (root / path).resolve()
+    try:
+        wheel_path_from_project_root(root, resolved)
+    except FindLinksError as exc:
+        raise DownloadError(
+            f"{name}: lockfile path {path!r} escapes the allowed vendored "
+            f"wheel scope for this project."
+        ) from exc
+    if not resolved.is_file():
+        raise DownloadError(f"{name}: vendored artifact not found at {path!r}.")
+    actual = sha256_file(resolved)
+    if actual != sha256:
+        raise HashMismatch(name=name, source=path, expected=sha256, actual=actual)
+    return resolved