kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/linux/runtime_stage.py

@@ -0,0 +1,107 @@
+"""Acquire the bundled CPython runtime for the AppDir (linux-spec).
+
+Consumes the provider-agnostic runtime pin from ``pylock.linux.toml`` (the
+single ``x86_64`` artifact this phase — one arch per AppImage), fetches +
+verifies its archive, extracts it, and materializes the relocatable CPython tree
+at ``usr/python``. The extracted archive is normalized to its canonical root via
+``normalized_runtime_root`` keyed on the lock's recorded ``provider`` — staging
+never hard-codes a provider's archive internals (spec 07). The PBS linux-gnu
+``install_only`` archive is the same unix-prefix layout as the darwin ones and
+uses ``$ORIGIN``-relative rpaths, so it is relocatable as-shipped — no patchelf
+pass, and (unlike macOS) no ``lipo`` merge, since Linux ships one arch per
+AppImage.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tarfile
+import tempfile
+from pathlib import Path
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.download import DownloadError, fetch_artifact
+from kivyforge.lock.wheelruntime.model import PythonRuntime
+from kivyforge.lock.wheelruntime.runtime import (
+    RuntimeProviderError,
+    normalized_runtime_root,
+)
+
+from . import AppDirError
+
+
+def stage_runtime(
+    runtime: PythonRuntime,
+    arch: str,
+    home: Path,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+) -> Path:
+    """Materialize the runtime for *arch* at *home*; return *home*.
+
+    *home* is the final CPython home directory (whose ``bin/python3`` ``AppRun``
+    execs). It is emptied and recreated.
+    """
+    cache = cache or ArtifactCache()
+    artifact = runtime.artifact_for(arch)
+    if artifact is None:
+        raise AppDirError(
+            f"the lock has no {arch} runtime artifact; re-run "
+            f"`kivyforge lock -p linux` (locked archs: "
+            f"{', '.join(a.arch for a in runtime.artifacts)})."
+        )
+
+    tmp = Path(tempfile.mkdtemp(prefix="kivy-runtime-"))
+    try:
+        archive = _fetch(artifact, arch, project_root, cache, no_cache)
+        extracted = _extract(archive, tmp, runtime.provider)
+        if home.exists():
+            shutil.rmtree(home)
+        home.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(extracted, home, symlinks=True)
+        return home
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def _fetch(artifact, arch, project_root, cache, no_cache) -> Path:
+    filename = artifact.url.rsplit("/", 1)[-1] or f"python-{arch}.tar.gz"
+    try:
+        return fetch_artifact(
+            name=f"python runtime ({arch})",
+            sha256=artifact.sha256,
+            filename=filename,
+            url=artifact.url,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+    except DownloadError as exc:
+        raise AppDirError(str(exc)) from exc
+
+
+def _extract(archive: Path, into: Path, provider: str) -> Path:
+    into.mkdir(parents=True, exist_ok=True)
+    try:
+        with tarfile.open(archive, "r:*") as tf:
+            _safe_extractall(tf, into)
+    except (tarfile.TarError, OSError) as exc:
+        raise AppDirError(f"failed to extract {archive.name}: {exc}") from exc
+    try:
+        return normalized_runtime_root(provider, into)
+    except RuntimeProviderError as exc:
+        raise AppDirError(f"{archive.name}: {exc}") from exc
+
+
+def _safe_extractall(tf: tarfile.TarFile, into: Path) -> None:
+    """Extract, rejecting members that would escape *into* (path traversal)."""
+    base = into.resolve()
+    for member in tf.getmembers():
+        target = (into / member.name).resolve()
+        if not (target == base or base in target.parents):
+            raise AppDirError(f"unsafe path in archive: {member.name!r}")
+    # Paths are validated above; fully_trusted preserves the runtime's
+    # permissions and symlinks (the restrictive filters would rewrite them).
+    tf.extractall(into, filter="fully_trusted")  # noqa: S202 — members validated just above

kivyforge/platforms/linux/wheels_stage.py

@@ -0,0 +1,103 @@
+"""Install the locked wheels into the AppDir's ``usr/lib`` (site-packages).
+
+Wheels are fetched + SHA-256-verified from ``pylock.linux.toml`` (URL or
+vendored path) and unpacked directly — no pip, so the bundler is independent of
+the host interpreter. Linux ships one arch per AppImage, so per package a single
+wheel satisfies coverage: a pure-Python (``py3-none-any``) wheel or a manylinux
+(or vendored ``linux_x86_64``) wheel matching the assembly arch. There is no
+``lipo``-style merge as on macOS.
+"""
+
+from __future__ import annotations
+
+import shutil
+import zipfile
+from pathlib import Path
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.download import DownloadError, fetch_artifact
+from kivyforge.lock.model import LockedPackage, LockedWheel
+
+from . import AppDirError
+from .lock import linux_wheel_arch
+
+
+def stage_wheels(
+    packages: tuple[LockedPackage, ...],
+    arch: str,
+    lib_dir: Path,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+) -> None:
+    """Unpack every package's wheel for *arch* into *lib_dir*."""
+    cache = cache or ArtifactCache()
+    if lib_dir.exists():
+        shutil.rmtree(lib_dir)
+    lib_dir.mkdir(parents=True)
+
+    for pkg in packages:
+        wheel = _select_wheel(pkg, arch)
+        _unpack(_fetch(wheel, project_root, cache, no_cache), lib_dir)
+
+
+def _select_wheel(pkg: LockedPackage, arch: str) -> LockedWheel:
+    """Pick the wheel to unpack: pure-Python, else the one covering *arch*."""
+    for wheel in pkg.wheels:
+        if wheel.is_pure_python:
+            return wheel
+    for wheel in pkg.wheels:
+        if any(linux_wheel_arch(sub) == arch for sub in wheel.platform_tag.split(".")):
+            return wheel
+    raise AppDirError(
+        f"{pkg.name} {pkg.version} has no wheel for arch {arch} in the lock.\n"
+        "  Re-run `kivyforge lock -p linux`."
+    )
+
+
+def _fetch(wheel: LockedWheel, project_root, cache, no_cache) -> Path:
+    try:
+        return fetch_artifact(
+            name=wheel.name,
+            sha256=wheel.sha256,
+            filename=wheel.name,
+            url=wheel.url,
+            path=wheel.path,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+    except DownloadError as exc:
+        raise AppDirError(str(exc)) from exc
+
+
+def _unpack(wheel: Path, target: Path) -> None:
+    """Extract a wheel into *target*, normalizing ``.data/{purelib,platlib}``."""
+    with zipfile.ZipFile(wheel) as zf:
+        _safe_extract(zf, target)
+    for data_dir in list(target.glob("*.data")):
+        for sub in ("purelib", "platlib"):
+            src = data_dir / sub
+            if src.is_dir():
+                _merge_tree(src, target)
+        shutil.rmtree(data_dir, ignore_errors=True)
+
+
+def _merge_tree(src: Path, dest: Path) -> None:
+    for item in src.iterdir():
+        target = dest / item.name
+        if item.is_dir():
+            target.mkdir(exist_ok=True)
+            _merge_tree(item, target)
+        else:
+            shutil.copy2(item, target)
+
+
+def _safe_extract(zf: zipfile.ZipFile, target: Path) -> None:
+    base = target.resolve()
+    for member in zf.namelist():
+        resolved = (target / member).resolve()
+        if not (resolved == base or base in resolved.parents):
+            raise AppDirError(f"unsafe path in wheel: {member!r}")
+    zf.extractall(target)  # noqa: S202 — members validated just above

kivyforge/platforms/macos/__init__.py

@@ -0,0 +1,121 @@
+"""macOS platform backend.
+
+Produces a self-contained ``.app`` bundle (macos-spec). macOS is the host
+default on Darwin, so a Mac with ``[tool.kivy.macos]`` configured resolves to
+this backend without ``-p``. It requires a macOS host (``codesign``/``lipo``
+from the Xcode command-line tools); the full Xcode IDE is not needed.
+"""
+
+from __future__ import annotations
+
+import platform as _platform
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ..base import HostCapabilityError, Platform
+
+if TYPE_CHECKING:
+    from kivyforge.doctor.result import CheckResult
+
+
+class AppBundleError(Exception):
+    """A macOS ``.app`` bundling failure surfaced with an actionable message."""
+
+
+class MacosPlatform(Platform):
+    name = "macos"
+    # macOS is a desktop target built on its own OS, so Darwin maps to it as the
+    # host default (resolution-chain step 3).
+    host_system = "Darwin"
+    # The distributable is the .app bundle; .dmg/installer is external.
+    package_formats = ("app",)
+
+    def check_host_capability(self, *, host_system: str | None = None) -> None:
+        host = host_system if host_system is not None else _platform.system()
+        if host != "Darwin":
+            raise HostCapabilityError(
+                "building for macOS requires a macOS host; "
+                f"this host is {host!r}.\n"
+                "  The .app bundler signs Mach-O binaries with codesign and "
+                "merges per-arch runtimes with lipo — both are macOS-only.\n"
+                "  Run `kivyforge doctor -p macos` on a Mac to check the setup."
+            )
+
+    def build(
+        self,
+        project_root: Path,
+        *,
+        target: str | None,
+        arch: str | None,
+        no_verify_lock: bool,
+        no_cache: bool,
+        team_id: str | None,
+        signing_identity: str | None,
+        export_method: str,
+        debug: bool = False,
+        fmt: str | None = None,
+        abi: str | None = None,
+    ) -> None:
+        self.reject_ios_only_target(target)
+        from .cli import macos_build
+
+        macos_build(
+            project_root,
+            arch=arch,
+            no_verify_lock=no_verify_lock,
+            no_cache=no_cache,
+        )
+
+    def run(
+        self,
+        project_root: Path,
+        *,
+        target: str,
+        arch: str | None,
+        destination: str | None,
+        no_build: bool,
+    ) -> None:
+        from .cli import macos_run
+
+        macos_run(project_root, arch=arch, no_build=no_build)
+
+    def package(
+        self,
+        project_root: Path,
+        *,
+        fmt: str,
+        arch: str | None,
+        team_id: str | None,
+        signing_identity: str | None,
+        export_method: str,
+        notarize: bool | None,
+        notary_profile: str | None,
+        no_verify_lock: bool,
+        no_cache: bool,
+        abi: str | None = None,
+        keystore: str | None = None,
+        key_alias: str | None = None,
+    ) -> None:
+        from .cli import macos_package
+
+        macos_package(
+            project_root,
+            arch=arch,
+            no_verify_lock=no_verify_lock,
+            no_cache=no_cache,
+            signing_identity=signing_identity,
+            notarize=notarize,
+            notary_profile=notary_profile,
+        )
+
+    def status(self, project_root: Path) -> None:
+        from .cli import macos_status
+
+        macos_status(project_root)
+
+    def doctor(
+        self, cwd: Path, *, kivyforge_version: str, offline: bool
+    ) -> list[CheckResult]:
+        from .doctor import macos_doctor
+
+        return macos_doctor(cwd, kivyforge_version=kivyforge_version, offline=offline)

kivyforge/platforms/macos/bundle.py

@@ -0,0 +1,255 @@
+"""Assemble (and optionally sign) the macOS ``.app`` bundle (macos-spec).
+
+Orchestrates the pieces: resolve the assembly arch from the lock + ``--arch``
+(macOS is arm64-only, so this is always a single arch), stage the runtime +
+wheels, copy the app sources, render the icon + Info.plist + launcher, and
+ad-hoc sign. Produces the layout documented in macos-spec:
+
+    <Name>.app/Contents/{Info.plist, MacOS/<exe>,
+                         Resources/{app,lib,python,<exe>.icns}}
+"""
+
+from __future__ import annotations
+
+import platform
+import plistlib
+import shutil
+import tempfile
+from pathlib import Path
+
+import click
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.bundle.pycompile import PycompileError, byte_compile, select_compiler
+from kivyforge.config.model import Config
+
+from . import AppBundleError
+from .icns import generate_icns
+from .launcher import build_launcher
+from .lock import MacosLockfile
+from .native_stage import stage_native_binaries
+from .plist import build_info_plist
+from .runtime_stage import stage_runtime
+from .signing import sign_bundle_adhoc
+from .wheels_stage import stage_wheels
+
+_IGNORE = shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store")
+
+
+def resolve_assembly_arch(locked: tuple[str, ...], arch: str | None) -> str:
+    """The single arch to assemble. macOS ships arm64 only."""
+    if not locked:
+        raise AppBundleError(
+            "the lock covers no architectures; re-run `kivyforge lock -p macos`."
+        )
+    if arch is None:
+        return locked[0]
+    if arch not in locked:
+        raise AppBundleError(
+            f"--arch {arch} is not in the lock (covers {', '.join(locked)}).\n"
+            f"  macOS builds are arm64-only; pick a locked arch."
+        )
+    return arch
+
+
+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 _resolve_byte_compile(
+    config: Config,
+    *,
+    staged_interpreter: Path,
+    target_arch: str,
+    python_version: str,
+    release: bool,
+) -> tuple[tuple[str, ...] | None, bool]:
+    """Decide whether to byte-compile, and with which interpreter.
+
+    Returns ``(compiler_argv_or_None, strip_source)``; ``None`` means do not
+    byte-compile. ``byte_compile = true`` is read as "I insist", so a missing
+    interpreter is an error; the default ``"release"`` degrades to shipping
+    source with a warning rather than breaking a build the user never
+    configured.
+    """
+    settings = config.macos_required.build_settings
+    if not _setting_applies(settings.byte_compile, release=release):
+        return None, False
+    native = platform.machine().lower() == target_arch
+    compiler = select_compiler(
+        staged_interpreter=staged_interpreter,
+        native=native,
+        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 AppBundleError(
+                "[tool.kivy.macos.build_settings].byte_compile = true but "
+                f"{message}.\n"
+                "  Install a matching CPython, or set byte_compile = false."
+            )
+        click.echo(f"[stage] not byte-compiling: {message}.")
+        return None, False
+    strip = _setting_applies(settings.strip_source, release=release)
+    return compiler, strip
+
+
+def build_app_bundle(
+    config: Config,
+    lock: MacosLockfile,
+    project_root: Path,
+    *,
+    arch: str | None = None,
+    staging_dir: Path | None = None,
+    sign: bool = True,
+    no_cache: bool = False,
+    cache: ArtifactCache | None = None,
+    release: bool = False,
+    echo=click.echo,
+) -> Path:
+    """Build the ``.app`` and return its path."""
+    target_arch = resolve_assembly_arch(lock.archs, arch)
+    cache = cache or ArtifactCache()
+    staging_dir = staging_dir or (project_root / "build" / "macos")
+    exe = config.app_slug
+    app = staging_dir / f"{config.display_name}.app"
+
+    # Assemble into a temp .app and swap it in only on success, so a failure
+    # mid-assembly (e.g. a transient runtime/wheel fetch error, or a signing
+    # failure) leaves the previous, working .app untouched instead of a
+    # half-written one. Mirrors the Linux AppDir builder's write-then-swap.
+    staging_dir.mkdir(parents=True, exist_ok=True)
+    work = Path(tempfile.mkdtemp(dir=staging_dir, prefix=f".{app.name}.tmp-"))
+    try:
+        contents = work / "Contents"
+        (contents / "MacOS").mkdir(parents=True)
+        resources = contents / "Resources"
+        resources.mkdir()
+
+        echo(
+            f"Staging CPython {lock.python_runtime.version} runtime ({target_arch}) ..."
+        )
+        stage_runtime(
+            lock.python_runtime,
+            target_arch,
+            resources / "python",
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+
+        echo(f"Installing {len(lock.packages)} locked packages ...")
+        stage_wheels(
+            lock.packages,
+            target_arch,
+            resources / "lib",
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+
+        if lock.native_binaries:
+            echo(f"Staging {len(lock.native_binaries)} native binaries ...")
+            stage_native_binaries(
+                lock,
+                resources,
+                project_root=project_root,
+                cache=cache,
+                no_cache=no_cache,
+            )
+
+        _copy_app_sources(config, project_root, resources / "app")
+        icon_file = _stage_icon(config, project_root, resources, exe)
+
+        build_launcher(
+            contents / "MacOS" / exe,
+            entry_point=config.kivy.entry_point,
+            arch=target_arch,
+        )
+
+        plist = build_info_plist(config, executable=exe, icon_file=icon_file)
+        with (contents / "Info.plist").open("wb") as fh:
+            plistlib.dump(plist, fh)
+
+        # Byte-compile before signing: codesign seals every file it signs, so
+        # mutating the payload afterward (deleting .py, writing .pyc) would
+        # invalidate the very signature this function is about to produce.
+        compiler, strip_source = _resolve_byte_compile(
+            config,
+            staged_interpreter=resources / "python" / "bin" / "python3",
+            target_arch=target_arch,
+            python_version=lock.python_runtime.version,
+            release=release,
+        )
+        if compiler is not None:
+            with_what = " ".join(compiler) if compiler else "this interpreter"
+            echo(
+                f"[stage] byte-compiling the Python payload with {with_what}"
+                + (" (.pyc only)" if strip_source else "")
+            )
+            try:
+                byte_compile(
+                    [resources / "app", resources / "lib"],
+                    compiler=compiler,
+                    strip_source=strip_source,
+                    stripdir=work,
+                )
+            except PycompileError as exc:
+                raise AppBundleError(
+                    f"{exc}\n  Fix it, or set "
+                    "[tool.kivy.macos.build_settings].byte_compile = false."
+                ) from exc
+
+        # Sign the temp bundle before the swap: codesign embeds signatures in the
+        # Mach-O files + Contents/_CodeSignature, so an atomic rename preserves
+        # them, and a signing failure never displaces the previous good .app.
+        if sign:
+            echo("Ad-hoc signing the bundle ...")
+            count = sign_bundle_adhoc(work)
+            echo(f"  signed {count} Mach-O binaries + the bundle")
+    except BaseException:
+        shutil.rmtree(work, ignore_errors=True)
+        raise
+
+    # Swap the freshly built tree in for the previous one. The rename is atomic
+    # within staging_dir; the brief rmtree→rename window only exists after a
+    # fully successful build.
+    if app.exists():
+        shutil.rmtree(app)
+    work.replace(app)
+    return app
+
+
+def _copy_app_sources(config: Config, project_root: Path, dest: Path) -> None:
+    src = (project_root / config.kivy.app_dir).resolve()
+    if not src.is_dir():
+        raise AppBundleError(
+            f"[tool.kivy].app_dir points to {config.kivy.app_dir!r}, which is not "
+            f"a directory under {project_root}."
+        )
+    entry = src / f"{config.kivy.entry_point}.py"
+    if not entry.is_file():
+        raise AppBundleError(
+            f"entry point {config.kivy.entry_point}.py not found in "
+            f"{config.kivy.app_dir}/ (set [tool.kivy].entry_point)."
+        )
+    shutil.copytree(src, dest, ignore=_IGNORE)
+
+
+def _stage_icon(
+    config: Config, project_root: Path, resources: Path, exe: str
+) -> str | None:
+    source = config.macos_required.icons.source
+    if not source:
+        return None
+    icns = f"{exe}.icns"
+    generate_icns((project_root / source).resolve(), resources / icns)
+    return icns