kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/lock/find_links.py

@@ -0,0 +1,182 @@
+"""Validate ``[tool.kivy.<platform>].find_links`` before lock resolution.
+
+``find_links`` is a shared surface across iOS/macOS/Linux, so every diagnostic
+here is parameterized by ``platform`` (the ``[tool.kivy.<platform>]`` key path
+and platform-appropriate wording). ``platform`` defaults to ``"ios"`` for
+backward compatibility with the original iOS-only call sites.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+class FindLinksError(Exception):
+    """A find_links directory is missing or has no usable wheels."""
+
+
+def resolve_find_links(project_root: Path, entries: tuple[str, ...]) -> list[str]:
+    """Resolve repo-relative ``find_links`` entries to absolute paths."""
+    root = project_root.resolve()
+    return [str((root / entry).resolve()) for entry in entries]
+
+
+def validate_find_links(
+    project_root: Path, entries: tuple[str, ...], *, platform: str = "ios"
+) -> None:
+    """Raise ``FindLinksError`` when a find_links directory is missing or unusable."""
+    if not entries:
+        return
+
+    key = f"[tool.kivy.{platform}].find_links"
+    root = project_root.resolve()
+    lines: list[str] = []
+    for entry in entries:
+        path = (root / entry).resolve()
+        rel = _display_path(root, path, entry)
+        if not path.exists():
+            lines.append(f"{key} entry {entry!r} does not exist ({rel}).")
+            continue
+        if not path.is_dir():
+            lines.append(f"{key} entry {entry!r} is not a directory ({rel}).")
+            continue
+        if not any(path.glob("*.whl")):
+            lines.append(f"{key} entry {entry!r} contains no .whl files ({rel}).")
+
+    if not lines:
+        return
+
+    hint = _find_links_hint(root, entries, platform)
+    message = "\n".join(lines)
+    if hint:
+        message = f"{message}\n{hint}"
+    raise FindLinksError(message)
+
+
+def wheel_path_from_project_root(project_root: Path, resolved: Path) -> str:
+    """Return a project-root-relative wheel path (may contain ``..``)."""
+    root = project_root.resolve()
+    resolved = resolved.resolve()
+    _ensure_find_link_scope(root, resolved)
+    return Path(os.path.relpath(resolved, root)).as_posix()
+
+
+def find_links_resolution_hint(
+    project_root: Path,
+    entries: tuple[str, ...],
+    *,
+    pip_stderr: str = "",
+    platform: str = "ios",
+) -> str | None:
+    """Return extra guidance when pip resolution likely failed for find_links reasons."""
+    if not entries:
+        return None
+
+    root = project_root.resolve()
+    pip_text = pip_stderr.lower()
+    if (
+        "no matching distribution" not in pip_text
+        and "could not find a version" not in pip_text
+    ):
+        return None
+
+    lines: list[str] = []
+    for entry in entries:
+        path = (root / entry).resolve()
+        rel = _display_path(root, path, entry)
+        if not path.exists():
+            lines.append(f"  • {entry!r} → missing ({rel})")
+        elif not path.is_dir():
+            lines.append(f"  • {entry!r} → not a directory ({rel})")
+        elif not any(path.glob("*.whl")):
+            lines.append(
+                f"  • {entry!r} → directory exists but has no .whl files ({rel})"
+            )
+        else:
+            count = len(list(path.glob("*.whl")))
+            lines.append(
+                f"  • {entry!r} → {count} wheel(s) present ({rel}); "
+                "none matched this target's platform tags or a dependency."
+            )
+
+    if not lines:
+        return None
+
+    return (
+        "find_links check:\n"
+        + "\n".join(lines)
+        + "\n"
+        + _find_links_hint(root, entries, platform)
+    )
+
+
+def find_links_doctor_detail(
+    project_root: Path, entry: str, path: Path, *, platform: str = "ios"
+) -> tuple[str, str | None]:
+    """Return (detail, hint) for a single find_links entry."""
+    rel = _display_path(project_root.resolve(), path, entry)
+    if not path.exists():
+        return f"{entry!r} missing ({rel})", _find_links_hint(
+            project_root, (entry,), platform
+        )
+    if not path.is_dir():
+        return f"{entry!r} is not a directory ({rel})", None
+    wheels = list(path.glob("*.whl"))
+    if not wheels:
+        return f"{entry!r} has no .whl files ({rel})", _find_links_hint(
+            project_root, (entry,), platform
+        )
+    return f"{entry!r} ({len(wheels)} wheel(s) in {rel})", None
+
+
+def _find_links_hint(
+    project_root: Path, entries: tuple[str, ...], platform: str = "ios"
+) -> str:
+    del entries  # reserved for future per-entry hints
+    shared_note = ""
+    if "examples" in project_root.parts and project_root.name != "wheels":
+        if platform == "ios":
+            # iOS ships a helper script to build its examples wheelhouse.
+            shared_note = (
+                "  Shared example wheels live under examples/wheels/ios/ — run "
+                "`scripts/build_ios_wheels.sh` from the repo root.\n"
+            )
+        else:
+            shared_note = (
+                f"  Shared example wheels live under examples/wheels/{platform}/.\n"
+            )
+    return (
+        f"{shared_note}"
+        f"  Add locally built {platform} wheels to the directory, then re-run "
+        "`kivyforge lock`."
+    )
+
+
+def _display_path(project_root: Path, path: Path, entry: str) -> str:
+    try:
+        return path.relative_to(project_root).as_posix()
+    except ValueError:
+        return entry
+
+
+def _repo_root(start: Path) -> Path | None:
+    """Nearest ancestor (inclusive) containing a ``.git`` marker, else None."""
+    for candidate in (start, *start.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return None
+
+
+def _ensure_find_link_scope(project_root: Path, resolved: Path) -> None:
+    allowed = [project_root, project_root.parent]
+    repo = _repo_root(project_root)
+    if repo is not None:
+        allowed.append(repo)
+    for base in allowed:
+        if resolved == base or base in resolved.parents:
+            return
+    raise FindLinksError(
+        f"find_links path {resolved} is outside the project directory, its "
+        "parent, and the enclosing repository"
+    )

kivyforge/lock/model.py

@@ -0,0 +1,69 @@
+"""Shared, platform-neutral ``[[packages]]`` model (PEP 751).
+
+The per-slice wheel + package dataclasses here are consumed by every backend
+(iOS, macOS, Linux) and the generic wheel+runtime engine. Platform-specific
+lockfile models (the iOS ``Lockfile`` + xcframework/swift-package entries, the
+macOS/Linux ``WheelRuntimeLock``) build on top of these.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+LOCK_VERSION = "1.0"
+
+
+@dataclass(frozen=True)
+class LockedWheel:
+    """One ``[[packages.wheels]]`` entry (a single platform slice)."""
+
+    name: str  # wheel filename; platform tag is parsed back out of this
+    sha256: str
+    url: str | None = None
+    path: str | None = None
+    upload_time: str | None = None
+    size: int | None = None
+
+    def __post_init__(self) -> None:
+        if bool(self.url) == bool(self.path):
+            raise ValueError(f"wheel {self.name!r} must have exactly one of url/path")
+
+    @property
+    def platform_tag(self) -> str:
+        """The platform tag parsed from the wheel filename (last tag segment)."""
+        stem = self.name[:-4] if self.name.endswith(".whl") else self.name
+        return stem.rsplit("-", 1)[-1]
+
+    @property
+    def is_pure_python(self) -> bool:
+        return "none-any" in self.name
+
+
+@dataclass(frozen=True)
+class PackageDep:
+    name: str
+    marker: str | None = None
+
+
+@dataclass(frozen=True)
+class LockedPackage:
+    """One ``[[packages]]`` entry."""
+
+    name: str
+    version: str
+    wheels: tuple[LockedWheel, ...]
+    requires_python: str | None = None
+    dependencies: tuple[PackageDep, ...] = ()
+    marker: str | None = None
+    direct_requirement: bool = False
+    source_index: str | None = None
+
+    @property
+    def sort_key(self) -> tuple[str, str]:
+        return (canonical_name(self.name), self.version)
+
+
+def canonical_name(name: str) -> str:
+    """PEP 503 normalization for package-name comparison."""
+    return re.sub(r"[-_.]+", "-", name).lower()

