kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/artifacts/wheels.py

@@ -0,0 +1,89 @@
+"""Select pinned iOS wheels for a build slice (spec 03 / spec 05 step 4).
+
+Slice selection is driven by the build target + ``--arch``.  The pip
+cross-install command lives in ``collect.py`` next to where it is invoked.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..lock.model import LockedPackage, LockedWheel
+
+# Build target -> the simulator/device platform-tag suffix.
+TARGET_SUFFIX = {
+    ("device", "arm64"): "arm64_iphoneos",
+    ("simulator", "arm64"): "arm64_iphonesimulator",
+    ("simulator", "x86_64"): "x86_64_iphonesimulator",
+}
+
+
+@dataclass(frozen=True)
+class BuildSlice:
+    target: str  # "device" | "simulator"
+    arch: str  # "arm64" | "x86_64"
+    deployment_target: str
+
+    @property
+    def platform_tag(self) -> str:
+        suffix = TARGET_SUFFIX.get((self.target, self.arch))
+        if suffix is None:
+            raise ValueError(f"unsupported target/arch: {self.target}/{self.arch}")
+        dt = self.deployment_target.replace(".", "_")
+        return f"ios_{dt}_{suffix}"
+
+
+def select_wheel(package: LockedPackage, slice_: BuildSlice) -> LockedWheel:
+    """Pick the wheel matching the build slice (pure-Python wheels match any).
+
+    For native wheels, the arch/sdk suffix must match exactly, but the iOS
+    version component uses compatibility matching: a wheel tagged ios_13_0_*
+    is valid for a project targeting ios_16_0 because the wheel can run on
+    any iOS >= 13.0.  The best (highest compatible) version is preferred.
+
+    Background: wheel tags are determined by the Python binary's compile-time
+    sysconfig.get_platform(), which reflects the Python.xcframework minimum OS
+    (e.g. python.org cp315 targets 13.0 regardless of IPHONEOS_DEPLOYMENT_TARGET
+    used when compiling the extension code itself).
+    """
+    pure = [w for w in package.wheels if w.is_pure_python]
+    if pure:
+        return pure[0]
+
+    arch_sdk = TARGET_SUFFIX.get((slice_.target, slice_.arch))
+    if arch_sdk is None:
+        raise ValueError(f"unsupported target/arch: {slice_.target}/{slice_.arch}")
+
+    dt_parts = tuple(int(x) for x in slice_.deployment_target.split("."))
+
+    candidates: list[tuple[tuple[int, ...], LockedWheel]] = []
+    for wheel in package.wheels:
+        tag = wheel.platform_tag  # e.g. "ios_13_0_arm64_iphonesimulator"
+        if not tag.endswith(f"_{arch_sdk}"):
+            continue
+        # Extract the ios_<major>_<minor> prefix.
+        prefix = tag[: -(len(arch_sdk) + 1)]  # "ios_13_0"
+        parts = prefix.split("_")  # ["ios", "13", "0"]
+        if parts[0] != "ios" or len(parts) < 3:
+            continue
+        try:
+            wheel_ver = tuple(int(x) for x in parts[1:])
+        except ValueError:
+            continue
+        if wheel_ver <= dt_parts:
+            candidates.append((wheel_ver, wheel))
+
+    if candidates:
+        # Prefer the highest compatible version.
+        candidates.sort(key=lambda t: t[0], reverse=True)
+        return candidates[0][1]
+
+    available = ", ".join(sorted(w.platform_tag for w in package.wheels))
+    raise WheelSelectionError(
+        f"{package.name} has no compatible wheel for slice "
+        f"{slice_.platform_tag} (have: {available})."
+    )
+
+
+class WheelSelectionError(Exception):
+    pass

kivyforge/bundle/__init__.py

@@ -0,0 +1 @@
+"""Bundling helpers shared by more than one platform backend."""

kivyforge/bundle/pycompile.py

@@ -0,0 +1,161 @@
+"""Byte-compile a staged Python payload, optionally stripping the sources.
+
+Shared by every backend that ships a Python tree: Android's asset bundle and
+the three desktop bundles. The mechanics below are identical everywhere; what
+differs per platform is only *which* trees get compiled and *which* interpreter
+does the compiling, both of which the caller supplies.
+
+Two layouts, and the difference matters:
+
+- Keeping the source, the ``.pyc`` goes in ``__pycache__/`` as usual, so imports
+  find it next to the ``.py`` it was built from.
+- Shipping ``.pyc`` only requires the *legacy* layout — PEP 3147 sourceless
+  imports look for ``foo.pyc`` at the source's own path, never inside
+  ``__pycache__/``. Compiling to ``__pycache__/`` and then deleting the ``.py``
+  would produce a tree that imports nothing at all.
+
+Hash-based, unchecked invalidation (PEP 552) is used rather than the default
+mtime+size: it saves a stat per import for a payload that cannot have a newer
+source than the one shipped, and it keeps an mtime out of every ``.pyc``.
+
+Paths are stripped to be payload-relative because a ``.pyc`` records the path it
+was compiled from: the default would leak local host paths into the shipped
+artifact and make otherwise-identical builds differ per machine.
+
+``compiler`` is an interpreter argv prefix whose CPython *minor* matches the
+target runtime — empty means "this interpreter". Establishing that match is the
+caller's job, because a ``.pyc`` is only loadable by the exact CPython minor
+that wrote it.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+
+class PycompileError(Exception):
+    """Byte-compilation failed, or the compiler could not be run."""
+
+
+def select_compiler(
+    *, staged_interpreter: Path, native: bool, python_version: str
+) -> tuple[str, ...] | None:
+    """Pick the interpreter argv to byte-compile the staged payload with.
+
+    The staged interpreter is the one actually shipped, so it is the first
+    choice — but only when *native*, i.e. the caller has confirmed it can run
+    on this host without emulation, which kivyforge never depends on. When it
+    can't run here, fall back to this process's own interpreter: a ``.pyc``'s
+    magic number is keyed to CPython's *minor* version only, never
+    architecture, so any interpreter of the right minor will do regardless of
+    which arch it runs on. Returns ``None`` when neither works, telling the
+    caller to degrade (skip compiling, ship source) rather than write a
+    ``.pyc`` nothing can load.
+    """
+    if native and staged_interpreter.is_file():
+        return (str(staged_interpreter),)
+    if sys.version_info[:2] == _target_minor(python_version):
+        return ()
+    return None
+
+
+def _target_minor(python_version: str) -> tuple[int, int]:
+    parts = python_version.split(".")[:2]
+    return (int(parts[0].split("rc")[0]), int(parts[1].split("rc")[0]))
+
+
+def byte_compile(
+    trees: Sequence[Path],
+    *,
+    compiler: Sequence[str] = (),
+    strip_source: bool = False,
+    stripdir: Path,
+) -> None:
+    """Compile every tree in *trees* in place; strip ``.py`` when asked.
+
+    Missing trees are skipped (a backend may stage some payload areas only
+    conditionally). Raises :class:`PycompileError` naming the tree that failed.
+    """
+    for tree in trees:
+        if not tree.is_dir():
+            continue
+        if not compile_tree(
+            tree, compiler=compiler, legacy=strip_source, stripdir=stripdir
+        ):
+            raise PycompileError(
+                f"byte-compiling {tree.name}/ failed; the output above names the "
+                "file.\n"
+                "  A syntax error in app code fails here rather than at runtime."
+            )
+        if strip_source:
+            strip_sources(tree)
+
+
+def strip_sources(tree: Path) -> None:
+    """Delete every ``.py`` that has a sibling ``.pyc``, and all ``__pycache__``.
+
+    Only sources with a compiled counterpart are removed, so a file the
+    compiler skipped is never silently dropped from the payload. The
+    ``__pycache__`` sweep matters because nothing can import from it once the
+    sources are gone — leaving it behind would ship dead weight.
+    """
+    for source in tree.rglob("*.py"):
+        if source.with_suffix(".pyc").is_file():
+            source.unlink()
+    for cache in tree.rglob("__pycache__"):
+        shutil.rmtree(cache, ignore_errors=True)
+
+
+def compile_tree(
+    target: Path,
+    *,
+    compiler: Sequence[str] = (),
+    legacy: bool = False,
+    stripdir: Path,
+) -> bool:
+    """Byte-compile *target*; return whether it succeeded.
+
+    Uses ``compileall`` in-process when *compiler* is empty, otherwise shells
+    out to the named interpreter so the ``.pyc`` carries the target runtime's
+    magic number.
+    """
+    if not compiler:
+        import compileall
+        import py_compile
+
+        return bool(
+            compileall.compile_dir(
+                target,
+                quiet=1,
+                legacy=legacy,
+                optimize=0,
+                invalidation_mode=py_compile.PycInvalidationMode.UNCHECKED_HASH,
+                force=True,
+                stripdir=str(stripdir),
+            )
+        )
+
+    argv = [
+        *compiler,
+        "-m",
+        "compileall",
+        "-q",
+        "-f",
+        "--invalidation-mode",
+        "unchecked-hash",
+        "-s",
+        str(stripdir),
+    ]
+    if legacy:
+        argv.append("-b")
+    argv.append(str(target))
+    try:
+        return subprocess.run(argv, check=False).returncode == 0
+    except OSError as exc:
+        raise PycompileError(
+            f"could not run {' '.join(compiler)} to byte-compile {target.name}: {exc}"
+        ) from exc

