kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/macos/lock/__init__.py

@@ -0,0 +1,112 @@
+"""macOS lock stack (``pylock.macos.toml``).
+
+A thin macOS *profile* (:class:`MacosProfile`) over the generic wheel+runtime
+lock engine (``kivyforge.lock.wheelruntime``). This module is the stable macOS
+public surface: it binds the profile into the core and re-exports the engine's
+types under macOS-friendly names so callers (the CLI, tests) never reach into the
+generic package directly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+
+from kivyforge.config.model import Config
+from kivyforge.lock.wheelruntime import (
+    PythonRuntime as MacosPythonRuntime,
+)
+from kivyforge.lock.wheelruntime import (
+    ResolvedPackage,
+    ResolvedWheel,
+    RuntimeArtifact,
+    RuntimeProvider,
+    RuntimeProviderError,
+    Variant,
+    WheelResolver,
+    WheelResolverError,
+    WheelRuntimeBuildError,
+    WheelRuntimeLock,
+    build_wheel_runtime_lock,
+    diff_summary,
+    get_wheel_resolver,
+    semantic_equal,
+)
+from kivyforge.lock.wheelruntime import serialize as _ser
+
+from .profile import MacosProfile, macos_platform_tag, wheel_arch
+from .runtime import PythonBuildStandaloneProvider
+
+# macOS-friendly aliases for the generic engine types.
+MacosLockfile = WheelRuntimeLock
+MacosBuildError = WheelRuntimeBuildError
+MacosResolverError = WheelResolverError
+
+_PROFILE = MacosProfile()
+
+__all__ = [
+    "MacosBuildError",
+    "MacosLockfile",
+    "MacosProfile",
+    "MacosPythonRuntime",
+    "MacosResolverError",
+    "PythonBuildStandaloneProvider",
+    "ResolvedPackage",
+    "ResolvedWheel",
+    "RuntimeArtifact",
+    "RuntimeProvider",
+    "RuntimeProviderError",
+    "Variant",
+    "WheelResolver",
+    "build_macos_lockfile",
+    "diff_summary",
+    "dumps",
+    "get_macos_resolver",
+    "load",
+    "loads",
+    "macos_platform_tag",
+    "semantic_equal",
+    "wheel_arch",
+]
+
+
+def build_macos_lockfile(
+    config: Config,
+    pyproject_text: str,
+    *,
+    project_root: Path | None = None,
+    resolver: WheelResolver | None = None,
+    runtime_provider: RuntimeProvider | None = None,
+    offline: bool = False,
+    now: datetime | None = None,
+    on_warning: Callable[[str], None] | None = None,
+) -> MacosLockfile:
+    return build_wheel_runtime_lock(
+        _PROFILE,
+        config,
+        pyproject_text,
+        project_root=project_root,
+        resolver=resolver,
+        runtime_provider=runtime_provider,
+        native_binaries=config.macos.binaries if config.macos else (),
+        offline=offline,
+        now=now,
+        on_warning=on_warning,
+    )
+
+
+def dumps(lock: MacosLockfile) -> str:
+    return _ser.dumps(lock)
+
+
+def loads(text: str) -> MacosLockfile:
+    return _ser.loads(text, platform="macos")
+
+
+def load(path: str | Path) -> MacosLockfile:
+    return _ser.load(path, platform="macos")
+
+
+def get_macos_resolver(backend: str = "pip", **kwargs) -> WheelResolver:
+    return get_wheel_resolver(backend, **kwargs)

kivyforge/platforms/macos/lock/profile.py

@@ -0,0 +1,119 @@
+"""macOS lock profile — the platform-specific inputs to the wheel+runtime core.
+
+macOS builds target ``arm64`` only, but wheel *tags* are a wider set: a
+``universal2`` wheel covers arm64 and is accepted, and ``x86_64`` tags are still
+parsed (they simply never match). Keeping ``VALID_WHEEL_ARCHS`` wider than the
+build-target set is deliberate — narrowing it would reject most macOS wheels on
+PyPI. The bundled runtime comes from python-build-standalone (darwin triples).
+Everything else — resolve/serialize/build orchestration — is the shared core.
+"""
+
+from __future__ import annotations
+
+import re
+
+from kivyforge.config.errors import ConfigError
+from kivyforge.config.model import Config
+from kivyforge.lock.wheelruntime.profile import PlatformLockProfile
+from kivyforge.lock.wheelruntime.resolver import Variant
+from kivyforge.lock.wheelruntime.runtime import RuntimeProvider
+
+from .runtime import PythonBuildStandaloneProvider
+
+# Default macOS deployment floor for the pip ``--platform`` request when the
+# project sets no ``minimum_system_version``. pip matches wheels tagged at or
+# below this floor (plus universal2), maximizing compatible wheels.
+DEFAULT_MACOS_FLOOR = "11.0"
+
+VALID_WHEEL_ARCHS = frozenset({"arm64", "x86_64", "universal2"})
+
+
+def macos_platform_tag(floor: str, arch: str) -> str:
+    """The pip ``--platform`` tag for a macOS deployment floor + arch."""
+    return f"macosx_{floor.replace('.', '_')}_{arch}"
+
+
+def wheel_arch(platform_tag: str) -> str | None:
+    """The architecture a macOS wheel platform tag targets, or ``None``.
+
+    ``macosx_11_0_arm64`` -> ``arm64``; ``macosx_11_0_x86_64`` -> ``x86_64``;
+    ``..._universal2`` -> ``universal2``. The arch is what follows the
+    ``macosx_<major>_<minor>_`` prefix (``x86_64`` itself has an underscore, so a
+    naive rsplit is wrong).
+    """
+    match = re.fullmatch(r"macosx_\d+_\d+_(.+)", platform_tag)
+    if match is None:
+        return None
+    arch = match.group(1)
+    return arch if arch in VALID_WHEEL_ARCHS else None
+
+
+class MacosProfile(PlatformLockProfile):
+    platform = "macos"
+
+    def overlay(self, config: Config):
+        return config.macos
+
+    def missing_overlay_error(self) -> str:
+        return "pyproject.toml has no [tool.kivy.macos] table; nothing to lock."
+
+    def python_version(self, config: Config) -> str:
+        # [tool.kivy.macos.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.
+        version = config.macos_required.python_version
+        if not version:
+            raise ConfigError(
+                "missing required [tool.kivy.macos.python].version",
+                key_path="tool.kivy.macos.python.version",
+            )
+        return version
+
+    def _floor(self, config: Config) -> str:
+        return config.macos_required.minimum_system_version or DEFAULT_MACOS_FLOOR
+
+    def variants(self, config: Config) -> tuple[Variant, ...]:
+        floor = self._floor(config)
+        return tuple(
+            Variant(arch=arch, platform_tag=macos_platform_tag(floor, arch))
+            for arch in config.macos_required.archs
+        )
+
+    def wheel_covers(self, platform_tag: str, archs: tuple[str, ...]) -> set[str]:
+        arch = wheel_arch(platform_tag)
+        if arch == "universal2":
+            return set(archs)
+        if arch in archs:
+            return {arch}
+        return set()
+
+    def runtime_provider(self, config: Config) -> RuntimeProvider:
+        return PythonBuildStandaloneProvider()
+
+    def declared_floor(self, config: Config) -> str | None:
+        return config.macos_required.minimum_system_version
+
+    def coverage_error(self, name: str, missing: list[str]) -> str:
+        return (
+            f"{name} is missing macOS wheel(s) for arch(es): {', '.join(missing)}.\n"
+            f"  A compiled package must publish an arm64 or universal2 wheel to "
+            f"be locked reproducibly.\n"
+            f"  Intel-only wheels cannot be used: kivyforge builds arm64-only "
+            f"macOS apps."
+        )
+
+    def floor_error(self, declared: str, runtime_floor: str, version: str) -> str:
+        return (
+            f"minimum_system_version {declared} is below the macOS {runtime_floor} "
+            f"floor required by the Python {version} runtime.\n"
+            f"  Raise [tool.kivy.macos].minimum_system_version to at least "
+            f"{runtime_floor}."
+        )
+
+    def wheel_scope_hint(self) -> str:
+        return (
+            "Vendored wheels must live under the project directory, a sibling "
+            "directory, or the enclosing repository (e.g. a wheels/ directory "
+            "beside pyproject.toml)."
+        )

kivyforge/platforms/macos/lock/runtime.py

@@ -0,0 +1,58 @@
+"""macOS runtime provider — python-build-standalone with darwin triples.
+
+A one-line specialization of the generic :class:`PbsProvider`: it fixes the
+arch→target-triple map to macOS's, and otherwise inherits the shared PBS
+resolution + injectable metadata fetcher.
+"""
+
+from __future__ import annotations
+
+from kivyforge.lock.wheelruntime.runtime import (
+    MetadataFetcher,
+    PbsProvider,
+    ReleaseAsset,
+    RuntimeProvider,
+    RuntimeProviderError,
+    pbs_asset_glob,
+)
+
+__all__ = [
+    "DARWIN_TRIPLES",
+    "PythonBuildStandaloneProvider",
+    "ReleaseAsset",
+    "RuntimeProvider",
+    "RuntimeProviderError",
+    "get_runtime_provider",
+    "pbs_asset_name",
+]
+
+# kivyforge arch name -> PBS/LLVM darwin target triple.
+DARWIN_TRIPLES = {
+    "arm64": "aarch64-apple-darwin",
+    "x86_64": "x86_64-apple-darwin",
+}
+
+# macOS-facing alias for the generic PBS asset glob helper.
+pbs_asset_name = pbs_asset_glob
+
+
+class PythonBuildStandaloneProvider(PbsProvider):
+    """PBS provider fixed to macOS darwin triples."""
+
+    def __init__(
+        self,
+        metadata_fetcher: MetadataFetcher | None = None,
+        *,
+        floor: str | None = None,
+    ) -> None:
+        super().__init__(DARWIN_TRIPLES, metadata_fetcher, floor=floor)
+
+
+def get_runtime_provider(
+    name: str = "python-build-standalone", **kwargs
+) -> RuntimeProvider:
+    if name in ("python-build-standalone", "pbs", "python_build_standalone"):
+        return PythonBuildStandaloneProvider(**kwargs)
+    raise RuntimeProviderError(
+        f"unknown runtime provider {name!r} (expected python-build-standalone)"
+    )

kivyforge/platforms/macos/machotools.py

@@ -0,0 +1,138 @@
+"""Thin wrappers over the macOS binary tools the bundler needs.
+
+``lipo -archs`` (read a Mach-O's architectures), ``codesign`` (ad-hoc signing —
+the mandatory Apple-Silicon floor), and Mach-O detection (so we only ever sign
+actual binaries, not text/data files). Kept isolated + injectable-friendly so
+the higher-level bundler logic stays testable and these are the only lines that
+shell out to Apple tools.
+
+There is no ``lipo -create`` wrapper: macOS builds are arm64-only, so nothing
+is ever merged into a universal binary.
+"""
+
+from __future__ import annotations
+
+import struct
+import subprocess
+import time
+from pathlib import Path
+
+from . import AppBundleError
+
+# codesign, when signing with a real (keychain-backed) identity, intermittently
+# fails with errSecInternalComponent under rapid successive invocations — a
+# long-standing macOS securityd flakiness (not a config problem; ad-hoc signing
+# uses no keychain and never hits it). A short retry with backoff reliably
+# clears it; see e.g. https://developer.apple.com/forums/thread/700333.
+_CODESIGN_TRANSIENT_ERRORS = ("errSecInternalComponent",)
+_CODESIGN_MAX_ATTEMPTS = 5
+_CODESIGN_RETRY_DELAY_S = 1.0
+
+# Mach-O magic numbers (little/big-endian, 32/64-bit) and the fat/universal
+# magics. A file that starts with any of these is a Mach-O we may lipo/sign.
+_MACHO_MAGICS = frozenset(
+    {
+        0xFEEDFACE,  # MH_MAGIC (32-bit)
+        0xCEFAEDFE,  # MH_CIGAM
+        0xFEEDFACF,  # MH_MAGIC_64
+        0xCFFAEDFE,  # MH_CIGAM_64
+        0xCAFEBABE,  # FAT_MAGIC (universal)
+        0xBEBAFECA,  # FAT_CIGAM
+    }
+)
+
+
+def is_macho(path: Path) -> bool:
+    """True if *path* is a regular file whose first 4 bytes are a Mach-O magic.
+
+    Note ``0xCAFEBABE`` is also the Java class-file magic, but the bundler only
+    ever walks a CPython tree + installed wheels, where it unambiguously means a
+    universal Mach-O.
+    """
+    if not path.is_file() or path.is_symlink():
+        return False
+    try:
+        with path.open("rb") as fh:
+            head = fh.read(4)
+    except OSError:
+        return False
+    if len(head) < 4:
+        return False
+    return struct.unpack(">I", head)[0] in _MACHO_MAGICS
+
+
+def macho_arches(path: Path) -> tuple[str, ...]:
+    """The architectures present in a Mach-O, via ``lipo -archs`` (empty on error)."""
+    proc = _run(["lipo", "-archs", str(path)], check=False)
+    if proc.returncode != 0:
+        return ()
+    return tuple(proc.stdout.split())
+
+
+def codesign_adhoc(path: Path) -> None:
+    """Ad-hoc sign a single Mach-O / bundle in place (``codesign --sign -``)."""
+    _run(["codesign", "--force", "--sign", "-", "--timestamp=none", str(path)])
+
+
+def codesign_identity(
+    path: Path, identity: str, *, entitlements: Path | None = None
+) -> None:
+    """Developer ID sign a Mach-O / bundle with Hardened Runtime + timestamp.
+
+    ``--options runtime`` (Hardened Runtime) and a secure ``--timestamp`` are
+    both notarization requirements. *entitlements* only applies to the main
+    executable, so callers pass it when sealing the ``.app`` (and the launcher),
+    not for nested dylib/so binaries.
+    """
+    cmd = [
+        "codesign",
+        "--force",
+        "--sign",
+        identity,
+        "--options",
+        "runtime",
+        "--timestamp",
+    ]
+    if entitlements is not None:
+        cmd += ["--entitlements", str(entitlements)]
+    cmd.append(str(path))
+    _run_with_retry(cmd)
+
+
+def codesign_verify(path: Path) -> bool:
+    """True if *path* has a valid signature (``codesign --verify``)."""
+    return _run(["codesign", "--verify", str(path)], check=False).returncode == 0
+
+
+def _run_with_retry(cmd: list[str]) -> None:
+    """Run *cmd* (a codesign invocation), retrying transient keychain flakiness.
+
+    Only retries errors matching ``_CODESIGN_TRANSIENT_ERRORS``; anything else
+    (a genuinely missing/expired identity, a bad entitlements plist, ...)
+    raises immediately.
+    """
+    for attempt in range(1, _CODESIGN_MAX_ATTEMPTS + 1):
+        try:
+            _run(cmd)
+            return
+        except AppBundleError as exc:
+            transient = any(m in str(exc) for m in _CODESIGN_TRANSIENT_ERRORS)
+            if not transient or attempt == _CODESIGN_MAX_ATTEMPTS:
+                raise
+            time.sleep(_CODESIGN_RETRY_DELAY_S * attempt)
+
+
+def _run(cmd: list[str], *, check: bool = True) -> subprocess.CompletedProcess:
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise AppBundleError(
+            f"required macOS tool {cmd[0]!r} not found.\n"
+            "  Install the Xcode command-line tools: xcode-select --install"
+        ) from exc
+    if check and proc.returncode != 0:
+        raise AppBundleError(
+            f"{cmd[0]} failed ({proc.returncode}): "
+            f"{(proc.stderr or proc.stdout).strip()}"
+        )
+    return proc

kivyforge/platforms/macos/native_stage.py

@@ -0,0 +1,47 @@
+"""Stage locked native binaries into the ``.app``'s ``Resources/bin`` (macos-spec).
+
+The ``[tool.kivy.macos.native.binaries]`` channel: each entry is fetched +
+SHA-256-verified from ``pylock.macos.toml`` (URL or vendored path), then staged
+into ``Contents/Resources/bin`` — a single native file copied in with its exec
+bit set, or a ``.zip`` / ``.tar.gz`` / ``.tgz`` of several extracted with a
+path-traversal guard. The directory is created only when the lock actually pins
+binaries (no empty ``bin/``). The bundle's signing sweep later covers everything
+under it.
+
+The staging mechanics live in the shared
+:mod:`kivyforge.artifacts.native_stage_util`; this module is the macOS-facing
+wrapper that translates the neutral :class:`NativeStageError` into
+``AppBundleError``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.native_stage_util import NativeStageError, stage_binaries
+
+from . import AppBundleError
+from .lock import MacosLockfile
+
+
+def stage_native_binaries(
+    lock: MacosLockfile,
+    resources: Path,
+    *,
+    project_root: Path,
+    cache: ArtifactCache | None = None,
+    no_cache: bool = False,
+) -> None:
+    """Stage every pinned native binary for the lock into ``resources/bin``."""
+    try:
+        stage_binaries(
+            lock.native_binaries,
+            resources,
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+            bin_label="Contents/Resources/bin",
+        )
+    except NativeStageError as exc:
+        raise AppBundleError(str(exc)) from exc

