kivyforge 3.0.0.dev0__py3-none-any.whl

kivyforge/platforms/windows/bundle.py

@@ -0,0 +1,298 @@
+r"""Assemble the Windows onedir bundle (windows-spec).
+
+Orchestrates the stages: pick the assembly arch from the lock (+ ``--arch``),
+stage the whole runtime prefix, install the locked wheels into it (no pip),
+copy the app sources, stage any declared native binaries, generate the bootstrap
+module, then place + resource-patch the launcher. Produces:
+
+    build/windows/<Name>/
+    ├── <Name>.exe                ← prebuilt launcher, resource-patched per app
+    ├── _kivyforge_bootstrap.py   ← generated (fixed name)
+    ├── app/                      ← user code ([tool.kivy].app_dir)
+    ├── bin/                      ← declared native binaries (absent when empty)
+    └── python/                   ← WHOLE PBS prefix
+
+The tree is assembled **in place** (see :mod:`.fsswap`): a freshly written tree
+cannot be reliably renamed on Windows because the antivirus scanner holds new
+files open, so any previous bundle is reserved first and restored if assembly
+fails — a broken build never destroys a working one.
+
+The onedir *folder* is a distributable format either way (portable use, zip it
+up yourself) — but *this* build's contents depend on ``release``: ``build``/
+``run`` (``release=False``) keep readable ``.py`` for fast iteration, while
+``package`` (``release=True``) additionally byte-compiles per
+``[tool.kivy.windows.build_settings]`` before copying the tree into
+``dist/windows``. ``release`` is a build-policy flag, not a statement about
+whether the folder *can* be distributed.
+"""
+
+from __future__ import annotations
+
+import platform
+import shutil
+from pathlib import Path
+
+import click
+
+from kivyforge.artifacts.cache import ArtifactCache
+from kivyforge.bundle.pycompile import PycompileError, byte_compile, select_compiler
+from kivyforge.config.model import Config
+
+from . import WindowsBundleError
+from .fsswap import discard_reserved, reserve_previous, restore_previous
+from .icons import stage_icon
+from .launcher import launcher_exe_name, place_launcher, write_bootstrap
+from .lock import WindowsLockfile
+from .naming import windows_safe_name
+from .native_stage import stage_native_binaries
+from .rcedit import ResourcePatch
+from .runtime_stage import stage_runtime
+from .signing import pep440_to_file_version
+from .wheels_stage import stage_wheels
+
+_IGNORE = shutil.ignore_patterns("__pycache__", "*.pyc")
+
+
+def resolve_assembly_arch(locked: tuple[str, ...], arch: str | None) -> str:
+    """The single arch to assemble. Windows ships one arch (``amd64``) per onedir."""
+    if not locked:
+        raise WindowsBundleError(
+            "the lock covers no architectures; re-run `kivyforge lock -p windows`."
+        )
+    if arch is None:
+        return locked[0]
+    if arch not in locked:
+        raise WindowsBundleError(
+            f"--arch {arch} is not in the lock (covers {', '.join(locked)}).\n"
+            f"  Add {arch!r} to [tool.kivy.windows].archs and re-lock, or pick a "
+            "locked arch."
+        )
+    return arch
+
+
+def bundle_dir_name(config: Config) -> str:
+    """The onedir folder name for *config* (Windows-safe display name)."""
+    return windows_safe_name(config.display_name)
+
+
+def _setting_applies(value: bool | str, *, release: bool) -> bool:
+    """A ``build_settings`` tri-state resolved for the build being produced."""
+    if isinstance(value, bool):
+        return value
+    return release  # DESKTOP_RELEASE_ONLY
+
+
+def _resolve_byte_compile(
+    config: Config,
+    *,
+    staged_interpreter: Path,
+    target_arch: str,
+    python_version: str,
+    release: bool,
+) -> tuple[tuple[str, ...] | None, bool]:
+    """Decide whether to byte-compile, and with which interpreter.
+
+    Returns ``(compiler_argv_or_None, strip_source)``; ``None`` means do not
+    byte-compile. ``byte_compile = true`` is read as "I insist", so a missing
+    interpreter is an error; the default ``"release"`` degrades to shipping
+    source with a warning rather than breaking a build the user never
+    configured.
+    """
+    settings = config.windows_required.build_settings
+    if not _setting_applies(settings.byte_compile, release=release):
+        return None, False
+    native = platform.machine().lower() == target_arch
+    compiler = select_compiler(
+        staged_interpreter=staged_interpreter,
+        native=native,
+        python_version=python_version,
+    )
+    if compiler is None:
+        message = (
+            f"this project ships CPython {python_version}, and no CPython of "
+            "that minor could be found to byte-compile with (a .pyc is only "
+            "loadable by the exact CPython minor that wrote it)"
+        )
+        if settings.byte_compile is True:
+            raise WindowsBundleError(
+                "[tool.kivy.windows.build_settings].byte_compile = true but "
+                f"{message}.\n"
+                "  Install a matching CPython, or set byte_compile = false."
+            )
+        click.echo(f"[stage] not byte-compiling: {message}.")
+        return None, False
+    strip = _setting_applies(settings.strip_source, release=release)
+    return compiler, strip
+
+
+def build_onedir(
+    config: Config,
+    lock: WindowsLockfile,
+    project_root: Path,
+    *,
+    arch: str | None = None,
+    staging_dir: Path | None = None,
+    no_cache: bool = False,
+    cache: ArtifactCache | None = None,
+    release: bool = False,
+    echo=click.echo,
+) -> Path:
+    """Build the onedir bundle tree and return its path.
+
+    The tree is assembled **directly into its final location**. Temp-dir + rename
+    (the POSIX pattern) is not viable on Windows: a just-written tree cannot be
+    reliably renamed because the antivirus real-time scanner holds the new
+    executables/DLLs open — on a cold first-sight scan (cloud lookup) that lasts
+    well beyond any reasonable retry window. Instead we preserve any previous
+    bundle in a trash dir first and restore it if assembly fails, so a broken
+    build never destroys a working one. The trash is an already-scanned tree,
+    which renames instantly; only freshly written files (which we never rename)
+    hit the scan window.
+    """
+    target_arch = resolve_assembly_arch(lock.archs, arch)
+    cache = cache or ArtifactCache()
+    staging_dir = staging_dir or (project_root / "build" / "windows")
+    bundle = staging_dir / bundle_dir_name(config)
+
+    staging_dir.mkdir(parents=True, exist_ok=True)
+    trash = reserve_previous(bundle)
+    try:
+        echo(
+            f"Staging CPython {lock.python_runtime.version} runtime ({target_arch}) ..."
+        )
+        stage_runtime(
+            lock.python_runtime,
+            target_arch,
+            bundle / "python",
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+
+        echo(f"Installing {len(lock.packages)} locked packages ...")
+        stage_wheels(
+            lock.packages,
+            target_arch,
+            bundle / "python",
+            project_root=project_root,
+            cache=cache,
+            no_cache=no_cache,
+        )
+
+        if lock.native_binaries:
+            echo(f"Staging {len(lock.native_binaries)} native binaries ...")
+            stage_native_binaries(
+                lock,
+                bundle,
+                target_arch,
+                project_root=project_root,
+                cache=cache,
+                no_cache=no_cache,
+            )
+
+        _copy_app_sources(config, project_root, bundle / "app")
+
+        compiler, strip_source = _resolve_byte_compile(
+            config,
+            staged_interpreter=bundle / "python" / "python.exe",
+            target_arch=target_arch,
+            python_version=lock.python_runtime.version,
+            release=release,
+        )
+        if compiler is not None:
+            with_what = " ".join(compiler) if compiler else "this interpreter"
+            echo(
+                f"[stage] byte-compiling the Python payload with {with_what}"
+                + (" (.pyc only)" if strip_source else "")
+            )
+            try:
+                byte_compile(
+                    [bundle / "app", bundle / "python" / "Lib" / "site-packages"],
+                    compiler=compiler,
+                    strip_source=strip_source,
+                    stripdir=bundle,
+                )
+            except PycompileError as exc:
+                raise WindowsBundleError(
+                    f"{exc}\n  Fix it, or set "
+                    "[tool.kivy.windows.build_settings].byte_compile = false."
+                ) from exc
+
+        write_bootstrap(
+            bundle,
+            entry_point=config.kivy.entry_point,
+            app_id=config.windows_required.app_id,
+        )
+
+        icon = stage_icon(config, project_root, bundle / "app.ico")
+        place_launcher(
+            bundle,
+            display_name=config.display_name,
+            patch=_resource_patch(config, icon),
+        )
+    except BaseException:
+        shutil.rmtree(bundle, ignore_errors=True)
+        restore_previous(trash, bundle)
+        raise
+
+    discard_reserved(trash)
+    return bundle
+
+
+def _first_author(config: Config) -> str | None:
+    """First ``[project].authors`` name, or ``None`` — the publisher/copyright.
+
+    Mirrors the iOS ``NSHumanReadableCopyright`` convention (pyproject-ios): the
+    first author's name populates both ``LegalCopyright`` and ``CompanyName`` in
+    the Windows version resource. Verbatim (no synthesized year) so the patch
+    stays deterministic.
+    """
+    return next((a.name for a in config.project.authors if a.name), None)
+
+
+def _resource_patch(config: Config, icon: Path | None) -> ResourcePatch:
+    """The launcher resource patch from project metadata.
+
+    The string ProductVersion carries the full PEP 440 version; the numeric
+    FILEVERSION/PRODUCTVERSION use the deterministic four-part mapping (signing).
+    LegalCopyright/CompanyName come from the first ``[project].authors`` entry.
+    """
+    version = config.project.version
+    numeric = pep440_to_file_version(version)
+    author = _first_author(config)
+    return ResourcePatch(
+        icon=icon,
+        product_name=config.display_name,
+        file_description=config.display_name,
+        product_version_string=version,
+        legal_copyright=author,
+        company_name=author,
+        file_version=numeric,
+        product_version=numeric,
+    )
+
+
+def _copy_app_sources(config: Config, project_root: Path, dest: Path) -> None:
+    src = (project_root / config.kivy.app_dir).resolve()
+    if not src.is_dir():
+        raise WindowsBundleError(
+            f"[tool.kivy].app_dir points to {config.kivy.app_dir!r}, which is not "
+            f"a directory under {project_root}."
+        )
+    entry_rel = f"{config.kivy.entry_point.replace('.', '/')}.py"
+    entry = src / entry_rel
+    if not entry.is_file():
+        raise WindowsBundleError(
+            f"entry point {entry_rel} not found in "
+            f"{config.kivy.app_dir}/ (set [tool.kivy].entry_point)."
+        )
+    shutil.copytree(src, dest, ignore=_IGNORE)
+
+
+# Re-exported for the verbs/status so they compute the same path.
+def onedir_path(config: Config, project_root: Path) -> Path:
+    return project_root / "build" / "windows" / bundle_dir_name(config)
+
+
+def launcher_name(config: Config) -> str:
+    return launcher_exe_name(config.display_name)

kivyforge/platforms/windows/cli.py

@@ -0,0 +1,314 @@
+"""Windows dispatch for the shared ``build`` / ``run`` / ``package`` verbs.
+
+Keeps the Windows onedir flow out of the (iOS/Xcode-centric) verb modules: each
+verb resolves the target platform and, when it is Windows, calls in here. Loads
+the Windows config + ``pylock.windows.toml``, runs the drift check, and drives
+the onedir bundler. The onedir folder is both the ``run`` target and — copied to
+``dist/windows`` — the ``package`` output (installers stay external).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+import click
+
+from kivyforge.cli._common import ToolchainError, lockfile_path_for
+from kivyforge.config import ConfigError, load_config
+from kivyforge.lock.reader import LockError, is_in_sync
+
+from .. import HostCapabilityError, get_platform
+from . import WindowsBundleError
+from .bundle import (
+    build_onedir,
+    bundle_dir_name,
+    launcher_name,
+    onedir_path,
+    resolve_assembly_arch,
+)
+from .fsswap import discard_reserved, reserve_previous, restore_previous
+from .lock import WindowsLockfile
+from .lock import load as load_windows_lock
+from .signing import select_signer
+
+# Never copy VCS metadata or editor droppings into the shipped dist tree. The
+# onedir bundle is assembled clean, so this is defense in depth (and covers a
+# build/ dir a user pointed packaging at directly).
+#
+# Deliberately does NOT exclude __pycache__/*.pyc/*.pyo: those used to be junk
+# patterns before byte-compilation existed, but [tool.kivy.windows
+# .build_settings] now makes .pyc the actual shipped payload -- excluding it
+# here would silently ship an empty app/ once strip_source has deleted the
+# .py, which is exactly what byte_compile/strip_source is supposed to produce.
+_PACKAGE_IGNORE = shutil.ignore_patterns(
+    ".git",
+    ".gitignore",
+    ".gitattributes",
+    ".svn",
+    ".hg",
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+    ".idea",
+    ".vscode",
+    "*.swp",
+    "*~",
+)
+
+
+def windows_build(
+    project_root: Path,
+    *,
+    arch: str | None,
+    no_verify_lock: bool,
+    no_cache: bool,
+) -> Path:
+    """Assemble the Windows onedir bundle; return its path."""
+    _require_windows_host()
+    config, lock = _load_and_verify(project_root, no_verify_lock)
+    bundle = _assemble(
+        config, lock, project_root, arch=arch, no_cache=no_cache, release=False
+    )
+    click.echo(f"Built {bundle.relative_to(project_root)}")
+    return bundle
+
+
+def windows_package(
+    project_root: Path,
+    *,
+    fmt: str,
+    arch: str | None,
+    no_verify_lock: bool,
+    no_cache: bool,
+) -> Path:
+    """Produce the distributable: the onedir folder copied to ``dist/windows``.
+
+    ``folder`` is the only Windows package format (installers stay external). The
+    copied tree is the portable, run-from-folder distributable.
+    """
+    _require_windows_host()
+    config, lock = _load_and_verify(project_root, no_verify_lock)
+    target_arch = _resolve_arch(lock, arch)
+    bundle = _assemble(
+        config, lock, project_root, arch=target_arch, no_cache=no_cache, release=True
+    )
+
+    # The dist folder name matches the build tree: the display_name run through
+    # the Windows filename sanitizer (windows-spec), not the raw project.name.
+    dest = (
+        project_root
+        / "dist"
+        / "windows"
+        / f"{bundle_dir_name(config)}-{config.project.version}-{target_arch}"
+    )
+    # Reserve any prior package and keep it until *signing* also succeeds, so a
+    # signer failure (missing cert, timestamp outage) rolls back to the previous
+    # known-good artifact rather than leaving a half-baked unsigned tree in place.
+    trash = _stage_dist_copy(bundle, dest)
+    try:
+        # Signing (when configured) targets the dist copy only, after the resource
+        # patch (done at build) and before any external installer. The build tree
+        # stays unsigned as the dev-run target.
+        signed = _sign_launcher(config, dest)
+    except BaseException:
+        shutil.rmtree(dest, ignore_errors=True)
+        restore_previous(trash, dest)
+        raise
+    discard_reserved(trash)
+
+    note = (
+        "signed + timestamped"
+        if signed
+        else "unsigned (configure [tool.kivy.windows.signing] to sign)"
+    )
+    click.echo(
+        f"Packaged {dest.relative_to(project_root)} (onedir folder, {note}).\n"
+        f"  Run it by double-clicking {launcher_name(config)}, or zip the folder "
+        "to distribute. An installer is an external step."
+    )
+    return dest
+
+
+def windows_run(
+    project_root: Path,
+    *,
+    arch: str | None,
+    no_build: bool,
+) -> None:
+    """Build (unless --no-build) and launch the app ``.exe`` in the foreground."""
+    if no_build:
+        _require_windows_host()
+        config = _load_config(project_root)
+        bundle = onedir_path(config, project_root)
+        if not bundle.exists():
+            raise ToolchainError(
+                f"no built bundle at {bundle.relative_to(project_root)}; run "
+                "without --no-build first."
+            )
+    else:
+        config = _load_config(project_root)
+        bundle = windows_build(
+            project_root, arch=arch, no_verify_lock=False, no_cache=False
+        )
+
+    exe = bundle / launcher_name(config)
+    click.echo(f"Launching {bundle.name} ...")
+    # Foreground: the launcher attaches to this console so the dev sees
+    # stdout/stderr + tracebacks (the Phase 3 console handoff).
+    proc = subprocess.run([str(exe)])
+    if proc.returncode != 0:
+        raise ToolchainError(f"{bundle.name} exited with status {proc.returncode}.")
+
+
+def windows_status(project_root: Path) -> None:
+    """Show app identity, Python version, lock sync, and build state."""
+    config = _load_config(project_root)
+    windows = config.windows_required
+    click.echo(f"App:        {config.display_name}  ({windows.app_id})")
+    click.echo(f"Python:     {windows.python_version or '(unset)'}")
+    click.echo(f"Lock:       {_lock_state(project_root)}")
+    click.echo(f"Build:      {_build_state(onedir_path(config, project_root))}")
+
+
+def _assemble(config, lock, project_root, *, arch, no_cache, release) -> Path:
+    try:
+        return build_onedir(
+            config, lock, project_root, arch=arch, no_cache=no_cache, release=release
+        )
+    except WindowsBundleError as exc:
+        raise ToolchainError(str(exc)) from exc
+
+
+def _resolve_arch(lock: WindowsLockfile, arch: str | None) -> str:
+    try:
+        return resolve_assembly_arch(lock.archs, arch)
+    except WindowsBundleError as exc:
+        raise ToolchainError(str(exc)) from exc
+
+
+def _sign_launcher(config, dest: Path) -> bool:
+    """Sign the launcher in the dist copy when signing is configured.
+
+    Returns whether the artifact was signed. Translates any signing failure into
+    a :class:`ToolchainError` so ``package`` reports it cleanly.
+    """
+    signer = select_signer(config.windows_required.signing)
+    if not signer.configured:
+        return False
+    exe = dest / launcher_name(config)
+    try:
+        signer.sign([exe])
+    except WindowsBundleError as exc:
+        raise ToolchainError(str(exc)) from exc
+    return True
+
+
+def _stage_dist_copy(bundle: Path, dest: Path) -> Path | None:
+    """Copy *bundle* into *dest*, returning the reserved previous tree (or None).
+
+    Copies **directly into the final location**: like the build step, a freshly
+    written tree cannot be reliably renamed on Windows (the antivirus scanner
+    holds new files open), so temp-dir + rename is not viable. Any previous dist
+    copy is reserved first and restored if the copy fails, so a broken package
+    never destroys a working one.
+
+    The reserved previous tree is **not** discarded here: the caller must call
+    :func:`discard_reserved` only after every later step (e.g. signing) succeeds,
+    or :func:`restore_previous` to roll back. This keeps the previous known-good
+    artifact recoverable across a post-copy failure.
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        trash = reserve_previous(dest)
+    except WindowsBundleError as exc:
+        raise ToolchainError(str(exc)) from exc
+    try:
+        # copytree needs a non-existent target; the reserve moved any prior away.
+        shutil.copytree(bundle, dest, ignore=_PACKAGE_IGNORE)
+    except BaseException:
+        shutil.rmtree(dest, ignore_errors=True)
+        restore_previous(trash, dest)
+        raise
+    return trash
+
+
+def _load_and_verify(
+    project_root: Path, no_verify_lock: bool
+) -> tuple[object, WindowsLockfile]:
+    config = _load_config(project_root)
+    lock = _load_lock(project_root)
+    pyproject = project_root / "pyproject.toml"
+    if not no_verify_lock and not is_in_sync(lock, pyproject.read_text("utf-8")):
+        raise ToolchainError(
+            f"{lockfile_path_for('windows').name} is out of date with "
+            "pyproject.toml.\n"
+            "  Run `kivyforge lock -p windows` to regenerate it (or pass "
+            "--no-verify-lock to build against the stale lock anyway)."
+        )
+    return config, lock
+
+
+def _lock_state(project_root: Path) -> str:
+    path = lockfile_path_for("windows", project_root)
+    if not path.is_file():
+        return "missing (run `kivyforge lock -p windows`)"
+    try:
+        lock = load_windows_lock(path)
+    except LockError:
+        return "unreadable (run `kivyforge lock -p windows`)"
+    pyproject = project_root / "pyproject.toml"
+    if is_in_sync(lock, pyproject.read_text("utf-8")):
+        return "in sync"
+    return "out of date (run `kivyforge lock -p windows`)"
+
+
+def _build_state(bundle: Path) -> str:
+    if not bundle.exists():
+        return "not built"
+    age = time.time() - bundle.stat().st_mtime
+    return f"last built {_humanize(age)}"
+
+
+def _humanize(seconds: float) -> str:
+    seconds = int(seconds)
+    if seconds < 60:
+        return "just now"
+    if seconds < 3600:
+        m = seconds // 60
+        return f"{m} minute{'s' if m != 1 else ''} ago"
+    if seconds < 86400:
+        h = seconds // 3600
+        return f"{h} hour{'s' if h != 1 else ''} ago"
+    d = seconds // 86400
+    return f"{d} day{'s' if d != 1 else ''} ago"
+
+
+def _require_windows_host() -> None:
+    try:
+        get_platform("windows").check_host_capability()
+    except HostCapabilityError as exc:
+        raise ToolchainError(str(exc)) from exc
+
+
+def _load_config(project_root: Path):
+    try:
+        return load_config(
+            project_root / "pyproject.toml", require_ios=False, require_windows=True
+        )
+    except ConfigError as exc:
+        raise ToolchainError(exc.format()) from exc
+
+
+def _load_lock(project_root: Path) -> WindowsLockfile:
+    path = lockfile_path_for("windows", project_root)
+    if not path.is_file():
+        raise ToolchainError(
+            f"no {path.name} found. Run `kivyforge lock -p windows` first."
+        )
+    try:
+        return load_windows_lock(path)
+    except LockError as exc:
+        raise ToolchainError(str(exc)) from exc