kivyforge/cli/__init__.py

@@ -0,0 +1,52 @@
+"""``kivyforge`` — the kivyforge 3.0 command-line interface.
+
+A slim click-based dispatcher. Each verb lives in its own module under
+``kivyforge.cli`` and is registered onto the top-level group here.
+"""
+
+from __future__ import annotations
+
+import click
+
+from .. import __version__
+from . import (
+    build,
+    clean,
+    doctor,
+    init,
+    lock,
+    open_cmd,
+    package,
+    run,
+    status,
+    upgrade,
+)
+
+
+@click.group(
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "kivyforge 3.0 — a declarative iOS bundler for Kivy apps.\n\n"
+        "Run commands from the directory that contains your pyproject.toml."
+    ),
+)
+@click.version_option(__version__, "-V", "--version", prog_name="kivyforge")
+def main() -> None:
+    pass
+
+
+# Real 3.0 verbs.
+main.add_command(init.init)
+main.add_command(lock.lock)
+main.add_command(build.build)
+main.add_command(run.run)
+main.add_command(open_cmd.open_)
+main.add_command(package.package)
+main.add_command(upgrade.upgrade)
+main.add_command(clean.clean)
+main.add_command(status.status)
+main.add_command(doctor.doctor)
+
+
+if __name__ == "__main__":
+    main()

