kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/android/lock/maven.py

@@ -0,0 +1,252 @@
+"""Gradle/Maven channel resolution for the lock (android/02, channel 4).
+
+``kivyforge lock`` emits the declared coordinates into a **scratch** Gradle
+project, runs Gradle with dependency verification metadata generation
+(``--write-verification-metadata sha256``) against a task that force-resolves
+the runtime classpath, and parses the resulting
+``gradle/verification-metadata.xml`` into ``[[tool.kivyforge.gradle.resolved]]``
+pins. The values live **in the lock**; ``kivyforge build`` later materializes
+``app/gradle.lockfile`` + ``gradle/verification-metadata.xml`` into the
+generated project from these pins (android/02 §gradle pins).
+
+The Gradle invocation is behind the ``GradleMavenResolver`` protocol so unit
+tests inject a fake and stay hermetic; the metadata parser is pure and tested
+against recorded XML. A JDK is required only when Maven dependencies are
+actually declared (android/06 §lock).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Protocol
+
+from kivyforge.config.model import AndroidGradleConfig
+
+from .model import GradleArtifact, GradlePins, GradleResolvedModule
+
+_VERIFICATION_NS = "{https://schema.gradle.org/dependency-verification}"
+
+
+class MavenResolverError(Exception):
+    pass
+
+
+class GradleMavenResolver(Protocol):
+    def resolve(
+        self, gradle: AndroidGradleConfig, *, offline: bool = False
+    ) -> tuple[GradleResolvedModule, ...]: ...
+
+
+def resolve_gradle_pins(
+    gradle: AndroidGradleConfig,
+    *,
+    resolver: GradleMavenResolver | None = None,
+    offline: bool = False,
+) -> GradlePins:
+    """Resolve the declared coordinates into hash-pinned modules.
+
+    Skipped entirely (empty pins) when no dependencies are declared — the
+    common Kivy case never needs a JDK at lock time.
+    """
+    if not gradle.dependencies:
+        return GradlePins()
+    backend = resolver or ScratchProjectResolver()
+    resolved = backend.resolve(gradle, offline=offline)
+    return GradlePins(
+        dependencies=tuple(gradle.dependencies),
+        repositories=tuple(gradle.repositories),
+        resolved=resolved,
+    )
+
+
+def parse_verification_metadata(xml_text: str) -> tuple[GradleResolvedModule, ...]:
+    """Parse Gradle's ``verification-metadata.xml`` into resolved-module pins.
+
+    The document shape (Gradle dependency-verification schema):
+    ``<verification-metadata><components><component group= name= version=>
+    <artifact name=...><sha256 value=.../></artifact>...`` — one component per
+    resolved module, one artifact per downloaded file.
+    """
+    try:
+        root = ET.fromstring(xml_text)
+    except ET.ParseError as exc:
+        raise MavenResolverError(
+            f"could not parse Gradle verification-metadata.xml: {exc}"
+        ) from exc
+    modules: list[GradleResolvedModule] = []
+    for component in root.iter(f"{_VERIFICATION_NS}component"):
+        group = component.get("group", "")
+        name = component.get("name", "")
+        version = component.get("version", "")
+        artifacts: list[GradleArtifact] = []
+        for artifact in component.findall(f"{_VERIFICATION_NS}artifact"):
+            sha = artifact.find(f"{_VERIFICATION_NS}sha256")
+            value = sha.get("value", "") if sha is not None else ""
+            if value:
+                artifacts.append(
+                    GradleArtifact(name=artifact.get("name", ""), sha256=value)
+                )
+        modules.append(
+            GradleResolvedModule(
+                coordinate=f"{group}:{name}:{version}",
+                artifacts=tuple(sorted(artifacts, key=lambda a: a.name)),
+            )
+        )
+    modules.sort(key=lambda m: m.coordinate)
+    return tuple(modules)
+
+
+# --------------------------------------------------------------------------- #
+# Default backend: a scratch Gradle project.
+# --------------------------------------------------------------------------- #
+
+_SETTINGS_GRADLE = """\
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+%(extra_repos)s
+    }
+}
+rootProject.name = "kivyforge-maven-lock"
+"""
+
+# A plain JVM project with an Android-attribute-tolerant configuration: the
+# lenient artifact view lets .aar-packaged AndroidX modules resolve without
+# AGP, since the lock only needs the *graph + bytes*, not a compiled classpath.
+_BUILD_GRADLE = """\
+plugins { id 'java-library' }
+
+configurations {
+    kivyforgeLock {
+        canBeConsumed = false
+        canBeResolved = true
+        attributes {
+            attribute(Attribute.of('artifactType', String), 'jar')
+        }
+    }
+}
+
+dependencies {
+%(dependencies)s
+}
+
+// Force full artifact download so verification metadata covers every file.
+tasks.register('kivyforgeResolveAll') {
+    doLast {
+        def seen = configurations.kivyforgeLock.incoming.artifactView {
+            lenient = true
+        }.files.files
+        println "kivyforge: resolved ${seen.size()} artifact files"
+    }
+}
+"""
+
+
+class ScratchProjectResolver:
+    """Run Gradle in a temp project and harvest verification metadata.
+
+    Uses a standalone ``gradle`` if one is on PATH; otherwise stages kivyforge's
+    vendored Gradle wrapper into the scratch project and runs it (the same
+    wrapper `build` uses), so a project only needs a JDK — not a separate Gradle
+    install — for the Maven lock.
+    """
+
+    _WRAPPER_DIR = Path(__file__).parent.parent / "gradle_wrapper"
+
+    def __init__(self, gradle_executable: str | None = None) -> None:
+        self._gradle = gradle_executable
+
+    def resolve(
+        self, gradle: AndroidGradleConfig, *, offline: bool = False
+    ) -> tuple[GradleResolvedModule, ...]:
+        with tempfile.TemporaryDirectory(prefix="kivyforge-maven-") as tmp:
+            root = Path(tmp)
+            extra = "\n".join(
+                f"        maven {{ url = uri({_groovy_str(u)}) }}"
+                for u in gradle.repositories
+            )
+            deps = "\n".join(
+                f"    kivyforgeLock {_groovy_str(c)}" for c in gradle.dependencies
+            )
+            (root / "settings.gradle").write_text(
+                _SETTINGS_GRADLE % {"extra_repos": extra}, encoding="utf-8"
+            )
+            (root / "build.gradle").write_text(
+                _BUILD_GRADLE % {"dependencies": deps}, encoding="utf-8"
+            )
+            exe = self._gradle_command(root)
+            cmd = [
+                *exe,
+                "--no-daemon",
+                "--console=plain",
+                "--write-verification-metadata",
+                "sha256",
+                "kivyforgeResolveAll",
+            ]
+            if offline:
+                cmd.append("--offline")
+            proc = subprocess.run(cmd, cwd=root, capture_output=True, text=True)
+            if proc.returncode != 0:
+                raise MavenResolverError(
+                    "Gradle could not resolve the declared Maven coordinates.\n"
+                    f"  Gradle said:\n{_indent(proc.stderr or proc.stdout)}"
+                )
+            metadata = root / "gradle" / "verification-metadata.xml"
+            if not metadata.is_file():
+                raise MavenResolverError(
+                    "Gradle wrote no verification-metadata.xml; cannot pin the "
+                    "resolved Maven graph."
+                )
+            return parse_verification_metadata(metadata.read_text(encoding="utf-8"))
+
+    def _gradle_command(self, root: Path) -> list[str]:
+        """A standalone gradle if present, else the vendored wrapper in ``root``."""
+        if self._gradle:
+            return [self._gradle]
+        standalone = shutil.which("gradle")
+        if standalone:
+            return [standalone]
+        jar = self._WRAPPER_DIR / "gradle-wrapper.jar"
+        if not jar.is_file():
+            raise MavenResolverError(
+                "[tool.kivy.android.gradle].dependencies is declared, but "
+                "neither a standalone `gradle` nor the vendored wrapper is "
+                "available (a JDK is still required for this channel; "
+                "android/06 §lock)."
+            )
+        import os as _os
+
+        wrapper = root / "gradle" / "wrapper"
+        wrapper.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(jar, wrapper / "gradle-wrapper.jar")
+        (wrapper / "gradle-wrapper.properties").write_text(
+            "distributionBase=GRADLE_USER_HOME\n"
+            "distributionPath=wrapper/dists\n"
+            "distributionUrl=https\\://services.gradle.org/distributions/"
+            "gradle-8.11.1-bin.zip\n"
+            "zipStoreBase=GRADLE_USER_HOME\n"
+            "zipStorePath=wrapper/dists\n",
+            encoding="utf-8",
+        )
+        for script in ("gradlew", "gradlew.bat"):
+            src = self._WRAPPER_DIR / script
+            if src.is_file():
+                dst = root / script
+                shutil.copy2(src, dst)
+                if script == "gradlew":
+                    dst.chmod(dst.stat().st_mode | 0o111)
+        return [str(root / ("gradlew.bat" if _os.name == "nt" else "gradlew"))]
+
+
+def _groovy_str(value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace("'", "\\'")
+    return f"'{escaped}'"
+
+
+def _indent(text: str) -> str:
+    return "\n".join(f"    {line}" for line in (text or "").splitlines())

kivyforge/platforms/android/lock/model.py

@@ -0,0 +1,113 @@
+"""In-memory model of ``pylock.android.toml`` (android/02).
+
+PEP 751-shaped ``[[packages]]`` (shared ``LockedPackage``/``LockedWheel``) plus
+the Android ``[tool.kivyforge]`` extension: the per-ABI python.org runtime,
+``.aar``/``.jar`` pins, the Gradle/Maven resolved graph, and the
+``include_files`` drift pins.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from kivyforge.lock.model import LOCK_VERSION, LockedPackage
+
+CREATED_BY = "kivyforge"
+TOOL_SCHEMA_VERSION = 1
+# Android's CPython floor (Tier 3; android/02 requires-python fallback).
+DEFAULT_REQUIRES_PYTHON = ">=3.14"
+
+
+@dataclass(frozen=True)
+class PythonAndroidRuntime:
+    """One ``[[tool.kivyforge.python_android]]`` entry (per ABI)."""
+
+    version: str
+    abi: str
+    sha256: str
+    min_api: int
+    url: str | None = None
+    path: str | None = None
+
+    def __post_init__(self) -> None:
+        if bool(self.url) == bool(self.path):
+            raise ValueError(
+                f"python_android {self.abi!r} must have exactly one of url/path"
+            )
+
+
+@dataclass(frozen=True)
+class LockedAndroidLib:
+    """One ``[[tool.kivyforge.android_libs]]`` entry (.aar/.jar, channel 3)."""
+
+    name: str
+    kind: str  # "aar" | "jar"
+    version: str
+    sha256: str
+    url: str | None = None
+    path: str | None = None
+
+    def __post_init__(self) -> None:
+        if bool(self.url) == bool(self.path):
+            raise ValueError(
+                f"android lib {self.name!r} must have exactly one of url/path"
+            )
+
+
+@dataclass(frozen=True)
+class GradleArtifact:
+    """One downloaded artifact of a resolved Maven module."""
+
+    name: str
+    sha256: str
+
+
+@dataclass(frozen=True)
+class GradleResolvedModule:
+    """One ``[[tool.kivyforge.gradle.resolved]]`` entry."""
+
+    coordinate: str
+    artifacts: tuple[GradleArtifact, ...]
+
+
+@dataclass(frozen=True)
+class GradlePins:
+    """``[tool.kivyforge.gradle]`` — declared coordinates + resolved graph."""
+
+    dependencies: tuple[str, ...] = ()
+    repositories: tuple[str, ...] = ()
+    resolved: tuple[GradleResolvedModule, ...] = ()
+
+    @property
+    def declared(self) -> bool:
+        return bool(self.dependencies)
+
+
+@dataclass(frozen=True)
+class LockedIncludeFile:
+    """One ``[[tool.kivyforge.include_files]]`` drift pin."""
+
+    source: str
+    dest: str
+    sha256: str
+
+
+@dataclass(frozen=True)
+class AndroidLockfile:
+    requires_python: str
+    packages: tuple[LockedPackage, ...]
+    python_android: tuple[PythonAndroidRuntime, ...]
+    kivyforge_version: str
+    generated_at: str
+    pyproject_sha256: str
+    tool_kivy_android_schema_version: int
+    kivy_generation: int
+    android_libs: tuple[LockedAndroidLib, ...] = ()
+    gradle: GradlePins = GradlePins()
+    include_files: tuple[LockedIncludeFile, ...] = ()
+    schema_version: int = TOOL_SCHEMA_VERSION
+    lock_version: str = LOCK_VERSION
+    created_by: str = CREATED_BY
+    extras: tuple[str, ...] = ()
+    dependency_groups: tuple[str, ...] = ()
+    default_groups: tuple[str, ...] = ()