kivyforge/lock/pep751.py

@@ -0,0 +1,111 @@
+"""Shared, platform-neutral PEP 751 serialization helpers.
+
+Both the iOS and macOS lock writers/readers emit and parse the ``[[packages]]``
+wheels section identically; only the per-platform ``[tool.kivyforge]`` extension
+(the iOS ``python_xcframework``/xcframeworks/swift_packages vs. the macOS python
+runtime) differs. Keeping the ``[[packages]]`` machinery here means a single
+source of truth for the PEP 751 layout and string escaping.
+"""
+
+from __future__ import annotations
+
+from .model import LockedPackage, LockedWheel, PackageDep
+
+
+def s(value: str) -> str:
+    """Emit a TOML basic string with minimal escaping."""
+    escaped = (
+        value.replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\n", "\\n")
+        .replace("\t", "\\t")
+    )
+    return f'"{escaped}"'
+
+
+def arr(values) -> str:
+    if not values:
+        return "[]"
+    return "[" + ", ".join(s(v) for v in values) + "]"
+
+
+def b(value: bool) -> str:
+    return "true" if value else "false"
+
+
+def emit_package(lines: list[str], pkg: LockedPackage) -> None:
+    lines.append("[[packages]]")
+    lines.append(f"name = {s(pkg.name)}")
+    lines.append(f"version = {s(pkg.version)}")
+    if pkg.requires_python:
+        lines.append(f"requires-python = {s(pkg.requires_python)}")
+    if pkg.marker:
+        lines.append(f"marker = {s(pkg.marker)}")
+    if pkg.dependencies:
+        deps = ", ".join(_dep_inline(d) for d in pkg.dependencies)
+        lines.append(f"dependencies = [{deps}]")
+
+    if pkg.direct_requirement or pkg.source_index:
+        lines.append("")
+        lines.append("[packages.tool.kivyforge]")
+        if pkg.direct_requirement:
+            lines.append("direct_requirement = true")
+        if pkg.source_index:
+            lines.append(f"source_index = {s(pkg.source_index)}")
+
+    for wheel in sorted(pkg.wheels, key=lambda w: w.name):
+        lines.append("")
+        emit_wheel(lines, wheel)
+    lines.append("")
+
+
+def emit_wheel(lines: list[str], wheel: LockedWheel) -> None:
+    lines.append("[[packages.wheels]]")
+    lines.append(f"name = {s(wheel.name)}")
+    if wheel.upload_time:
+        lines.append(f"upload-time = {s(wheel.upload_time)}")
+    if wheel.url:
+        lines.append(f"url = {s(wheel.url)}")
+    else:
+        path = wheel.path
+        assert path is not None
+        lines.append(f"path = {s(path)}")
+    lines.append(f"hashes = {{ sha256 = {s(wheel.sha256)} }}")
+    if wheel.size is not None:
+        lines.append(f"size = {wheel.size}")
+
+
+def parse_package(p: dict) -> LockedPackage:
+    tool = p.get("tool", {}).get("kivyforge", {})
+    deps = tuple(
+        PackageDep(name=d["name"], marker=d.get("marker"))
+        for d in p.get("dependencies", [])
+    )
+    wheels = tuple(parse_wheel(w) for w in p.get("wheels", []))
+    return LockedPackage(
+        name=p["name"],
+        version=p["version"],
+        wheels=wheels,
+        requires_python=p.get("requires-python"),
+        dependencies=deps,
+        marker=p.get("marker"),
+        direct_requirement=bool(tool.get("direct_requirement", False)),
+        source_index=tool.get("source_index"),
+    )
+
+
+def parse_wheel(w: dict) -> LockedWheel:
+    return LockedWheel(
+        name=w["name"],
+        sha256=w.get("hashes", {}).get("sha256", ""),
+        url=w.get("url"),
+        path=w.get("path"),
+        upload_time=w.get("upload-time"),
+        size=w.get("size"),
+    )
+
+
+def _dep_inline(dep: PackageDep) -> str:
+    if dep.marker:
+        return f"{{ name = {s(dep.name)}, marker = {s(dep.marker)} }}"
+    return f"{{ name = {s(dep.name)} }}"