kivyforge/platforms/macos/notarize.py

@@ -0,0 +1,143 @@
+"""Notarize + staple the signed ``.app`` (macos-spec, Developer ID workstream).
+
+The distribution path since macOS 10.15 is **sign + notarize + staple**: zip the
+Developer-ID-signed ``.app`` (``ditto -c -k --keepParent`` preserves the bundle
+metadata Gatekeeper checks), submit it with ``xcrun notarytool submit --wait``,
+and on acceptance ``xcrun stapler staple`` the ticket into the bundle so
+Gatekeeper trusts it offline.
+
+Credentials come from a **keychain profile** created once with::
+
+    xcrun notarytool store-credentials <profile> \
+        --apple-id <you@example.com> --team-id <TEAMID> --password <app-specific>
+
+so nothing secret ever lives in ``pyproject.toml`` (CI keychains work the same
+way). ``.dmg``-level notarization stays external — kivyforge never builds
+``.dmg`` files (see common packaging scope).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+
+import click
+
+from . import AppBundleError
+
+
+def notarize_and_staple(app: Path, *, profile: str, echo=click.echo) -> None:
+    """Submit *app* to Apple's notary service and staple the ticket.
+
+    Blocks until the notary service responds (``--wait``; typically a couple of
+    minutes). On rejection, fetches the notary log and surfaces the per-file
+    issues in the error message.
+    """
+    with tempfile.TemporaryDirectory(prefix="kivyforge-notarize-") as tmp:
+        archive = Path(tmp) / f"{app.stem}.zip"
+        echo(f"Zipping {app.name} for notarization ...")
+        _run(["ditto", "-c", "-k", "--keepParent", str(app), str(archive)])
+
+        echo("Submitting to the Apple notary service (this can take minutes) ...")
+        proc = _run(
+            [
+                "xcrun",
+                "notarytool",
+                "submit",
+                str(archive),
+                "--keychain-profile",
+                profile,
+                "--wait",
+                "--output-format",
+                "json",
+            ],
+            check=False,
+        )
+        submission_id, status = _parse_submission(proc.stdout)
+        if proc.returncode != 0 and status is None:
+            raise AppBundleError(
+                f"notarytool submit failed ({proc.returncode}): "
+                f"{(proc.stderr or proc.stdout).strip()}\n"
+                f"  Check the keychain profile: `xcrun notarytool history "
+                f"--keychain-profile {profile}`."
+            )
+        if status != "Accepted":
+            raise AppBundleError(_rejection_message(submission_id, status, profile))
+        echo(f"Notarization accepted (submission {submission_id}).")
+
+    echo("Stapling the notarization ticket ...")
+    _run(["xcrun", "stapler", "staple", str(app)])
+
+
+def _parse_submission(stdout: str) -> tuple[str | None, str | None]:
+    """(submission id, status) from ``notarytool --output-format json`` output."""
+    try:
+        data = json.loads(stdout or "{}")
+    except json.JSONDecodeError:
+        return None, None
+    return data.get("id"), data.get("status")
+
+
+def _rejection_message(
+    submission_id: str | None, status: str | None, profile: str
+) -> str:
+    lines = [f"notarization was not accepted (status: {status or 'unknown'})."]
+    if submission_id:
+        log = _notary_log(submission_id, profile)
+        if log:
+            lines.append(f"  Notary log issues:\n{log}")
+        else:
+            lines.append(
+                f"  Fetch the log: `xcrun notarytool log {submission_id} "
+                f"--keychain-profile {profile}`."
+            )
+    lines.append(
+        "  Common causes: a binary missed Hardened Runtime / timestamp signing, "
+        "or the identity is not a Developer ID Application certificate."
+    )
+    return "\n".join(lines)
+
+
+def _notary_log(submission_id: str, profile: str) -> str:
+    """The notary log's per-file issues, indented; empty string on any failure."""
+    proc = _run(
+        [
+            "xcrun",
+            "notarytool",
+            "log",
+            submission_id,
+            "--keychain-profile",
+            profile,
+        ],
+        check=False,
+    )
+    if proc.returncode != 0:
+        return ""
+    try:
+        issues = json.loads(proc.stdout).get("issues") or []
+    except json.JSONDecodeError:
+        return ""
+    lines = [
+        f"    {issue.get('severity', '?')}: {issue.get('path', '?')}: "
+        f"{issue.get('message', '?')}"
+        for issue in issues
+    ]
+    return "\n".join(lines)
+
+
+def _run(cmd: list[str], *, check: bool = True) -> subprocess.CompletedProcess:
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise AppBundleError(
+            f"required macOS tool {cmd[0]!r} not found.\n"
+            "  Install the Xcode command-line tools: xcode-select --install"
+        ) from exc
+    if check and proc.returncode != 0:
+        raise AppBundleError(
+            f"{cmd[0]} failed ({proc.returncode}): "
+            f"{(proc.stderr or proc.stdout).strip()}"
+        )
+    return proc