kivyforge/cli/_common.py

@@ -0,0 +1,62 @@
+"""Shared helpers for the ``kivyforge`` CLI.
+
+All verbs look for ``pyproject.toml`` in the **current working directory
+only** — no parent-directory traversal (per spec 05).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+PYPROJECT_NAME = "pyproject.toml"
+# iOS lockfile name, kept for the iOS verbs' backward-compatible call sites.
+# New/platform-aware code uses ``lockfile_name``/``lockfile_path_for``.
+LOCKFILE_NAME = "pylock.ios.toml"
+
+
+def lockfile_name(platform: str) -> str:
+    """The per-platform lockfile filename, e.g. ``pylock.macos.toml``."""
+    return f"pylock.{platform}.toml"
+
+
+class ToolchainError(click.ClickException):
+    """A user-facing error that prints cleanly and exits non-zero.
+
+    Unlike a bare exception, ``click`` renders this as ``Error: <message>``
+    without a traceback, which is what we want for expected failure modes
+    (missing pyproject, validation errors, drift, etc.).
+    """
+
+    exit_code = 1
+
+
+def find_pyproject(start: Path | None = None) -> Path:
+    """Return the path to ``pyproject.toml`` in the current directory.
+
+    Raises ``ToolchainError`` if it is not present. No parent traversal is
+    performed — the tool is intentionally CWD-scoped so it never picks up an
+    unrelated ``pyproject.toml`` from an ancestor directory.
+    """
+    base = Path.cwd() if start is None else start
+    candidate = base / PYPROJECT_NAME
+    if not candidate.is_file():
+        raise ToolchainError(
+            f"no {PYPROJECT_NAME} found in the current directory ({base}).\n"
+            f"  Run kivyforge commands from the directory that contains your "
+            f"{PYPROJECT_NAME}, or run `kivyforge init` to create one."
+        )
+    return candidate
+
+
+def lockfile_path(start: Path | None = None) -> Path:
+    """Return the path where ``pylock.ios.toml`` lives (sibling to pyproject)."""
+    base = Path.cwd() if start is None else start
+    return base / LOCKFILE_NAME
+
+
+def lockfile_path_for(platform: str, start: Path | None = None) -> Path:
+    """Return the ``pylock.<platform>.toml`` path (sibling to pyproject)."""
+    base = Path.cwd() if start is None else start
+    return base / lockfile_name(platform)

kivyforge/cli/_platform.py

@@ -0,0 +1,84 @@
+"""CLI glue for target-platform selection (common design doc 02).
+
+Provides the shared ``-p/--platform`` option and ``resolve_target``, which reads
+which ``[tool.kivy.<platform>]`` overlays a project configures and runs the
+resolution chain, surfacing failures as clean ``ToolchainError`` messages.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+import click
+
+from ..platforms import (
+    Platform,
+    PlatformResolutionError,
+    available_platform_names,
+)
+from ..platforms import (
+    resolve_target as _resolve_target,
+)
+from ._common import ToolchainError, find_pyproject
+
+platform_option = click.option(
+    "--platform",
+    "-p",
+    "cli_platform",
+    type=click.Choice(available_platform_names()),
+    default=None,
+    help="Target platform (overrides KIVYFORGE_PLATFORM and the host default).",
+)
+
+
+def configured_platforms(pyproject: Path) -> set[str]:
+    """Platform names whose ``[tool.kivy.<name>]`` overlay this project declares."""
+    try:
+        raw = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError):
+        return set()
+    kivy = raw.get("tool", {}).get("kivy", {})
+    if not isinstance(kivy, dict):
+        return set()
+    return {name for name in available_platform_names() if name in kivy}
+
+
+def reject_android_only(backend: Platform, options: dict[str, object]) -> None:
+    """Fail when Android-only options are used against another platform.
+
+    The shared verbs carry the full option superset, so an option that only
+    Android acts on would otherwise be silently ignored elsewhere — the worst
+    outcome, since the user believes it took effect.
+    """
+    used = [name for name, value in options.items() if value]
+    if not used or backend.name == "android":
+        return
+    raise ToolchainError(
+        f"{', '.join(used)} {'is' if len(used) == 1 else 'are'} "
+        f"Android-only; not valid for {backend.name}."
+    )
+
+
+def resolve_target(
+    cli_platform: str | None, *, verb: str = "build"
+) -> tuple[Platform, Path]:
+    """Resolve the target platform and return it with the project root.
+
+    Looks for ``pyproject.toml`` in the CWD (like every verb), determines the
+    configured overlays, and runs the resolution chain. ``verb`` names the
+    calling CLI command so an unresolved-platform error's example command is
+    accurate (e.g. ``kivyforge lock --platform ios``, not always ``build``).
+    """
+    pyproject = find_pyproject()
+    try:
+        backend = _resolve_target(
+            cli_platform,
+            configured=configured_platforms(pyproject),
+            env=os.environ,
+            verb=verb,
+        )
+    except PlatformResolutionError as exc:
+        raise ToolchainError(str(exc)) from exc
+    return backend, pyproject.parent