kivyforge/lock/reader.py

@@ -0,0 +1,30 @@
+"""Shared lockfile drift detection + the ``LockError`` type.
+
+Every backend records the pyproject SHA-256 in its lockfile and compares it on
+build to detect drift; those neutral helpers live here so iOS, macOS, and Linux
+readers all reuse them. The iOS ``pylock.ios.toml`` parser lives in
+``kivyforge.platforms.ios.lock.reader``; the wheel+runtime parser lives in
+``kivyforge.lock.wheelruntime.serialize``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Protocol
+
+
+class LockError(Exception):
+    """A malformed or unreadable lockfile."""
+
+
+class _HasPyprojectSha(Protocol):
+    pyproject_sha256: str
+
+
+def compute_pyproject_sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def is_in_sync(lock: _HasPyprojectSha, pyproject_text: str) -> bool:
+    """True if the lock's recorded pyproject hash matches the current pyproject."""
+    return lock.pyproject_sha256 == compute_pyproject_sha256(pyproject_text)

kivyforge/lock/resolver.py

@@ -0,0 +1,124 @@
+"""Platform-neutral pip helpers shared by every wheel resolver (spec 02).
+
+The iOS resolver (``kivyforge.platforms.ios.lock.resolver``) and the generic
+wheel+runtime resolver (``kivyforge.lock.wheelruntime.resolver``) both drive pip
+in dry-run ``--report`` mode per platform tag; the pip-version gate, version
+formatting, ABI tag list, ``--python-version`` normalization, and requires-dist
+name parsing are identical and live here.
+"""
+
+from __future__ import annotations
+
+import subprocess
+
+from packaging.requirements import InvalidRequirement, Requirement
+
+# Minimum host pip that understands PEP 730 iOS platform tags (pip 24.3, 2024-10-27).
+# Earlier pip cannot match an ``ios_<dt>_*`` --platform request against a wheel
+# tagged at a lower floor (e.g. ios_13_0_*), so compatible wheels are reported as
+# missing. kivyforge targets Python that ships iOS support, so requiring a current
+# pip is simpler — and far less surprising — than reimplementing tag expansion.
+MIN_PIP_VERSION = (24, 3)
+
+
+def version_str(version: tuple[int, ...]) -> str:
+    return ".".join(str(part) for part in version)
+
+
+def pip_version(python_executable: str) -> tuple[int, ...] | None:
+    """Best-effort ``(major, minor, ...)`` version of pip for ``python_executable``.
+
+    Returns ``None`` when pip can't be queried — treated as "unknown" (don't
+    block) rather than "too old", since a genuinely broken pip surfaces its own
+    error when resolution runs.
+    """
+    try:
+        proc = subprocess.run(
+            [python_executable, "-m", "pip", "--version"],
+            capture_output=True,
+            text=True,
+        )
+    except (OSError, ValueError):
+        return None
+    if proc.returncode != 0:
+        return None
+    # Format: "pip 24.3.1 from /path/site-packages/pip (python 3.15)".
+    tokens = proc.stdout.split()
+    if len(tokens) < 2 or tokens[0] != "pip":
+        return None
+    return _parse_version(tokens[1])
+
+
+def _parse_version(text: str) -> tuple[int, ...] | None:
+    parts: list[int] = []
+    for chunk in text.split("."):
+        digits = "".join(c for c in chunk if c.isdigit())
+        if not digits:
+            break
+        parts.append(int(digits))
+    return tuple(parts) or None
+
+
+def pip_python_version(python_version: str) -> str:
+    """``pip install --python-version`` accepts only integer dotted parts."""
+    parts: list[str] = []
+    for chunk in python_version.split("."):
+        digits = "".join(c for c in chunk if c.isdigit())
+        if not digits:
+            break
+        parts.append(digits)
+    if len(parts) >= 2:
+        return f"{parts[0]}.{parts[1]}"
+    return python_version
+
+
+def abi_tags(python_version: str) -> tuple[str, ...]:
+    """ABI tags to offer pip; cp<XY> first, then the limited-API/none fallbacks.
+
+    Per the Phase 0 findings we must not over-constrain abi (abi3 wheels would
+    be missed otherwise).
+    """
+    major_minor = "".join(python_version.split(".")[:2])
+    return (f"cp{major_minor}", "abi3", "none")
+
+
+def dep_names_for_environment(
+    requires_dist: list[str], environment: dict[str, str]
+) -> list[str]:
+    """The dependency edges that actually apply on the target platform.
+
+    ``Requires-Dist`` lists every edge a distribution *might* have, gated by
+    markers: Kivy's raw list names ``pytest``, ``sphinx`` and
+    ``kivy-deps.angle`` alongside its real runtime dependencies. Recording it
+    unfiltered would describe a dependency graph the lock does not install, so
+    each marker is evaluated against the target environment. ``extra`` is empty
+    there, which drops extra-gated edges too.
+    """
+    names: list[str] = []
+    for raw in requires_dist or []:
+        try:
+            requirement = Requirement(raw)
+        except InvalidRequirement:
+            # Unparseable metadata is upstream's problem, not a reason to fail
+            # the lock; fall back to the permissive name-only reading.
+            names.extend(_dep_names([raw]))
+            continue
+        if requirement.marker is not None and not requirement.marker.evaluate(
+            environment
+        ):
+            continue
+        names.append(requirement.name)
+    return names
+
+
+def _dep_names(requires_dist: list[str]) -> list[str]:
+    names: list[str] = []
+    for raw in requires_dist or []:
+        # Strip everything after the name: extras, specifiers, markers.
+        name = raw.split(";", 1)[0].split("[", 1)[0]
+        for sep in ("==", ">=", "<=", "~=", "!=", ">", "<", "(", " "):
+            name = name.split(sep, 1)[0]
+        name = name.strip()
+        if name:
+            names.append(name)
+    return names

