kivyforge 0.1.0__py3-none-any.whl

kivyforge/__init__.py

@@ -0,0 +1,11 @@
+"""kivyforge: build, run, and package Kivy apps for Android, iOS, macOS,
+Windows, and Linux.
+
+kivyforge reads a user-authored ``pyproject.toml`` (PEP 621 ``[project]``
+plus ``[tool.kivy]`` and one ``[tool.kivy.<platform>]`` overlay per target),
+resolves a PEP 751 ``pylock.<platform>.toml`` build manifest, and materializes
+it into that platform's project or bundle. See ``docs/design`` for the full
+specification.
+"""
+
+__version__ = "0.1.0"

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,424 @@
+"""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; ``Frameworks/`` is rebuilt from the
+lock every run. 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
+import zipfile
+from collections.abc import Callable
+from pathlib import Path
+
+from ..build_outcome import discard_note
+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 ..report.diagnostics import BYTECOMPILE_NO_INTERP
+from ..report.failures import ClassifiedError, reclassify
+from .cache import ArtifactCache
+from .download import Downloader, fetch_artifact
+from .frameworks import (
+    PlacedFramework,
+    clear_staged_frameworks,
+    copy_wheel_frameworks,
+    extract_xcframework_archive,
+)
+from .wheels import BuildSlice, select_wheel
+
+
+class CollectError(ClassifiedError):
+    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",
+        # pip is the one tool here that can genuinely prompt: an index needing
+        # auth asks for credentials, which in CI hangs until the job times out.
+        "--no-input",
+        # pip would byte-compile what it installs with the *host* interpreter,
+        # whose .pyc the target's CPython cannot load. That includes a wheel's
+        # data files, whose __pycache__ then outlives them. A release build
+        # compiles pip-deps itself, with a matching interpreter.
+        "--no-compile",
+        "--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,
+    note=discard_note,
+) -> 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] = {}
+    # Frameworks/ is rebuilt from this lock alone, so a removed wheel or
+    # native entry takes its xcframework with it.
+    clear_staged_frameworks(layout.frameworks)
+    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,
+            note=note,
+        )
+        _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],
+    note=discard_note,
+) -> 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:
+        minor = ".".join(python_version.split(".")[:2])
+        headline = (
+            f"no final CPython {minor} found (this project ships {python_version})"
+        )
+        why_and_fix = (
+            "  Pre-releases do not count: CPython only freezes the .pyc "
+            f"magic number at the first release candidate, so a {minor} alpha "
+            f"writes bytecode {python_version} refuses to import.\n"
+            f"  Fix: install a final CPython {minor} — kivyforge finds it "
+            "automatically — or set byte_compile = false in "
+            "[tool.kivy.ios.python.build_settings]."
+        )
+        if settings.byte_compile is True:
+            raise CollectError(
+                "[tool.kivy.ios.python.build_settings].byte_compile = true, but "
+                f"{headline}.\n{why_and_fix}"
+            )
+        echo(f"[stage] not byte-compiling pip-deps: {headline}.\n{why_and_fix}")
+        note(
+            BYTECOMPILE_NO_INTERP,
+            f"not byte-compiling pip-deps: {headline}.",
+            {"payload": "pip-deps"},
+        )
+        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.",
+            **reclassify(exc),
+        ) 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))
+        # Each collect always starts from a clean slate so no stale .so
+        # files from a previous slice accumulate in the slice-specific dir --
+        # also when the lock now pins nothing, or removing the last dependency
+        # would leave the previous collect's packages in the app.
+        if slice_pip_deps.is_dir():
+            shutil.rmtree(slice_pip_deps)
+        slice_pip_deps.mkdir(parents=True, exist_ok=True)
+        if not wheel_files:
+            return
+        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)
+        for wheel_file in wheel_files:
+            _drop_wheel_data_files(Path(wheel_file), slice_pip_deps)
+
+
+def _drop_wheel_data_files(wheel: Path, slice_pip_deps: Path) -> None:
+    """Remove what *wheel* installed from its ``.data/data/`` tree.
+
+    That tree is a wheel's ``data_files``: paths relative to an install prefix
+    (``share/...``, examples, headers, test sources), which ``pip --target``
+    lays down at the root of the slice. Nothing on iOS can find them: the app's
+    ``sys.prefix`` is not ``pip-deps``. They are dead weight, and a release
+    build byte-compiles them, so one Python 2 example fails the whole package
+    (pyobjus ships 18). macOS never installs this tree (``wheels_stage._unpack``
+    keeps only ``purelib``/``platlib``); this brings iOS in line.
+
+    Only the files the wheel itself names are removed, never a whole
+    directory, so a data file beside a real package cannot take the package
+    with it. Directories left empty are pruned.
+    """
+    with zipfile.ZipFile(wheel) as zf:
+        names = zf.namelist()
+    root = slice_pip_deps.resolve()
+    emptied: set[Path] = set()
+    for name in names:
+        parts = name.split("/")
+        if len(parts) < 3 or not parts[0].endswith(".data") or parts[1] != "data":
+            continue
+        installed = (slice_pip_deps / Path(*parts[2:])).resolve()
+        if not installed.is_relative_to(root) or not installed.is_file():
+            continue
+        installed.unlink()
+        emptied.update(p for p in installed.parents if p.is_relative_to(root))
+    # Deepest first, so a parent is only tried once its children are gone.
+    for directory in sorted(emptied, key=lambda p: len(p.parts), reverse=True):
+        if directory != root and directory.is_dir() and not any(directory.iterdir()):
+            directory.rmdir()
+
+
+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