kivyforge/platforms/android/lock/python_meta.py

@@ -0,0 +1,199 @@
+"""Resolve python.org Android runtime metadata for the lock (android/02).
+
+``kivyforge lock`` pins, per targeted ABI, the Android embeddable package's
+URL + SHA-256 and its minimum-API floor into ``[[tool.kivyforge.python_android]]``.
+Modeled on the iOS ``PythonOrgProvider`` — same cache/offline/retry posture —
+but per-ABI (the runtime ships one artifact per ABI, not a fat xcframework).
+
+Artifact naming is **discovered from the release's file listing**, not
+hardcoded: the observed 3.14.6 names are
+``python-3.14.6-{aarch64,x86_64}-linux-android.tar.gz`` (see
+docs/design/dev/android-loadmodel-findings.md §runtime-package facts, which
+corrected the illustrative URL in android/02). The known pattern serves as a
+fallback when the listing is unreachable but the artifact itself is.
+
+The min-API floor is read from ``android-env.sh`` inside the tarball
+(``ANDROID_API_LEVEL:=24``) — the same source python.org's own testbed Gradle
+project reads it from, so there is no per-version table to maintain.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import tarfile
+import tempfile
+import time
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.artifacts.verify import sha256_file
+
+RELEASE_LISTING_URL = "https://www.python.org/ftp/python/{version}/"
+
+# ABI (wheel-tag spelling) -> the arch component in python.org's filenames.
+ABI_TO_PYTHON_ORG_ARCH = {"arm64_v8a": "aarch64", "x86_64": "x86_64"}
+
+_FALLBACK_NAME = "python-{version}-{arch}-linux-android.tar.gz"
+_ANDROID_TARBALL_RE = re.compile(
+    r'href="(python-(?P<version>[^"]+?)-(?P<arch>aarch64|x86_64)'
+    r'-linux-android\.tar\.gz)"'
+)
+_API_LEVEL_RE = re.compile(r"ANDROID_API_LEVEL:?=\s*(\d+)")
+
+_DOWNLOAD_ATTEMPTS = 4
+_RETRY_BACKOFF_SEC = (1.0, 2.0, 4.0)
+# Returned when android-env.sh is absent or unparseable; matches the runtime's
+# documented floor (android/01 min_sdk).
+_MIN_API_FALLBACK = 24
+
+
+class PythonAndroidError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class PythonAndroidInfo:
+    """One per-ABI runtime pin for ``[[tool.kivyforge.python_android]]``."""
+
+    version: str
+    abi: str
+    url: str
+    sha256: str
+    min_api: int
+
+
+class PythonAndroidProvider(Protocol):
+    def get(
+        self, version: str, abi: str, *, offline: bool = False
+    ) -> PythonAndroidInfo: ...
+
+
+def read_min_api(archive_path: str | Path) -> int:
+    """Read ``ANDROID_API_LEVEL`` from ``android-env.sh`` inside the tarball."""
+    try:
+        with open(archive_path, "rb") as f:
+            return _read_min_api_from_fileobj(f)
+    except OSError:
+        return _MIN_API_FALLBACK
+
+
+def _read_min_api_from_fileobj(fileobj) -> int:
+    """Same as :func:`read_min_api`, but reads an already-open, seekable file.
+
+    ``_download`` reads it via its own live ``NamedTemporaryFile`` handle
+    rather than reopening the path — reopening a still-open ``NamedTemporaryFile``
+    by name is a documented POSIX-only guarantee (it silently fails on Windows).
+    """
+    try:
+        with tarfile.open(fileobj=fileobj, mode="r:gz") as tf:
+            for member in tf.getmembers():
+                if not member.name.endswith("android-env.sh"):
+                    continue
+                f = tf.extractfile(member)
+                if f is None:
+                    continue
+                match = _API_LEVEL_RE.search(f.read().decode("utf-8", "replace"))
+                if match:
+                    return int(match.group(1))
+    except Exception:  # noqa: BLE001 — malformed archive, test fixture, etc.
+        pass
+    return _MIN_API_FALLBACK
+
+
+class PythonOrgAndroidProvider:
+    """Default provider: discover the artifact from the release file listing."""
+
+    def __init__(self, *, cache: ArtifactCache | None = None) -> None:
+        self._cache = cache or ArtifactCache()
+        # version -> {arch -> filename}, from one listing fetch per version.
+        self._listing: dict[str, dict[str, str]] = {}
+
+    def get(
+        self, version: str, abi: str, *, offline: bool = False
+    ) -> PythonAndroidInfo:
+        arch = ABI_TO_PYTHON_ORG_ARCH.get(abi)
+        if arch is None:
+            raise PythonAndroidError(
+                f"unknown Android ABI {abi!r}; expected one of "
+                f"{sorted(ABI_TO_PYTHON_ORG_ARCH)}"
+            )
+        filename = self._filename(version, arch, offline=offline)
+        url = RELEASE_LISTING_URL.format(version=version) + filename
+
+        cached = self._cache.find_by_filename(filename)
+        if cached is not None:
+            return PythonAndroidInfo(
+                version=version,
+                abi=abi,
+                url=url,
+                sha256=sha256_file(cached),
+                min_api=read_min_api(cached),
+            )
+        if offline:
+            raise PythonAndroidError(
+                f"python.org Android runtime {version} ({abi}) is not in the "
+                f"artifact cache ({filename}).\n"
+                f"  Run `kivyforge lock` online once, then retry with --offline."
+            )
+        sha256, min_api = self._download(url, version, abi)
+        return PythonAndroidInfo(
+            version=version, abi=abi, url=url, sha256=sha256, min_api=min_api
+        )
+
+    # ----------------------------------------------------------------- #
+    def _filename(self, version: str, arch: str, *, offline: bool) -> str:
+        fallback = _FALLBACK_NAME.format(version=version, arch=arch)
+        if offline:
+            return fallback
+        listing = self._listing.get(version)
+        if listing is None:
+            listing = self._fetch_listing(version)
+            self._listing[version] = listing
+        return listing.get(arch, fallback)
+
+    def _fetch_listing(self, version: str) -> dict[str, str]:
+        url = RELEASE_LISTING_URL.format(version=version)
+        try:
+            with urllib.request.urlopen(url) as resp:  # noqa: S310
+                html = resp.read().decode("utf-8", "replace")
+        except OSError:
+            # The artifact fetch itself will surface a clear error if the
+            # fallback name is also wrong.
+            return {}
+        found: dict[str, str] = {}
+        for match in _ANDROID_TARBALL_RE.finditer(html):
+            found[match.group("arch")] = match.group(1)
+        return found
+
+    def _download(self, url: str, version: str, abi: str) -> tuple[str, int]:
+        last_exc: OSError | None = None
+        for attempt in range(_DOWNLOAD_ATTEMPTS):
+            try:
+                digest = hashlib.sha256()
+                with tempfile.NamedTemporaryFile(suffix=".tar.gz") as tmp:
+                    with urllib.request.urlopen(url) as resp:  # noqa: S310
+                        for chunk in iter(lambda: resp.read(1 << 20), b""):
+                            digest.update(chunk)
+                            tmp.write(chunk)
+                    tmp.flush()
+                    tmp.seek(0)
+                    min_api = _read_min_api_from_fileobj(tmp)
+                return digest.hexdigest(), min_api
+            except OSError as exc:
+                last_exc = exc
+                if attempt < _DOWNLOAD_ATTEMPTS - 1:
+                    time.sleep(
+                        _RETRY_BACKOFF_SEC[min(attempt, len(_RETRY_BACKOFF_SEC) - 1)]
+                    )
+        assert last_exc is not None
+        raise PythonAndroidError(
+            f"could not fetch the python.org Android runtime {version} ({abi}) "
+            f"from {url}: {last_exc}\n"
+            f"  Check the version exists at python.org/downloads/android/ and "
+            f"that you are online. Transient errors are retried "
+            f"{_DOWNLOAD_ATTEMPTS} times."
+        ) from last_exc