pyappdist 0.1.0__py3-none-any.whl

pyappdist/_hostexec.py

@@ -0,0 +1,30 @@
+"""Execution helpers that absorb host/target differences.
+
+When handling a Windows target from WSL (a Linux host), Windows tools (uv.exe)
+must be invoked and paths converted to Windows form (wslpath -w).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from .targets import Target
+
+
+def is_cross_windows(target: Target) -> bool:
+    """Handling a Windows target from a Linux host (requires the .exe bridge)."""
+    return target.os == "windows" and sys.platform != "win32"
+
+
+def target_path(target: Target, path: Path | str) -> str:
+    """Path string to pass to a target tool."""
+    p = Path(path)
+    if is_cross_windows(target):
+        out = subprocess.run(
+            ["wslpath", "-w", str(p)], capture_output=True, text=True,
+            errors="replace", check=True,
+        )
+        return out.stdout.strip()
+    return str(p)

pyappdist/cli.py

@@ -0,0 +1,199 @@
+"""pyappdist CLI.
+
+Subcommands:
+  build-wheels   app + dependency wheels into appdist/wheelhouse
+  fetch-runtime  python-build-standalone runtime into appdist/runtime
+  build-image    runtime + install + compileall + launcher + portable zip into appdist/image
+  build-launchers build launcher.exe inside the image (Windows, MSVC)
+  gen-wix        scan the image and generate WiX XML (.wxs)
+  build          run wheels->runtime->image->launcher->wix->MSI in one go
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import sys
+from pathlib import Path
+
+from . import image as image_mod
+from .config import ensure_upgrade_code, load_config
+from .context import BuildContext
+from .errors import BuildError, PyappdistError
+from .launcher import build_launchers
+from .runtime import fetch_runtime
+from .sign import sign_artifact
+from .wheels import build_wheelhouse
+from .wix import build_msi, generate_wxs, scan_image
+
+
+def _build_context(args: argparse.Namespace) -> BuildContext:
+    project_dir = Path(args.project).resolve()
+    config = load_config(project_dir, target_override=args.target)
+    out_dir = Path(args.out_dir).resolve() if args.out_dir else project_dir / "appdist"
+    return BuildContext(config=config, out_dir=out_dir)
+
+
+def _do_fetch_runtime(ctx: BuildContext, args: argparse.Namespace):
+    return fetch_runtime(
+        ctx.config.target,
+        ctx.config.python,
+        ctx.runtime_dir,
+        runtime_source=Path(args.runtime_source) if args.runtime_source else None,
+        runtime_release=args.runtime_release,
+    )
+
+
+def cmd_build_wheels(args: argparse.Namespace) -> int:
+    ctx = _build_context(args)
+    # Dependencies are resolved with the target runtime's python, so prepare the runtime first.
+    info = _do_fetch_runtime(ctx, args)
+    wheels = build_wheelhouse(ctx.config, info, ctx.wheelhouse)
+    print(f"OK: {len(wheels)} wheel -> {ctx.wheelhouse}")
+    return 0
+
+
+def cmd_fetch_runtime(args: argparse.Namespace) -> int:
+    ctx = _build_context(args)
+    info = _do_fetch_runtime(ctx, args)
+    print(f"OK: runtime {info.version} -> {ctx.runtime_dir}")
+    return 0
+
+
+def cmd_build_image(args: argparse.Namespace) -> int:
+    ctx = _build_context(args)
+    info = _do_fetch_runtime(ctx, args)
+    build_wheelhouse(ctx.config, info, ctx.wheelhouse)
+    layout = image_mod.build_image(ctx, info, compile_pyc=not args.no_compile)
+    exes = build_launchers(ctx.config, layout, ctx.out_dir / "_launcher_build")
+    # The zip includes launcher.exe, so do it after the launcher build.
+    if not args.no_zip:
+        image_mod.make_portable_zip(ctx)
+    print(f"OK: image -> {layout.image_dir} ({len(exes)} launcher)")
+    return 0
+
+
+def cmd_build_launchers(args: argparse.Namespace) -> int:
+    ctx = _build_context(args)
+    if not ctx.image_dir.is_dir():
+        raise BuildError(
+            f"image is missing: {ctx.image_dir} (run build-image first)"
+        )
+    layout = image_mod.ImageLayout(
+        image_dir=ctx.image_dir,
+        target=ctx.config.target,
+        minor=ctx.config.python_minor,
+    )
+    exes = build_launchers(ctx.config, layout, ctx.out_dir / "_launcher_build")
+    print(f"OK: {len(exes)} launcher -> {layout.image_dir}")
+    return 0
+
+
+def _write_wxs(ctx: BuildContext) -> Path:
+    # Ensure a stable upgrade_code exists (generated and persisted to pyproject.toml if unset).
+    upgrade_code = ensure_upgrade_code(ctx.config.project_dir)
+    config = ctx.config
+    if config.wix.upgrade_code != upgrade_code:
+        config = dataclasses.replace(
+            config, wix=dataclasses.replace(config.wix, upgrade_code=upgrade_code)
+        )
+    tree = scan_image(ctx.image_dir)
+    xml = generate_wxs(config, tree)
+    wxs = ctx.out_dir / f"{ctx.config.dist_name}.wxs"
+    wxs.write_text(xml, encoding="utf-8")
+    return wxs
+
+
+def cmd_gen_wix(args: argparse.Namespace) -> int:
+    ctx = _build_context(args)
+    if not ctx.image_dir.is_dir():
+        raise BuildError(f"image is missing: {ctx.image_dir} (run build-image first)")
+    wxs = _write_wxs(ctx)
+    print(f"OK: wxs -> {wxs}")
+    return 0
+
+
+def cmd_build(args: argparse.Namespace) -> int:
+    """Run wheelhouse -> runtime -> image -> launcher -> wix -> MSI in one go (Phase 5)."""
+    ctx = _build_context(args)
+    info = _do_fetch_runtime(ctx, args)
+    build_wheelhouse(ctx.config, info, ctx.wheelhouse)
+    layout = image_mod.build_image(ctx, info, compile_pyc=not args.no_compile)
+    exes = build_launchers(ctx.config, layout, ctx.out_dir / "_launcher_build")
+    for exe in exes:
+        sign_artifact(exe)
+    if not args.no_zip:
+        image_mod.make_portable_zip(ctx)
+
+    wxs = _write_wxs(ctx)
+    msi_name = f"{ctx.config.dist_name}-{ctx.config.version}.msi"
+    msi = build_msi(ctx.config, ctx.image_dir, wxs, ctx.dist_dir / msi_name)
+    if msi is not None:
+        sign_artifact(msi)
+        print(f"OK: msi -> {msi} ({len(exes)} launcher)")
+    else:
+        print(f"OK: image -> {layout.image_dir} (msi skipped on non-Windows)")
+    return 0
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("project", nargs="?", default=".", help="the app's project directory")
+    p.add_argument("--target", help="distribution target (e.g. windows-x86_64 / linux-x86_64)")
+    p.add_argument("--out-dir", help="output directory (default: <project>/appdist)")
+
+
+def _add_runtime_opts(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--runtime-release", help="pin the python-build-standalone release tag")
+    p.add_argument("--runtime-source", help="local runtime tar.gz (offline)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pyappdist", description="Create a Windows distribution of a Python app")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("build-wheels", help="wheels into appdist/wheelhouse")
+    _add_common(p)
+    _add_runtime_opts(p)
+    p.set_defaults(func=cmd_build_wheels)
+
+    p = sub.add_parser("fetch-runtime", help="runtime into appdist/runtime")
+    _add_common(p)
+    _add_runtime_opts(p)
+    p.set_defaults(func=cmd_fetch_runtime)
+
+    p = sub.add_parser("build-image", help="image into appdist/image")
+    _add_common(p)
+    _add_runtime_opts(p)
+    p.add_argument("--no-compile", action="store_true", help="skip compileall")
+    p.add_argument("--no-zip", action="store_true", help="do not create a portable zip")
+    p.set_defaults(func=cmd_build_image)
+
+    p = sub.add_parser("build-launchers", help="build launcher.exe into the image (Windows)")
+    _add_common(p)
+    p.set_defaults(func=cmd_build_launchers)
+
+    p = sub.add_parser("gen-wix", help="generate WiX XML (.wxs) from the image")
+    _add_common(p)
+    p.set_defaults(func=cmd_gen_wix)
+
+    p = sub.add_parser("build", help="run wheels->runtime->image->launcher->wix->MSI in one go")
+    _add_common(p)
+    _add_runtime_opts(p)
+    p.add_argument("--no-compile", action="store_true")
+    p.add_argument("--no-zip", action="store_true")
+    p.set_defaults(func=cmd_build)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except PyappdistError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyappdist/config.py

@@ -0,0 +1,176 @@
+"""Loading and validation of ``[tool.pyappdist]``.
+
+Treats pyproject.toml as the single source of truth and normalizes it into a
+typed dataclass.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import ConfigError
+from .targets import Target, get_target
+
+_PYTHON_RE = re.compile(r"^\d+\.\d+(\.\d+)?$")
+
+_MANAGERS = ("uv", "poetry", "pipenv", "pdm", "requirements.txt")
+
+
+@dataclass(frozen=True)
+class LauncherConfig:
+    name: str           # output exe name (without extension)
+    entry: str          # "module:callable"
+    gui: bool = False
+    icon: str | None = None
+    args: str = ""      # fixed arguments (single string)
+
+
+@dataclass(frozen=True)
+class WixConfig:
+    manufacturer: str | None = None
+    upgrade_code: str | None = None
+
+
+@dataclass(frozen=True)
+class Config:
+    project_dir: Path
+    name: str           # display name
+    dist_name: str      # distribution package name ([project].name)
+    version: str
+    python: str         # "X.Y" or "X.Y.Z"
+    target: Target
+    identifier: str | None
+    launchers: tuple[LauncherConfig, ...]
+    wix: WixConfig
+    manager: str | None  # manager used for dependency resolution (uv/poetry/pipenv/pdm/requirements.txt). None=auto-detect
+
+    @property
+    def python_minor(self) -> str:
+        parts = self.python.split(".")
+        return f"{parts[0]}.{parts[1]}"
+
+
+def load_config(project_dir: Path, *, target_override: str | None = None) -> Config:
+    project_dir = Path(project_dir).resolve()
+    pyproject = project_dir / "pyproject.toml"
+    if not pyproject.is_file():
+        raise ConfigError(f"pyproject.toml not found: {pyproject}")
+
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    project = data.get("project", {})
+    tool = data.get("tool", {}).get("pyappdist")
+    if tool is None:
+        raise ConfigError(f"[tool.pyappdist] is missing: {pyproject}")
+
+    dist_name = project.get("name")
+    if not dist_name:
+        raise ConfigError("[project].name is required")
+    name = tool.get("name") or dist_name
+
+    version = tool.get("version") or project.get("version") or "0.0.0"
+
+    python = tool.get("python")
+    if not python:
+        raise ConfigError("[tool.pyappdist].python is required (e.g. \"3.12\")")
+    if not _PYTHON_RE.match(str(python)):
+        raise ConfigError(f"python must be in X.Y or X.Y.Z format: {python!r}")
+
+    target_name = target_override or tool.get("target") or "windows-x86_64"
+    target = get_target(target_name)
+
+    launchers = _parse_launchers(tool.get("launchers"))
+    wix = _parse_wix(tool.get("wix"))
+
+    manager = tool.get("manager")
+    if manager is not None and manager not in _MANAGERS:
+        raise ConfigError(
+            f"[tool.pyappdist].manager must be one of {_MANAGERS}: {manager!r}"
+        )
+
+    return Config(
+        project_dir=project_dir,
+        name=str(name),
+        dist_name=str(dist_name),
+        version=str(version),
+        python=str(python),
+        target=target,
+        identifier=tool.get("identifier"),
+        launchers=launchers,
+        wix=wix,
+        manager=manager,
+    )
+
+
+def _parse_launchers(raw: object) -> tuple[LauncherConfig, ...]:
+    if raw is None:
+        return ()
+    if not isinstance(raw, list):
+        raise ConfigError("[tool.pyappdist].launchers must be an array")
+    out: list[LauncherConfig] = []
+    for i, item in enumerate(raw):
+        if not isinstance(item, dict):
+            raise ConfigError(f"launchers[{i}] must be a table")
+        name = item.get("name")
+        entry = item.get("entry")
+        if not name:
+            raise ConfigError(f"launchers[{i}].name is required")
+        if not entry or ":" not in str(entry):
+            raise ConfigError(
+                f"launchers[{i}].entry must be in \"module:callable\" format: {entry!r}"
+            )
+        out.append(
+            LauncherConfig(
+                name=str(name),
+                entry=str(entry),
+                gui=bool(item.get("gui", False)),
+                icon=item.get("icon"),
+                args=str(item.get("args", "")),
+            )
+        )
+    return tuple(out)
+
+
+def ensure_upgrade_code(project_dir: Path, *, log=print) -> str:
+    """Return the WiX upgrade_code, generating and persisting one if unset.
+
+    The upgrade code identifies the product across versions for MSI MajorUpgrade,
+    so it must stay stable across builds. When it is missing from pyproject.toml we
+    generate a UUID and write it back into [tool.pyappdist.wix], editing with
+    tomlkit so existing formatting and comments are preserved.
+    """
+    import uuid
+
+    import tomlkit
+
+    from .wix.guid import is_guid
+
+    pyproject = Path(project_dir).resolve() / "pyproject.toml"
+    doc = tomlkit.parse(pyproject.read_text(encoding="utf-8"))
+
+    wix = doc.get("tool", {}).get("pyappdist", {}).get("wix")
+    existing = wix.get("upgrade_code") if wix is not None else None
+    if existing and is_guid(str(existing)):
+        return str(existing)
+
+    code = str(uuid.uuid4()).upper()
+    tool = doc.setdefault("tool", tomlkit.table())
+    pyappdist = tool.setdefault("pyappdist", tomlkit.table())
+    wix_tbl = pyappdist.setdefault("wix", tomlkit.table())
+    wix_tbl["upgrade_code"] = code
+    pyproject.write_text(tomlkit.dumps(doc), encoding="utf-8")
+    log(f"wix: generated upgrade_code {code} -> {pyproject}")
+    return code
+
+
+def _parse_wix(raw: object) -> WixConfig:
+    if raw is None:
+        return WixConfig()
+    if not isinstance(raw, dict):
+        raise ConfigError("[tool.pyappdist.wix] must be a table")
+    return WixConfig(
+        manufacturer=raw.get("manufacturer"),
+        upgrade_code=raw.get("upgrade_code"),
+    )

pyappdist/context.py

@@ -0,0 +1,30 @@
+"""Container for paths and settings shared across the whole build."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import Config
+
+
+@dataclass(frozen=True)
+class BuildContext:
+    config: Config
+    out_dir: Path  # appdist/
+
+    @property
+    def wheelhouse(self) -> Path:
+        return self.out_dir / "wheelhouse"
+
+    @property
+    def runtime_dir(self) -> Path:
+        return self.out_dir / "runtime"
+
+    @property
+    def image_dir(self) -> Path:
+        return self.out_dir / "image"
+
+    @property
+    def dist_dir(self) -> Path:
+        return self.out_dir / "dist"

pyappdist/deps.py

@@ -0,0 +1,104 @@
+"""Determining the dependency list (package manager lockfile -> requirements.txt).
+
+Dependencies are pinned **based on the project's lockfile**. Using the manager
+the developer uses (uv / poetry / pipenv / PDM), ``requirements.txt`` is exported
+from the lock, and later ``pip wheel -r requirements.txt`` is run with the target
+runtime's python. The export emits production dependencies only (dev excluded),
+with cross markers and hashes.
+
+Resolution:
+* An explicit ``[tool.pyappdist].manager`` setting takes top priority (if
+  ``requirements.txt`` is specified, the requirements.txt directly under the
+  project is used as-is).
+* If unset, lockfiles are searched in the order uv.lock -> poetry.lock ->
+  Pipfile.lock -> pdm.lock, and the first tool found is used.
+* If undeterminable, a warning is emitted and it operates in ``requirements.txt``
+  mode (``BuildError`` if absent).
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from .config import Config
+from .errors import BuildError
+
+# tool name -> lockfile name (auto-detect search order).
+_LOCKFILES: tuple[tuple[str, str], ...] = (
+    ("uv", "uv.lock"),
+    ("poetry", "poetry.lock"),
+    ("pipenv", "Pipfile.lock"),
+    ("pdm", "pdm.lock"),
+)
+
+# tool name -> export command (run with cwd=project_dir, stdout becomes requirements.txt).
+# All emit production dependencies only (dev excluded), with hashes.
+_EXPORT_CMDS: dict[str, list[str]] = {
+    "uv": ["uv", "export", "--frozen", "--no-dev", "--no-emit-project", "--format", "requirements-txt"],
+    "poetry": ["poetry", "export", "-f", "requirements.txt", "--without", "dev"],
+    "pipenv": ["pipenv", "requirements", "--hash"],
+    "pdm": ["pdm", "export", "-f", "requirements", "--prod"],
+}
+
+
+def _auto_detect(project_dir: Path) -> str | None:
+    """Detect the manager from the presence of a lockfile (None if absent)."""
+    for manager, lockfile in _LOCKFILES:
+        if (project_dir / lockfile).is_file():
+            return manager
+    return None
+
+
+def _warn(log, message: str) -> None:
+    log(f"warning: {message}")
+
+
+def resolve_manager(project_dir: Path, override: str | None, *, log=print) -> str:
+    """Determine the manager to use (or "requirements.txt")."""
+    if override:
+        return override
+    detected = _auto_detect(project_dir)
+    if detected:
+        return detected
+    _warn(
+        log,
+        "no lockfile (uv.lock etc.) and no [tool.pyappdist].manager setting. "
+        "Falling back to requirements.txt",
+    )
+    return "requirements.txt"
+
+
+def resolve_requirements(config: Config, wheelhouse: Path, *, log=print) -> Path:
+    """Prepare the pinned dependency list at ``wheelhouse/requirements.txt`` and return its path."""
+    manager = resolve_manager(config.project_dir, config.manager, log=log)
+    out = wheelhouse / "requirements.txt"
+
+    if manager == "requirements.txt":
+        src = config.project_dir / "requirements.txt"
+        if not src.is_file():
+            raise BuildError(
+                f"requirements.txt is missing: {src}"
+                " (provide a manager lockfile or place a requirements.txt)"
+            )
+        log(f"deps: using requirements.txt ({src})")
+        out.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
+        return out
+
+    cmd = _EXPORT_CMDS[manager]
+    log(f"deps: exporting requirements.txt from {manager} lock")
+    proc = subprocess.run(
+        cmd,
+        cwd=str(config.project_dir),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if proc.returncode != 0:
+        raise BuildError(
+            f"requirements.txt export failed ({proc.returncode}): {' '.join(cmd)}\n"
+            f"{proc.stderr.strip()}"
+        )
+    out.write_text(proc.stdout, encoding="utf-8")
+    return out

pyappdist/errors.py

@@ -0,0 +1,15 @@
+"""pyappdist exception hierarchy."""
+
+from __future__ import annotations
+
+
+class PyappdistError(Exception):
+    """Base for all pyappdist exceptions."""
+
+
+class ConfigError(PyappdistError):
+    """A problem in pyproject.toml / [tool.pyappdist]."""
+
+
+class BuildError(PyappdistError):
+    """A failure in a build step (wheel / runtime / image, etc.)."""

pyappdist/image/__init__.py

@@ -0,0 +1,37 @@
+"""Image assembly (Phase 2).
+
+build_image: copy runtime -> install -> compileall -> portable zip.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..context import BuildContext
+from ..runtime import RuntimeInfo
+from .assemble import assemble_runtime, make_portable_zip
+from .compile import compile_site_packages
+from .install import install_app
+from .layout import ImageLayout
+
+__all__ = ["ImageLayout", "build_image", "make_portable_zip"]
+
+
+def build_image(
+    ctx: BuildContext,
+    runtime: RuntimeInfo,
+    *,
+    compile_pyc: bool = True,
+    log=print,
+) -> ImageLayout:
+    """Copy the runtime and assemble an image with install + compileall applied.
+
+    Building launcher.exe and creating the portable zip are the caller's (cli's)
+    responsibility. The zip must be created after the launcher build so it
+    includes the launcher.
+    """
+    layout = assemble_runtime(ctx, runtime, log=log)
+    install_app(layout, ctx.wheelhouse, log=log)
+    if compile_pyc:
+        compile_site_packages(layout, log=log)
+    return layout

pyappdist/image/assemble.py

@@ -0,0 +1,30 @@
+"""Copy the runtime to assemble an image and generate a portable zip."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from ..context import BuildContext
+from ..runtime import RuntimeInfo
+from .layout import ImageLayout
+
+
+def assemble_runtime(ctx: BuildContext, runtime: RuntimeInfo, *, log=print) -> ImageLayout:
+    """Copy the runtime to image/python and return an ImageLayout."""
+    image_dir = ctx.image_dir
+    if image_dir.exists():
+        shutil.rmtree(image_dir)
+    image_dir.mkdir(parents=True)
+    python_dir = image_dir / "python"
+    log(f"image: copying runtime -> {python_dir}")
+    shutil.copytree(runtime.root, python_dir, symlinks=True)
+    return ImageLayout(image_dir=image_dir, target=ctx.config.target, minor=runtime.minor)
+
+
+def make_portable_zip(ctx: BuildContext, *, log=print) -> Path:
+    ctx.dist_dir.mkdir(parents=True, exist_ok=True)
+    base = ctx.dist_dir / f"{ctx.config.dist_name}-{ctx.config.version}-portable"
+    log(f"image: generating portable zip -> {base}.zip")
+    archive = shutil.make_archive(str(base), "zip", root_dir=ctx.image_dir)
+    return Path(archive)

pyappdist/image/compile.py

@@ -0,0 +1,32 @@
+"""Generate .pyc files for the image's site-packages at build time."""
+
+from __future__ import annotations
+
+import subprocess
+
+from .._hostexec import target_path
+from ..errors import BuildError
+from .layout import ImageLayout
+
+
+def compile_site_packages(layout: ImageLayout, *, log=print) -> None:
+    """Run compileall with the runtime's python.
+
+    The target OS's python must be run (for a Linux host -> Windows target,
+    python.exe is run via WSL interop and paths are converted to Windows form).
+    Raises BuildError in environments where it cannot be run.
+    """
+    target = layout.target
+    log("image: compileall")
+    cmd = [
+        str(layout.python_exe), "-m", "compileall", "-q",
+        target_path(target, layout.site_packages),
+    ]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, errors="replace")
+    except OSError as e:
+        raise BuildError(
+            f"cannot run compileall (unable to run {target.name}'s python): {e}"
+        ) from e
+    if proc.returncode != 0:
+        raise BuildError(f"compileall failed ({proc.returncode}):\n{proc.stderr.strip()}")