kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/android/lock/reader.py

@@ -0,0 +1,206 @@
+"""Parse ``pylock.android.toml`` back into an ``AndroidLockfile`` (android/02).
+
+The neutral drift helpers (``LockError``, ``compute_pyproject_sha256``,
+``is_in_sync``) live in ``kivyforge.lock.reader``; this module adds the Android
+``pylock.android.toml`` parsing on top. The reader fails *cleanly* on corrupt,
+hand-edited, or future-schema files — never a raw ``KeyError``.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from kivyforge.lock.pep751 import parse_package as _parse_package
+from kivyforge.lock.reader import (
+    LockError,
+    compute_pyproject_sha256,
+    is_in_sync,
+)
+
+from .model import (
+    LOCK_VERSION,
+    TOOL_SCHEMA_VERSION,
+    AndroidLockfile,
+    GradleArtifact,
+    GradlePins,
+    GradleResolvedModule,
+    LockedAndroidLib,
+    LockedIncludeFile,
+    PythonAndroidRuntime,
+)
+
+__all__ = [
+    "LockError",
+    "compute_pyproject_sha256",
+    "is_in_sync",
+    "load",
+    "loads",
+]
+
+SUPPORTED_LOCK_VERSION_MAJOR = int(LOCK_VERSION.split(".", 1)[0])
+SUPPORTED_TOOL_SCHEMA_VERSION = TOOL_SCHEMA_VERSION
+
+
+def loads(text: str) -> AndroidLockfile:
+    try:
+        raw = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise LockError(f"pylock.android.toml is not valid TOML: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise LockError("pylock.android.toml must be a TOML table.")
+    try:
+        return _from_raw(raw)
+    except LockError:
+        raise
+    except (KeyError, TypeError, AttributeError, ValueError) as exc:
+        raise LockError(f"pylock.android.toml is malformed: {exc!r}") from exc
+
+
+def load(path: str | Path) -> AndroidLockfile:
+    return loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _from_raw(raw: dict) -> AndroidLockfile:
+    lock_version = _check_lock_version(raw)
+
+    tool_raw = raw.get("tool", {})
+    if not isinstance(tool_raw, dict):
+        raise LockError("pylock.android.toml [tool] must be a table.")
+    tool = tool_raw.get("kivyforge", {})
+    if not isinstance(tool, dict) or not tool:
+        raise LockError("pylock.android.toml is missing the [tool.kivyforge] table.")
+
+    schema_version = _check_tool_schema_version(tool)
+
+    runtimes = tuple(_parse_runtime(r) for r in _as_list(tool, "python_android"))
+    if not runtimes:
+        raise LockError(
+            "pylock.android.toml has no [[tool.kivyforge.python_android]] "
+            "entries; re-run `kivyforge lock -p android`."
+        )
+    packages = tuple(_parse_package(p) for p in _as_list(raw, "packages"))
+    android_libs = tuple(_parse_lib(x) for x in _as_list(tool, "android_libs"))
+    gradle = _parse_gradle(tool.get("gradle"))
+    include_files = tuple(
+        _parse_include_file(f) for f in _as_list(tool, "include_files")
+    )
+
+    kivy_generation = tool.get("kivy_generation", 2)
+    if kivy_generation not in (2, 3):
+        raise LockError(
+            f"pylock.android.toml [tool.kivyforge].kivy_generation "
+            f"{kivy_generation!r} invalid."
+        )
+
+    return AndroidLockfile(
+        requires_python=raw.get("requires-python", ">=3.14"),
+        packages=packages,
+        python_android=runtimes,
+        kivyforge_version=tool.get("kivyforge_version", ""),
+        generated_at=tool.get("generated_at", ""),
+        pyproject_sha256=tool.get("pyproject_sha256", ""),
+        tool_kivy_android_schema_version=tool.get(
+            "tool_kivy_android_schema_version", 1
+        ),
+        kivy_generation=kivy_generation,
+        android_libs=android_libs,
+        gradle=gradle,
+        include_files=include_files,
+        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", [])),
+    )
+
+
+def _parse_runtime(entry: dict) -> PythonAndroidRuntime:
+    return PythonAndroidRuntime(
+        version=entry["version"],
+        abi=entry["abi"],
+        url=entry.get("url"),
+        path=entry.get("path"),
+        sha256=entry["sha256"],
+        min_api=int(entry.get("min_api", 24)),
+    )
+
+
+def _parse_lib(entry: dict) -> LockedAndroidLib:
+    return LockedAndroidLib(
+        name=entry["name"],
+        kind=entry["kind"],
+        version=entry["version"],
+        url=entry.get("url"),
+        path=entry.get("path"),
+        sha256=entry["sha256"],
+    )
+
+
+def _parse_gradle(table: object) -> GradlePins:
+    if table is None:
+        return GradlePins()
+    if not isinstance(table, dict):
+        raise LockError("pylock.android.toml [tool.kivyforge.gradle] must be a table.")
+    resolved = tuple(
+        GradleResolvedModule(
+            coordinate=m["coordinate"],
+            artifacts=tuple(
+                GradleArtifact(name=a["name"], sha256=a["sha256"])
+                for a in m.get("artifacts", [])
+            ),
+        )
+        for m in table.get("resolved", [])
+    )
+    return GradlePins(
+        dependencies=tuple(table.get("dependencies", [])),
+        repositories=tuple(table.get("repositories", [])),
+        resolved=resolved,
+    )
+
+
+def _parse_include_file(entry: dict) -> LockedIncludeFile:
+    return LockedIncludeFile(
+        source=entry["source"], dest=entry["dest"], sha256=entry["sha256"]
+    )
+
+
+def _check_lock_version(raw: dict) -> str:
+    lock_version = raw.get("lock-version", LOCK_VERSION)
+    if not isinstance(lock_version, str):
+        raise LockError("pylock.android.toml lock-version must be a string.")
+    major = lock_version.split(".", 1)[0]
+    if not major.isdigit():
+        raise LockError(
+            f"pylock.android.toml lock-version {lock_version!r} is not a valid version."
+        )
+    if int(major) > SUPPORTED_LOCK_VERSION_MAJOR:
+        raise LockError(
+            f"pylock.android.toml lock-version {lock_version} is newer than "
+            f"this kivyforge understands (<= {SUPPORTED_LOCK_VERSION_MAJOR}.x); "
+            "upgrade kivyforge."
+        )
+    return lock_version
+
+
+def _check_tool_schema_version(tool: dict) -> int:
+    schema_version = tool.get("schema_version", TOOL_SCHEMA_VERSION)
+    if not isinstance(schema_version, int) or isinstance(schema_version, bool):
+        raise LockError(
+            "pylock.android.toml [tool.kivyforge].schema_version must be an integer."
+        )
+    if schema_version > SUPPORTED_TOOL_SCHEMA_VERSION:
+        raise LockError(
+            f"pylock.android.toml [tool.kivyforge].schema_version "
+            f"{schema_version} is newer than this kivyforge understands "
+            f"(<= {SUPPORTED_TOOL_SCHEMA_VERSION}); upgrade kivyforge."
+        )
+    return schema_version
+
+
+def _as_list(table: dict, key: str) -> list:
+    value = table.get(key, [])
+    if not isinstance(value, list):
+        raise LockError(f"pylock.android.toml {key!r} must be an array of tables.")
+    return value

kivyforge/platforms/android/lock/resolver.py

@@ -0,0 +1,276 @@
+"""Android dependency resolver (android/02 §"Resolution semantics").
+
+Turns ``[project].dependencies`` into fully-pinned per-ABI Android wheels,
+**host-independent**: every compiled package is pinned for every ABI in
+``[tool.kivy.android].abis``, regardless of the host running ``lock``.
+
+Host-independence covers *marker evaluation*, not just wheel tags. pip's
+``--platform``/``--abi`` select acceptable tags but leave ``sys_platform`` and
+friends pointing at the machine running pip, which made the same lock succeed
+on Linux and fail on Windows. Resolution therefore runs through
+``_pip_shim.py``, which retargets ``packaging``'s marker environment at Android
+(see ``markers.py``) before handing off to pip.
+
+Mirrors the iOS resolver (same pip ``--report`` backend, same fail-fast
+semantics): a package missing any targeted ABI slice is rejected, and a
+version skew across ABIs (one ABI's wheel published before another's) is
+rejected rather than merged. The wheel-tag API level is a floor — pip's
+PEP 738 tag expansion accepts an ``android_21_*`` wheel at ``min_sdk = 24``
+(android/01 §find_links), so kivyforge never re-implements that rule.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from kivyforge.lock import _pip_shim
+from kivyforge.lock._pip_shim import MARKER_ENV_VAR
+from kivyforge.lock.model import canonical_name
+from kivyforge.lock.resolver import (
+    MIN_PIP_VERSION,
+    abi_tags,
+    dep_names_for_environment,
+    pip_python_version,
+    pip_version,
+    version_str,
+)
+
+from .markers import android_marker_environment
+
+# Run by path, not ``-m``: the shim imports nothing from kivyforge, so it also
+# works when resolving with an interpreter that only has pip installed.
+_SHIM = Path(_pip_shim.__file__)
+
+# Android wheels: android_<apilevel>_<abi> (PEP 738). pip >= 25.1 understands
+# them (including cross-download); enforce the same floor everywhere.
+MIN_ANDROID_PIP_VERSION = (25, 1)
+
+
+class ResolverError(Exception):
+    """A resolution failure (missing ABI, no matching wheel, backend error)."""
+
+
+@dataclass(frozen=True)
+class ResolvedWheel:
+    filename: str
+    url: str
+    sha256: str
+    upload_time: str | None = None
+    size: int | None = None
+
+
+@dataclass
+class ResolvedPackage:
+    name: str
+    version: str
+    wheels: list[ResolvedWheel] = field(default_factory=list)
+    requires_python: str | None = None
+    dependencies: list[str] = field(default_factory=list)
+    source_index: str | None = None
+
+
+def abi_platform_tag(min_sdk: int, abi: str) -> str:
+    """The pip ``--platform`` tag for one targeted ABI (android/06 step 4)."""
+    return f"android_{min_sdk}_{abi}"
+
+
+class Resolver(Protocol):
+    def resolve(
+        self,
+        requirements: list[str],
+        *,
+        python_version: str,
+        min_sdk: int,
+        abis: tuple[str, ...],
+        extra_index_urls: list[str],
+        find_links: list[str] | None = None,
+        offline: bool = False,
+    ) -> list[ResolvedPackage]:
+        """Resolve requirements to per-ABI Android wheels (all ABIs pinned)."""
+        ...
+
+
+class PipResolver:
+    """Default backend: stock pip cross-resolution via ``pip install --report``.
+
+    One dry-run report per targeted ABI; results merge into one
+    ``ResolvedPackage`` per distribution (pure-Python wheels dedupe by
+    filename across ABIs).
+    """
+
+    def __init__(self, python_executable: str | None = None) -> None:
+        self._python = python_executable or sys.executable
+
+    def resolve(
+        self,
+        requirements: list[str],
+        *,
+        python_version: str,
+        min_sdk: int,
+        abis: tuple[str, ...],
+        extra_index_urls: list[str],
+        find_links: list[str] | None = None,
+        offline: bool = False,
+    ) -> list[ResolvedPackage]:
+        if not requirements:
+            return []
+        self._require_modern_pip()
+        cp_abis = abi_tags(python_version)
+        merged: dict[str, ResolvedPackage] = {}
+        seen_filenames: dict[str, set[str]] = {}
+
+        for abi in abis:
+            # Markers are evaluated for the *target*, per ABI: platform_machine
+            # differs between arm64_v8a and x86_64, and packages do gate on it.
+            environment = android_marker_environment(
+                python_version=python_version, abi=abi
+            )
+            report = self._run_report(
+                requirements,
+                python_version=python_version,
+                platform_tag=abi_platform_tag(min_sdk, abi),
+                abis=cp_abis,
+                extra_index_urls=extra_index_urls,
+                find_links=find_links or [],
+                offline=offline,
+                marker_environment=environment,
+            )
+            for item in report.get("install", []):
+                self._absorb(item, merged, seen_filenames, environment)
+
+        return list(merged.values())
+
+    def _require_modern_pip(self) -> None:
+        version = pip_version(self._python)
+        floor = max(MIN_PIP_VERSION, MIN_ANDROID_PIP_VERSION)
+        if version is not None and version < floor:
+            raise ResolverError(
+                f"kivyforge needs pip >= {version_str(floor)} to resolve "
+                f"Android wheels, but {self._python} has pip "
+                f"{version_str(version)}.\n"
+                "  pip < 25.1 predates PEP 738 android platform tags, so "
+                "compatible wheels (e.g. android_24_*) are reported as missing.\n"
+                f"  Upgrade it: {self._python} -m pip install --upgrade pip"
+            )
+
+    def _absorb(self, item, merged, seen_filenames, environment) -> None:
+        meta = item.get("metadata", {})
+        name = meta.get("name")
+        version = meta.get("version")
+        download = item.get("download_info", {})
+        url = download.get("url", "")
+        if not url.endswith(".whl"):
+            # sdist/vcs/directory are refused (android/02): wheels only — the
+            # backend has no on-host cross-compile step.
+            raise ResolverError(
+                f"{name} {version} resolved to a non-wheel source ({url}); "
+                "kivyforge installs only Android wheels (no from-source "
+                "pipeline — build an android_* wheel out-of-band, android/03)."
+            )
+        archive = download.get("archive_info", {})
+        hashes = archive.get("hashes", {})
+        sha256 = hashes.get("sha256", "")
+        filename = url.rsplit("/", 1)[-1]
+        key = canonical_name(name)
+        pkg = merged.get(key)
+        if pkg is None:
+            pkg = ResolvedPackage(
+                name=name,
+                version=version,
+                requires_python=meta.get("requires_python"),
+                dependencies=dep_names_for_environment(
+                    meta.get("requires_dist", []), environment
+                ),
+            )
+            merged[key] = pkg
+            seen_filenames[key] = set()
+        elif version != pkg.version:
+            # Each ABI is a separate pip resolution; if upstream published the
+            # ABIs at different times they can disagree on version. Merging
+            # would produce a lock that installs mismatched binaries per ABI.
+            raise ResolverError(
+                f"{name} resolved to inconsistent versions across Android ABIs: "
+                f"{pkg.version!r} and {version!r}. Re-lock once upstream "
+                "publishes the lagging ABI (android/02 fail-fast)."
+            )
+        if filename not in seen_filenames[key]:
+            seen_filenames[key].add(filename)
+            pkg.wheels.append(ResolvedWheel(filename=filename, url=url, sha256=sha256))
+
+    def _run_report(
+        self,
+        requirements: list[str],
+        *,
+        python_version: str,
+        platform_tag: str,
+        abis: tuple[str, ...],
+        extra_index_urls: list[str],
+        find_links: list[str],
+        offline: bool,
+        marker_environment: dict[str, str],
+    ) -> dict:
+        with tempfile.TemporaryDirectory(prefix="kivy-lock-") as tmp:
+            report_path = Path(tmp) / "report.json"
+            # Not "-m pip": the shim retargets marker evaluation at the Android
+            # environment first, then runs pip unchanged (see _pip_shim.py).
+            cmd = [
+                self._python,
+                str(_SHIM),
+                "install",
+                "--dry-run",
+                "--ignore-installed",
+                "--only-binary=:all:",
+                "--python-version",
+                pip_python_version(python_version),
+                "--implementation",
+                "cp",
+                "--platform",
+                platform_tag,
+                "--target",
+                str(Path(tmp) / "target"),
+                "--report",
+                str(report_path),
+            ]
+            for abi in abis:
+                cmd += ["--abi", abi]
+            for index in extra_index_urls:
+                cmd += ["--extra-index-url", index]
+            for link in find_links:
+                cmd += ["--find-links", link]
+            if offline:
+                cmd += ["--no-index"]
+            cmd += list(requirements)
+
+            env = dict(os.environ)
+            env[MARKER_ENV_VAR] = json.dumps(marker_environment)
+            proc = subprocess.run(cmd, capture_output=True, text=True, env=env)
+            if proc.returncode != 0:
+                raise ResolverError(
+                    f"pip could not resolve the Android ABI {platform_tag!r}.\n"
+                    f"  This usually means a dependency has no android_* wheel "
+                    f"for that ABI (vendor one via find_links, android/03).\n"
+                    f"  pip said:\n{_indent(proc.stderr or proc.stdout)}"
+                )
+            try:
+                # pip writes the report as UTF-8; never trust the locale codec
+                # (cp1252 on Windows chokes on non-ASCII package metadata).
+                return json.loads(report_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError) as exc:
+                raise ResolverError(f"could not read pip report: {exc}") from exc
+
+
+def get_resolver(backend: str = "pip", **kwargs) -> Resolver:
+    if backend == "pip":
+        return PipResolver(**kwargs)
+    raise ResolverError(f"unknown resolver backend {backend!r} (expected pip)")
+
+
+def _indent(text: str) -> str:
+    return "\n".join(f"    {line}" for line in (text or "").splitlines())