kivyforge/cli/build.py

@@ -0,0 +1,111 @@
+"""``kivyforge build`` — materialize the lock into an Xcode project (specs 05/06).
+
+Build performs, in order:
+
+1. **Drift check** — the lock must be in sync with ``pyproject.toml``.
+2-5. **Artifact collection** — Python.xcframework, pinned wheels into
+   ``pip-deps/``, wheel-embedded + native ``.xcframework`` into ``Frameworks/``.
+6. **Project materialization** — generate ``<app>-ios/`` and the ``.xcodeproj``.
+7. **xcodebuild** — only when a target flag is given (Phase 6); a bare
+   ``kivyforge build`` stops after step 6 with a ready-to-open project.
+"""
+
+from __future__ import annotations
+
+import click
+
+from ._platform import platform_option, reject_android_only, resolve_target
+
+
+@click.command()
+@platform_option
+@click.option(
+    "--simulator",
+    "target",
+    flag_value="simulator",
+    help="Build for the iOS simulator (Debug).",
+)
+@click.option(
+    "--device", "target", flag_value="device", help="Build for a device (Debug)."
+)
+@click.option(
+    "--release", "target", flag_value="release", help="Archive + export a .ipa."
+)
+@click.option(
+    "--arch",
+    # x86_64 stays: it is the Linux arch and an Android ABI. It is not a macOS
+    # or iOS-simulator arch any more -- those backends reject it themselves.
+    type=click.Choice(["arm64", "x86_64"]),
+    default=None,
+    help="iOS: simulator arch. macOS: assemble a subset of the locked archs.",
+)
+@click.option(
+    "--no-verify-lock", is_flag=True, help="Skip the pyproject drift check (CI only)."
+)
+@click.option("--no-cache", is_flag=True, help="Force re-download of every artifact.")
+@click.option(
+    "--team-id", default=None, help="Override [tool.kivy.ios.signing].team_id."
+)
+@click.option(
+    "--signing-identity",
+    default=None,
+    help="Override [tool.kivy.ios.signing].identity.",
+)
+@click.option(
+    "--export-method",
+    type=click.Choice(["app-store", "ad-hoc", "development"]),
+    default="app-store",
+    help="Export method (only meaningful with --release).",
+)
+# --- Android-only ---
+@click.option(
+    "--debug",
+    is_flag=True,
+    help="Android: assemble the debug-signed artifact after generating.",
+)
+@click.option(
+    "-f",
+    "--format",
+    "fmt",
+    type=click.Choice(["apk", "aab"]),
+    default=None,
+    help="Android (with --debug): debug artifact format (default apk).",
+)
+@click.option(
+    "--abi",
+    type=click.Choice(["arm64_v8a", "x86_64"]),
+    default=None,
+    help="Android: restrict this build to one ABI.",
+)
+def build(
+    cli_platform: str | None,
+    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,
+    fmt: str | None,
+    abi: str | None,
+) -> None:
+    """Download artifacts, generate the platform project, and optionally build it."""
+    # Resolve the target platform before any work so an unresolved target fails
+    # fast with an actionable message (common design doc 02).
+    backend, project_root = resolve_target(cli_platform, verb="build")
+    reject_android_only(backend, {"--debug": debug, "-f/--format": fmt, "--abi": abi})
+
+    backend.build(
+        project_root,
+        target=target,
+        arch=arch,
+        no_verify_lock=no_verify_lock,
+        no_cache=no_cache,
+        team_id=team_id,
+        signing_identity=signing_identity,
+        export_method=export_method,
+        debug=debug,
+        fmt=fmt,
+        abi=abi,
+    )