kivyforge/lock/wheelruntime/__init__.py

@@ -0,0 +1,70 @@
+"""Generic ``wheel + bundled-runtime`` lock engine.
+
+The reusable core for every platform whose lock is "platform-tagged wheels plus
+a bundled CPython runtime": macOS now; Linux, Windows, Android later. Each such
+platform is a thin :class:`PlatformLockProfile` over this engine — no new
+builder, resolver, model, or serializer. iOS is intentionally *not* in this
+family (its per-slice framework/xcframework/SPM lock is a different shape).
+"""
+
+from __future__ import annotations
+
+from .builder import (
+    WheelRuntimeBuildError,
+    build_wheel_runtime_lock,
+    diff_summary,
+    semantic_equal,
+)
+from .model import (
+    LockedNativeBinary,
+    PythonRuntime,
+    RuntimeArtifact,
+    WheelRuntimeLock,
+)
+from .native_binaries import resolve_native_binaries
+from .profile import PlatformLockProfile
+from .resolver import (
+    PipWheelResolver,
+    ResolvedPackage,
+    ResolvedWheel,
+    Variant,
+    WheelResolver,
+    WheelResolverError,
+    get_wheel_resolver,
+)
+from .runtime import (
+    PbsProvider,
+    ReleaseAsset,
+    RuntimeProvider,
+    RuntimeProviderError,
+    pbs_asset_glob,
+)
+from .serialize import dumps, load, loads
+
+__all__ = [
+    "LockedNativeBinary",
+    "PbsProvider",
+    "PipWheelResolver",
+    "PlatformLockProfile",
+    "PythonRuntime",
+    "ReleaseAsset",
+    "ResolvedPackage",
+    "ResolvedWheel",
+    "RuntimeArtifact",
+    "RuntimeProvider",
+    "RuntimeProviderError",
+    "Variant",
+    "WheelResolver",
+    "WheelResolverError",
+    "WheelRuntimeBuildError",
+    "WheelRuntimeLock",
+    "build_wheel_runtime_lock",
+    "diff_summary",
+    "dumps",
+    "get_wheel_resolver",
+    "load",
+    "loads",
+    "pbs_asset_glob",
+    "resolve_native_binaries",
+    "semantic_equal",
+]