kivyforge/platforms/android/lock/writer.py

@@ -0,0 +1,121 @@
+"""Serialize an ``AndroidLockfile`` to ``pylock.android.toml`` text (android/02).
+
+Hand-rolled emitter like the iOS writer: exact PEP 751 layout via the shared
+``kivyforge.lock.pep751`` helpers, deterministic ordering everywhere (packages
+by name/version, wheels by filename, runtimes by ABI, libs by name, resolved
+Maven modules by coordinate) so re-lock diffs show only real changes.
+"""
+
+from __future__ import annotations
+
+from kivyforge.lock.pep751 import arr as _arr
+from kivyforge.lock.pep751 import emit_package as _emit_package
+from kivyforge.lock.pep751 import s as _s
+
+from .model import (
+    AndroidLockfile,
+    GradleResolvedModule,
+    LockedAndroidLib,
+    PythonAndroidRuntime,
+)
+
+
+def dumps(lock: AndroidLockfile) -> str:
+    lines: list[str] = []
+
+    # --- PEP 751 top-level scalars ---
+    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("")
+
+    # --- [[packages]] (deterministic order) ---
+    for pkg in sorted(lock.packages, key=lambda p: p.sort_key):
+        _emit_package(lines, pkg)
+
+    # --- [tool.kivyforge] extension ---
+    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_kivy_android_schema_version = {lock.tool_kivy_android_schema_version}"
+    )
+    lines.append(f"kivy_generation = {lock.kivy_generation}")
+
+    # --- [[tool.kivyforge.python_android]] (one per ABI, sorted) ---
+    for runtime in sorted(lock.python_android, key=lambda r: r.abi):
+        lines.append("")
+        _emit_runtime(lines, runtime)
+
+    # --- [[tool.kivyforge.android_libs]] ---
+    for lib in sorted(lock.android_libs, key=lambda x: (x.name.lower(), x.version)):
+        lines.append("")
+        _emit_android_lib(lines, lib)
+
+    # --- [tool.kivyforge.gradle] (only when Maven deps are declared) ---
+    if lock.gradle.declared:
+        lines.append("")
+        lines.append("[tool.kivyforge.gradle]")
+        lines.append(f"dependencies = {_arr(lock.gradle.dependencies)}")
+        lines.append(f"repositories = {_arr(lock.gradle.repositories)}")
+        for module in sorted(lock.gradle.resolved, key=lambda m: m.coordinate):
+            lines.append("")
+            _emit_resolved_module(lines, module)
+
+    # --- [[tool.kivyforge.include_files]] ---
+    for pin in sorted(lock.include_files, key=lambda p: (p.dest, p.source)):
+        lines.append("")
+        lines.append("[[tool.kivyforge.include_files]]")
+        lines.append(f"source = {_s(pin.source)}")
+        lines.append(f"dest = {_s(pin.dest)}")
+        lines.append(f"sha256 = {_s(pin.sha256)}")
+
+    return "\n".join(lines) + "\n"
+
+
+def _emit_runtime(lines: list[str], runtime: PythonAndroidRuntime) -> None:
+    lines.append("[[tool.kivyforge.python_android]]")
+    lines.append(f"version = {_s(runtime.version)}")
+    lines.append(f"abi = {_s(runtime.abi)}")
+    if runtime.url:
+        lines.append(f"url = {_s(runtime.url)}")
+    else:
+        path = runtime.path
+        assert path is not None
+        lines.append(f"path = {_s(path)}")
+    lines.append(f"sha256 = {_s(runtime.sha256)}")
+    lines.append(f"min_api = {runtime.min_api}")
+
+
+def _emit_android_lib(lines: list[str], lib: LockedAndroidLib) -> None:
+    lines.append("[[tool.kivyforge.android_libs]]")
+    lines.append(f"name = {_s(lib.name)}")
+    lines.append(f"kind = {_s(lib.kind)}")
+    lines.append(f"version = {_s(lib.version)}")
+    if lib.url:
+        lines.append(f"url = {_s(lib.url)}")
+    else:
+        path = lib.path
+        assert path is not None
+        lines.append(f"path = {_s(path)}")
+    lines.append(f"sha256 = {_s(lib.sha256)}")
+
+
+def _emit_resolved_module(lines: list[str], module: GradleResolvedModule) -> None:
+    lines.append("[[tool.kivyforge.gradle.resolved]]")
+    lines.append(f"coordinate = {_s(module.coordinate)}")
+    artifacts = sorted(module.artifacts, key=lambda a: a.name)
+    if not artifacts:
+        lines.append("artifacts = []")
+        return
+    lines.append("artifacts = [")
+    for artifact in artifacts:
+        lines.append(
+            f"    {{ name = {_s(artifact.name)}, sha256 = {_s(artifact.sha256)} }},"
+        )
+    lines.append("]")