kivyforge/platforms/macos/plist.py

@@ -0,0 +1,37 @@
+"""Build the ``.app`` ``Info.plist`` from the project config (macos-spec).
+
+kivyforge owns the identity/versioning keys (mirroring the iOS managed-plist
+discipline); there is no user Info.plist merge on macOS in this phase.
+"""
+
+from __future__ import annotations
+
+from kivyforge.config.model import Config
+
+# LSMinimumSystemVersion when the project sets none. Matches the macOS lock's
+# default pip floor so the plist and the resolved wheels agree.
+DEFAULT_MINIMUM_SYSTEM_VERSION = "11.0"
+
+
+def build_info_plist(config: Config, *, executable: str, icon_file: str | None) -> dict:
+    macos = config.macos_required
+    plist: dict[str, object] = {
+        "CFBundleName": config.display_name,
+        "CFBundleDisplayName": config.display_name,
+        "CFBundleIdentifier": macos.bundle_id,
+        "CFBundleExecutable": executable,
+        "CFBundlePackageType": "APPL",
+        "CFBundleInfoDictionaryVersion": "6.0",
+        "CFBundleShortVersionString": config.project.version,
+        "CFBundleVersion": str(macos.build),
+        "LSMinimumSystemVersion": (
+            macos.minimum_system_version or DEFAULT_MINIMUM_SYSTEM_VERSION
+        ),
+        "NSHighResolutionCapable": True,
+        # A GUI app (Kivy opens a window); without this Finder still launches it,
+        # but it is the correct declaration for a windowed, non-agent app.
+        "LSBackgroundOnly": False,
+    }
+    if icon_file is not None:
+        plist["CFBundleIconFile"] = icon_file
+    return plist