kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/lock/wheelruntime/serialize.py

@@ -0,0 +1,245 @@
+"""Serialize/parse ``pylock.<platform>.toml`` for the wheel+runtime family.
+
+Reuses the platform-neutral PEP 751 ``[[packages]]`` emitter/parser
+(``kivyforge.lock.pep751``) and adds the ``[tool.kivyforge]`` extension: the arch
+set plus the bundled Python runtime pin (provider + per-arch artifacts). The
+platform is carried by the filename, so ``loads``/``load`` take it explicitly
+(used only for clear error messages and to stamp the model).
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from ..model import LOCK_VERSION
+from ..pep751 import arr as _arr
+from ..pep751 import emit_package as _emit_package
+from ..pep751 import parse_package as _parse_package
+from ..pep751 import s as _s
+from ..reader import LockError
+from .model import (
+    TOOL_SCHEMA_VERSION,
+    LockedNativeBinary,
+    PythonRuntime,
+    RuntimeArtifact,
+    WheelRuntimeLock,
+)
+
+SUPPORTED_LOCK_VERSION_MAJOR = int(LOCK_VERSION.split(".", 1)[0])
+SUPPORTED_TOOL_SCHEMA_VERSION = TOOL_SCHEMA_VERSION
+
+
+def dumps(lock: WheelRuntimeLock) -> str:
+    lines: list[str] = []
+
+    lines.append(f"lock-version = {_s(lock.lock_version)}")
+    lines.append(f"created-by = {_s(lock.created_by)}")
+    lines.append(f"requires-python = {_s(lock.requires_python)}")
+    lines.append(f"extras = {_arr(lock.extras)}")
+    lines.append(f"dependency-groups = {_arr(lock.dependency_groups)}")
+    lines.append(f"default-groups = {_arr(lock.default_groups)}")
+    lines.append("")
+
+    for pkg in sorted(lock.packages, key=lambda p: p.sort_key):
+        _emit_package(lines, pkg)
+
+    lines.append("[tool.kivyforge]")
+    lines.append(f"schema_version = {lock.schema_version}")
+    lines.append(f"kivyforge_version = {_s(lock.kivyforge_version)}")
+    lines.append(f"generated_at = {_s(lock.generated_at)}")
+    lines.append(f"pyproject_sha256 = {_s(lock.pyproject_sha256)}")
+    lines.append(
+        f"tool_kivyforge_schema_version = {lock.tool_kivyforge_schema_version}"
+    )
+    lines.append(f"archs = {_arr(lock.archs)}")
+    lines.append("")
+    lines.append("[tool.kivyforge.python_runtime]")
+    lines.append(f"provider = {_s(lock.python_runtime.provider)}")
+    lines.append(f"version = {_s(lock.python_runtime.version)}")
+    if lock.python_runtime.floor:
+        lines.append(f"floor = {_s(lock.python_runtime.floor)}")
+
+    for art in sorted(lock.python_runtime.artifacts, key=lambda a: a.arch):
+        lines.append("")
+        lines.append("[[tool.kivyforge.python_runtime.artifacts]]")
+        lines.append(f"arch = {_s(art.arch)}")
+        lines.append(f"url = {_s(art.url)}")
+        lines.append(f"sha256 = {_s(art.sha256)}")
+        lines.append(f"archive_format = {_s(art.archive_format)}")
+
+    for nb in sorted(lock.native_binaries, key=lambda b: b.name):
+        lines.append("")
+        lines.append("[[tool.kivyforge.native_binaries]]")
+        lines.append(f"name = {_s(nb.name)}")
+        lines.append(f"version = {_s(nb.version)}")
+        if nb.url is not None:
+            lines.append(f"url = {_s(nb.url)}")
+        else:
+            lines.append(f"path = {_s(nb.path)}")
+        lines.append(f"sha256 = {_s(nb.sha256)}")
+
+    return "\n".join(lines) + "\n"
+
+
+def loads(text: str, *, platform: str) -> WheelRuntimeLock:
+    name = f"pylock.{platform}.toml"
+    try:
+        raw = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise LockError(f"{name} is not valid TOML: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise LockError(f"{name} must be a TOML table.")
+    try:
+        return _from_raw(raw, platform=platform, name=name)
+    except LockError:
+        raise
+    except (KeyError, TypeError, AttributeError, ValueError) as exc:
+        raise LockError(f"{name} is malformed: {exc!r}") from exc
+
+
+def load(path: str | Path, *, platform: str) -> WheelRuntimeLock:
+    return loads(Path(path).read_text(encoding="utf-8"), platform=platform)
+
+
+def _from_raw(raw: dict, *, platform: str, name: str) -> WheelRuntimeLock:
+    lock_version = _check_lock_version(raw, name)
+
+    tool_raw = raw.get("tool", {})
+    if not isinstance(tool_raw, dict):
+        raise LockError(f"{name} [tool] must be a table.")
+    tool = tool_raw.get("kivyforge", {})
+    if not isinstance(tool, dict) or not tool:
+        raise LockError(f"{name} is missing the [tool.kivyforge] table.")
+
+    schema_version = _check_tool_schema_version(tool)
+    runtime = _parse_runtime(tool, name)
+    native_binaries = _parse_native_binaries(tool, name)
+
+    packages = tuple(_parse_package(p) for p in _as_list(raw, "packages", name))
+
+    return WheelRuntimeLock(
+        platform=platform,
+        requires_python=raw.get("requires-python", ">=3.15"),
+        packages=packages,
+        python_runtime=runtime,
+        archs=tuple(tool.get("archs", [])),
+        kivyforge_version=tool.get("kivyforge_version", ""),
+        generated_at=tool.get("generated_at", ""),
+        pyproject_sha256=tool.get("pyproject_sha256", ""),
+        tool_kivyforge_schema_version=tool.get("tool_kivyforge_schema_version", 1),
+        schema_version=schema_version,
+        lock_version=lock_version,
+        created_by=raw.get("created-by", "kivyforge"),
+        extras=tuple(raw.get("extras", [])),
+        dependency_groups=tuple(raw.get("dependency-groups", [])),
+        default_groups=tuple(raw.get("default-groups", [])),
+        native_binaries=native_binaries,
+    )
+
+
+def _check_lock_version(raw: dict, name: str) -> str:
+    lock_version = raw.get("lock-version", LOCK_VERSION)
+    if not isinstance(lock_version, str):
+        raise LockError(f"{name} lock-version must be a string.")
+    major = lock_version.split(".", 1)[0]
+    if not major.isdigit():
+        raise LockError(f"{name} lock-version {lock_version!r} is not a valid version.")
+    if int(major) > SUPPORTED_LOCK_VERSION_MAJOR:
+        raise LockError(
+            f"{name} lock-version {lock_version} is newer than this kivyforge "
+            f"understands (max {SUPPORTED_LOCK_VERSION_MAJOR}.x). Upgrade kivyforge."
+        )
+    return lock_version
+
+
+def _check_tool_schema_version(tool: dict) -> int:
+    schema_version = tool.get("schema_version", SUPPORTED_TOOL_SCHEMA_VERSION)
+    if not isinstance(schema_version, int) or isinstance(schema_version, bool):
+        raise LockError("[tool.kivyforge].schema_version must be an integer.")
+    if schema_version > SUPPORTED_TOOL_SCHEMA_VERSION:
+        raise LockError(
+            f"[tool.kivyforge].schema_version {schema_version} is newer than this "
+            f"kivyforge understands (max {SUPPORTED_TOOL_SCHEMA_VERSION}). "
+            "Upgrade kivyforge."
+        )
+    return schema_version
+
+
+def _parse_runtime(tool: dict, name: str) -> PythonRuntime:
+    rt = tool.get("python_runtime")
+    if not isinstance(rt, dict) or not rt:
+        raise LockError(f"{name} is missing [tool.kivyforge.python_runtime].")
+    for field in ("provider", "version"):
+        value = rt.get(field)
+        if not isinstance(value, str) or not value:
+            raise LockError(
+                f"[tool.kivyforge.python_runtime].{field} is missing or empty."
+            )
+    artifacts_raw = rt.get("artifacts", [])
+    if not isinstance(artifacts_raw, list) or not artifacts_raw:
+        raise LockError(
+            "[tool.kivyforge.python_runtime] must list at least one artifact."
+        )
+    artifacts = []
+    for a in artifacts_raw:
+        for field in ("arch", "url", "sha256"):
+            if not isinstance(a.get(field), str) or not a.get(field):
+                raise LockError(
+                    f"a [tool.kivyforge.python_runtime.artifacts] entry is "
+                    f"missing {field!r}."
+                )
+        artifacts.append(
+            RuntimeArtifact(
+                arch=a["arch"],
+                url=a["url"],
+                sha256=a["sha256"],
+                archive_format=a.get("archive_format", "tar.gz"),
+            )
+        )
+    return PythonRuntime(
+        provider=rt["provider"],
+        version=rt["version"],
+        artifacts=tuple(artifacts),
+        floor=rt.get("floor"),
+    )
+
+
+def _parse_native_binaries(tool: dict, name: str) -> tuple[LockedNativeBinary, ...]:
+    raw = tool.get("native_binaries", [])
+    if not isinstance(raw, list):
+        raise LockError(f"{name} [tool.kivyforge.native_binaries] must be an array.")
+    out: list[LockedNativeBinary] = []
+    for entry in raw:
+        if not isinstance(entry, dict):
+            raise LockError(
+                f"{name} [[tool.kivyforge.native_binaries]] entries must be tables."
+            )
+        for field in ("name", "version", "sha256"):
+            if not isinstance(entry.get(field), str) or not entry.get(field):
+                raise LockError(
+                    f"a [[tool.kivyforge.native_binaries]] entry is missing {field!r}."
+                )
+        url = entry.get("url")
+        path = entry.get("path")
+        if bool(url) == bool(path):
+            raise LockError(
+                f"native binary {entry['name']!r} must have exactly one of url/path."
+            )
+        out.append(
+            LockedNativeBinary(
+                name=entry["name"],
+                version=entry["version"],
+                sha256=entry["sha256"],
+                url=url,
+                path=path,
+            )
+        )
+    return tuple(sorted(out, key=lambda b: b.name))
+
+
+def _as_list(table: dict, key: str, name: str) -> list:
+    value = table.get(key, [])
+    if not isinstance(value, list):
+        raise LockError(f"{name} {key!r} must be an array of tables.")
+    return value

kivyforge/platforms/__init__.py

@@ -0,0 +1,114 @@
+"""Platform backend registry + target resolution (common design docs 02, 05).
+
+The registry is a plain, static dict of in-repo backends — no entry-point plugin
+discovery yet (it can be added later without changing callers). ``resolve_target``
+implements the documented resolution chain:
+
+    --platform / -p  >  KIVYFORGE_PLATFORM  >  host OS  >  actionable error
+"""
+
+from __future__ import annotations
+
+import platform as _platform
+from collections.abc import Collection, Mapping
+
+from .android import AndroidPlatform
+from .base import HostCapabilityError, Platform
+from .ios import IosPlatform
+from .linux import LinuxPlatform
+from .macos import MacosPlatform
+from .windows import WindowsPlatform
+
+__all__ = [
+    "HostCapabilityError",
+    "Platform",
+    "PlatformResolutionError",
+    "PLATFORM_ENV_VAR",
+    "available_platform_names",
+    "get_platform",
+    "resolve_target",
+]
+
+PLATFORM_ENV_VAR = "KIVYFORGE_PLATFORM"
+
+# Registered backends, in display order. Add new platforms here.
+_REGISTRY: tuple[Platform, ...] = (
+    IosPlatform(),
+    MacosPlatform(),
+    LinuxPlatform(),
+    WindowsPlatform(),
+    AndroidPlatform(),
+)
+
+# name/alias -> backend
+_BY_SELECTOR: dict[str, Platform] = {
+    selector: backend for backend in _REGISTRY for selector in backend.selectors
+}
+
+
+class PlatformResolutionError(Exception):
+    """No target platform could be resolved from CLI/env/host."""
+
+
+def available_platform_names() -> list[str]:
+    """Canonical names of registered platforms (for ``click.Choice``)."""
+    return [backend.name for backend in _REGISTRY]
+
+
+def get_platform(name: str) -> Platform:
+    """Return the backend registered under ``name`` or an alias."""
+    try:
+        return _BY_SELECTOR[name]
+    except KeyError:
+        raise PlatformResolutionError(
+            f"unknown platform {name!r}; "
+            f"registered: {', '.join(available_platform_names())}"
+        ) from None
+
+
+def resolve_target(
+    cli_platform: str | None,
+    *,
+    configured: Collection[str],
+    env: Mapping[str, str] | None = None,
+    host_system: str | None = None,
+    verb: str = "build",
+) -> Platform:
+    """Resolve the target platform per the documented chain.
+
+    ``configured`` is the set of platform names whose overlay this project's
+    ``pyproject.toml`` actually declares (e.g. ``{"ios"}`` for ``[tool.kivy.ios]``).
+    ``env``/``host_system`` are injectable for testing. ``verb`` names the CLI
+    command that called this (e.g. ``"lock"``, ``"run"``) purely so the error
+    message's example command is accurate; it never affects resolution.
+    """
+    env = env if env is not None else {}
+
+    # 1. explicit --platform / -p
+    if cli_platform:
+        return get_platform(cli_platform)
+
+    # 2. KIVYFORGE_PLATFORM session/CI default
+    env_platform = env.get(PLATFORM_ENV_VAR)
+    if env_platform:
+        return get_platform(env_platform)
+
+    # 3. host OS -> its own platform, only if registered *and* configured
+    host = host_system if host_system is not None else _platform.system()
+    for backend in _REGISTRY:
+        if backend.host_system == host and backend.name in configured:
+            return backend
+
+    # 4. actionable error
+    raise PlatformResolutionError(_resolution_help(configured, verb))
+
+
+def _resolution_help(configured: Collection[str], verb: str = "build") -> str:
+    configured_list = ", ".join(sorted(configured)) or "none"
+    example = sorted(configured)[0] if configured else "macos"
+    return (
+        "no target platform resolved.\n"
+        f"  Pass one explicitly:      kivyforge {verb} --platform {example}\n"
+        f"  Or set a session default: export {PLATFORM_ENV_VAR}={example}\n"
+        f"  (Configured platforms in this pyproject.toml: {configured_list})"
+    )

kivyforge/platforms/android/__init__.py

@@ -0,0 +1,140 @@
+"""Android platform backend (docs/design/platforms/android/01-08).
+
+Produces a Gradle/AGP project from ``pyproject.toml`` + ``pylock.android.toml``
+— the ABI-independent Python asset bundle, flattened extension ``.so``s in
+``jniLibs/<abi>/``, the kivyforge-owned bootstrap (stock SDL Java glue +
+``PythonActivity`` + the ``SDL_main`` native launcher), and a signed ``.apk`` /
+``.aab``. Android is a cross-compiled target: no host OS maps to it as a
+default, so it always needs explicit ``-p android`` (or ``KIVYFORGE_PLATFORM``).
+Any desktop host can build: the backend consumes prebuilt wheels + the prebuilt
+python.org runtime and drives Gradle/SDK/NDK, all cross-platform.
+
+The load model this backend generates was proven on-device before any of this
+code was written — see docs/design/dev/android-loadmodel-findings.md.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from ..base import Platform
+
+if TYPE_CHECKING:
+    from kivyforge.doctor.result import CheckResult
+
+
+class AndroidBuildError(Exception):
+    """An Android build/stage failure surfaced with an actionable message."""
+
+
+class AndroidPlatform(Platform):
+    name = "android"
+    aliases = ()
+    # Cross-compiled target: never a host default (resolution-chain step 3).
+    host_system = None
+    # apk = sideload/CI unit (default); aab = Play upload unit.
+    package_formats = ("apk", "aab")
+
+    def check_host_capability(self, *, host_system: str | None = None) -> None:
+        # Windows, macOS, and Linux hosts can all build for Android: kivyforge
+        # consumes prebuilt wheels + the prebuilt python.org runtime and drives
+        # Gradle + the Android SDK/NDK, which are cross-platform (android/06
+        # §host support). Host *adequacy* (JDK, SDK, NDK present) is doctor's
+        # job, not a capability gate.
+        return
+
+    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:
+        # `target` carries the iOS-only selectors. Without --debug, build stops
+        # after generating the project; with it, Gradle assembles the debug
+        # artifact (android/06 step 8). `--abi` is the Android spelling of the
+        # ABI restriction; `--arch` is accepted for it too.
+        self.reject_ios_only_target(target)
+        from .cli import android_build
+
+        android_build(
+            project_root,
+            debug=debug,
+            fmt=fmt or "apk",
+            abi=abi or 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 android_run
+
+        android_run(
+            project_root,
+            no_build=no_build,
+            abi=arch,
+            serial=destination,
+        )
+
+    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 android_package
+
+        android_package(
+            project_root,
+            fmt=fmt,
+            abi=abi or arch,
+            keystore=keystore,
+            key_alias=key_alias,
+            no_verify_lock=no_verify_lock,
+            no_cache=no_cache,
+        )
+
+    def status(self, project_root: Path) -> None:
+        from .cli import android_status
+
+        android_status(project_root)
+
+    def open_project(self, project_root: Path) -> None:
+        from .cli import android_open
+
+        android_open(project_root)
+
+    def doctor(
+        self, cwd: Path, *, kivyforge_version: str, offline: bool
+    ) -> list[CheckResult]:
+        from .doctor import android_doctor
+
+        return android_doctor(cwd, kivyforge_version=kivyforge_version, offline=offline)