pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/project/fingerprint.py

@@ -0,0 +1,171 @@
+"""Native build fingerprints: know when ``pn run`` can skip the toolchain.
+
+A debug build only has to be rebuilt when one of its *native inputs*
+changes: ``pythonnative.toml``, the bundled native template, the
+``pythonnative`` package itself, project-local native plugins, or the
+build flavor (platform, SDK, release). Edits under ``app/`` don't count;
+the dev server syncs those into the running app and Fast Refresh applies
+them, exactly as Metro does for a React Native debug build.
+
+[`compute`][pythonnative.project.fingerprint.compute] hashes those
+inputs into one hex digest. ``pn run`` writes it next to the build
+after a successful toolchain run (see
+[`write_stamp`][pythonnative.project.fingerprint.write_stamp]) and, when
+the digest is unchanged and a dev server is running to deliver the
+latest sources, reinstalls the previous artifact instead of staging and
+compiling again.
+
+The hash covers file *contents*, not mtimes, so touching a file or
+re-cloning the repository doesn't invalidate a build.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Dict, Iterable, Optional, Sequence
+
+from .config import CONFIG_FILENAME, AppConfig
+
+__all__ = ["STAMP_NAME", "compute", "hash_tree", "read_stamp", "write_stamp"]
+
+STAMP_NAME = ".pn-native-fingerprint.json"
+"""File written into ``build/<platform>/`` after a successful native build."""
+
+_IGNORED_DIRS = {
+    "__pycache__",
+    ".git",
+    ".gradle",
+    ".build",
+    ".swiftpm",
+    "build",
+    "DerivedData",
+    "xcuserdata",
+    "node_modules",
+    ".venv",
+}
+_IGNORED_SUFFIXES = (".pyc", ".pyo", ".DS_Store")
+
+
+def hash_tree(root: Path, *, into: Optional["hashlib._Hash"] = None) -> str:
+    """Hash every file under ``root`` (relative path + contents), deterministically.
+
+    Build outputs, caches, and bytecode are skipped so a checkout that
+    has been built hashes the same as a fresh one.
+
+    Args:
+        root: Directory (or single file) to hash. A missing path hashes
+            as the empty tree.
+        into: An existing hasher to feed instead of creating one.
+
+    Returns:
+        The hex digest (of ``into`` when given).
+    """
+    hasher = into or hashlib.sha256()
+    if root.is_file():
+        _feed_file(hasher, root.name, root)
+        return hasher.hexdigest()
+    if not root.is_dir():
+        return hasher.hexdigest()
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in _IGNORED_DIRS and not d.startswith("."))
+        for name in sorted(filenames):
+            if name.endswith(_IGNORED_SUFFIXES):
+                continue
+            path = Path(dirpath) / name
+            if path.is_symlink() and not path.exists():
+                continue
+            _feed_file(hasher, str(path.relative_to(root)).replace(os.sep, "/"), path)
+    return hasher.hexdigest()
+
+
+def _feed_file(hasher: "hashlib._Hash", rel: str, path: Path) -> None:
+    hasher.update(rel.encode("utf-8"))
+    hasher.update(b"\0")
+    try:
+        with open(path, "rb") as handle:
+            for chunk in iter(lambda: handle.read(1 << 16), b""):
+                hasher.update(chunk)
+    except OSError:
+        hasher.update(b"<unreadable>")
+    hasher.update(b"\0")
+
+
+def compute(
+    config: AppConfig,
+    platform: str,
+    *,
+    template_root: Path,
+    lib_root: Path,
+    release: bool = False,
+    ios_sdks: Sequence[str] = (),
+    extra: Optional[Dict[str, str]] = None,
+) -> str:
+    """Digest every native input of a build.
+
+    Args:
+        config: The loaded project configuration (its file is hashed).
+        platform: ``"android"`` or ``"ios"``.
+        template_root: The bundled native template directory.
+        lib_root: The ``pythonnative`` package directory that gets bundled.
+        release: Release builds are distinct from debug builds.
+        ios_sdks: The iOS SDK slices being staged.
+        extra: Additional key/value inputs (host arch, tool versions).
+
+    Returns:
+        A hex SHA-256 digest.
+    """
+    hasher = hashlib.sha256()
+    header = {
+        "platform": platform,
+        "release": bool(release),
+        "ios_sdks": sorted(ios_sdks),
+        "python": f"{sys.version_info[0]}.{sys.version_info[1]}",
+        "extra": dict(sorted((extra or {}).items())),
+    }
+    hasher.update(json.dumps(header, sort_keys=True).encode("utf-8"))
+    hasher.update(b"\0config\0")
+    hash_tree(config.project_root / CONFIG_FILENAME, into=hasher)
+    hasher.update(b"\0template\0")
+    hash_tree(template_root, into=hasher)
+    hasher.update(b"\0lib\0")
+    hash_tree(lib_root, into=hasher)
+    hash_tree(config.project_root / "pn.lock", into=hasher)
+    for plugin_path in _plugin_paths(config):
+        hasher.update(b"\0plugin:" + str(plugin_path).encode("utf-8") + b"\0")
+        hash_tree(plugin_path, into=hasher)
+    return hasher.hexdigest()
+
+
+def _plugin_paths(config: AppConfig) -> Iterable[Path]:
+    for raw in getattr(config, "plugin_paths", ()) or ():
+        try:
+            yield config.resolve_path(raw)
+        except Exception:
+            continue
+
+
+def read_stamp(build_dir: Path) -> Optional[Dict[str, str]]:
+    """Return the stamp written by the last successful build, or ``None``."""
+    path = build_dir / STAMP_NAME
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (OSError, ValueError):
+        return None
+    if not isinstance(data, dict) or "fingerprint" not in data:
+        return None
+    return {str(k): str(v) for k, v in data.items()}
+
+
+def write_stamp(build_dir: Path, fingerprint: str, *, artifact: Optional[Path] = None) -> None:
+    """Record ``fingerprint`` (and the artifact it produced) for the next ``pn run``."""
+    build_dir.mkdir(parents=True, exist_ok=True)
+    payload: Dict[str, str] = {"fingerprint": fingerprint}
+    if artifact is not None:
+        payload["artifact"] = str(artifact)
+    with open(build_dir / STAMP_NAME, "w", encoding="utf-8") as handle:
+        json.dump(payload, handle, indent=2)

pythonnative/project/icons.py

@@ -0,0 +1,247 @@
+"""App icon and splash image generation.
+
+Given a single high-resolution source image per asset (a 1024x1024 icon
+and an optional splash image), this module renders the per-platform,
+per-density variants each toolchain expects:
+
+- iOS: a single-size ``AppIcon.appiconset`` (Xcode resizes at build time)
+  and a ``Splash`` image set referenced by the generated launch screen.
+- Android: ``mipmap-*`` launcher PNGs at every density (mdpi…xxxhdpi),
+  a circular round-icon variant, and a centered splash icon used by the
+  Android 12+ splash screen.
+
+Image resizing uses [Pillow](https://python-pillow.org/), declared as the
+``[build]`` optional dependency. When Pillow isn't installed every
+function degrades gracefully: it returns ``False`` (and the caller keeps
+the template's default assets) so a missing optional dependency never
+breaks a build. ``pn doctor`` reports whether Pillow is available.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+# Android launcher icon sizes (px) per density bucket.
+ANDROID_LAUNCHER_DENSITIES: Dict[str, int] = {
+    "mdpi": 48,
+    "hdpi": 72,
+    "xhdpi": 96,
+    "xxhdpi": 144,
+    "xxxhdpi": 192,
+}
+
+
+def pillow_available() -> bool:
+    """Return whether Pillow can be imported.
+
+    Returns:
+        ``True`` if ``PIL.Image`` imports, else ``False``.
+    """
+    try:
+        import PIL.Image  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def _open_rgba(source: Path) -> "object":
+    from PIL import Image
+
+    img = Image.open(source).convert("RGBA")
+    return img
+
+
+def _resized(img: "object", size: int) -> "object":
+    from PIL import Image
+
+    return img.resize((size, size), Image.LANCZOS)
+
+
+def _circular(img: "object") -> "object":
+    """Return a copy of a square image masked to a circle."""
+    from PIL import Image, ImageDraw
+
+    size = img.size[0]
+    mask = Image.new("L", (size, size), 0)
+    draw = ImageDraw.Draw(mask)
+    draw.ellipse((0, 0, size, size), fill=255)
+    out = Image.new("RGBA", (size, size), (0, 0, 0, 0))
+    out.paste(img, (0, 0), mask)  # type: ignore[arg-type]
+    return out
+
+
+def generate_ios_icons(source: Path, appiconset_dir: Path) -> bool:
+    """Generate a single-size iOS ``AppIcon.appiconset``.
+
+    Writes ``icon-1024.png`` (a flattened, opaque 1024x1024 image; the
+    App Store rejects icons with alpha) and a ``Contents.json`` that
+    declares it as the universal iOS app icon. Xcode derives every other
+    size at build time.
+
+    Args:
+        source: Path to the source icon image.
+        appiconset_dir: The ``AppIcon.appiconset`` directory to populate.
+
+    Returns:
+        ``True`` if icons were written, ``False`` if Pillow is missing.
+    """
+    if not pillow_available():
+        return False
+    from PIL import Image
+
+    appiconset_dir.mkdir(parents=True, exist_ok=True)
+    img = _open_rgba(source)
+    icon = _resized(img, 1024)
+    flattened = Image.new("RGB", (1024, 1024), (255, 255, 255))
+    flattened.paste(icon, (0, 0), icon)  # type: ignore[arg-type]
+    flattened.save(appiconset_dir / "icon-1024.png", format="PNG")
+
+    contents = {
+        "images": [
+            {
+                "idiom": "universal",
+                "platform": "ios",
+                "size": "1024x1024",
+                "filename": "icon-1024.png",
+            }
+        ],
+        "info": {"author": "pythonnative", "version": 1},
+    }
+    (appiconset_dir / "Contents.json").write_text(json.dumps(contents, indent=2) + "\n", encoding="utf-8")
+    return True
+
+
+def generate_android_icons(source: Path, res_dir: Path) -> bool:
+    """Generate Android launcher icons at every density.
+
+    Writes ``mipmap-<density>/ic_launcher.png`` and a circular
+    ``ic_launcher_round.png`` for each density bucket, and removes the
+    adaptive ``mipmap-anydpi-v26`` definitions so the generated PNGs are
+    used directly (otherwise the template's vector adaptive icon would
+    win on API 26+).
+
+    Args:
+        source: Path to the source icon image.
+        res_dir: The Android ``res`` directory.
+
+    Returns:
+        ``True`` if icons were written, ``False`` if Pillow is missing.
+    """
+    if not pillow_available():
+        return False
+
+    img = _open_rgba(source)
+    for density, size in ANDROID_LAUNCHER_DENSITIES.items():
+        mip_dir = res_dir / f"mipmap-{density}"
+        mip_dir.mkdir(parents=True, exist_ok=True)
+        square = _resized(img, size)
+        square.save(mip_dir / "ic_launcher.png", format="PNG")
+        round_icon = _circular(square)
+        round_icon.save(mip_dir / "ic_launcher_round.png", format="PNG")
+
+    # Drop adaptive XML icons so the raster mipmaps above are authoritative.
+    anydpi = res_dir / "mipmap-anydpi-v26"
+    if anydpi.is_dir():
+        shutil.rmtree(anydpi, ignore_errors=True)
+    return True
+
+
+def generate_ios_splash(source: Path, imageset_dir: Path) -> bool:
+    """Generate an iOS ``Splash`` image set from a source image.
+
+    Args:
+        source: Path to the splash image.
+        imageset_dir: The ``Splash.imageset`` directory to populate.
+
+    Returns:
+        ``True`` if the image set was written, ``False`` if Pillow is
+        missing.
+    """
+    if not pillow_available():
+        return False
+
+    imageset_dir.mkdir(parents=True, exist_ok=True)
+    img = _open_rgba(source)
+    img.save(imageset_dir / "splash.png", format="PNG")
+    contents = {
+        "images": [{"idiom": "universal", "filename": "splash.png"}],
+        "info": {"author": "pythonnative", "version": 1},
+    }
+    (imageset_dir / "Contents.json").write_text(json.dumps(contents, indent=2) + "\n", encoding="utf-8")
+    return True
+
+
+def generate_android_splash_icon(source: Path, dest: Path, size: int = 288) -> bool:
+    """Render the centered icon used by the Android 12+ splash screen.
+
+    The Android splash screen draws this image centered on the splash
+    background color. A transparent square is recommended; the default
+    size (288 dp at xxxhdpi → ~864 px) matches Google's guidance.
+
+    Args:
+        source: Path to the source splash (or icon) image.
+        dest: Destination PNG path.
+        size: Output edge length in pixels.
+
+    Returns:
+        ``True`` if the image was written, ``False`` if Pillow is missing.
+    """
+    if not pillow_available():
+        return False
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    img = _open_rgba(source)
+    _resized(img, size).save(dest, format="PNG")
+    return True
+
+
+def dominant_background_color(source: Path) -> Optional[str]:
+    """Best-effort estimate of a splash background color from an image.
+
+    Samples the image's corner pixels and returns the most common one as
+    a ``#RRGGBB`` hex string. Used as a default splash background when the
+    config doesn't specify one.
+
+    Args:
+        source: Path to the splash image.
+
+    Returns:
+        A hex color string, or ``None`` if Pillow is missing or the
+        sampling fails.
+    """
+    if not pillow_available():
+        return None
+    try:
+        img = _open_rgba(source)
+        width, height = img.size
+        corners: List[Tuple[int, int]] = [
+            (0, 0),
+            (width - 1, 0),
+            (0, height - 1),
+            (width - 1, height - 1),
+        ]
+        counts: Dict[Tuple[int, int, int], int] = {}
+        for x, y in corners:
+            r, g, b, _a = img.getpixel((x, y))
+            key = (r, g, b)
+            counts[key] = counts.get(key, 0) + 1
+        r, g, b = max(counts, key=lambda k: counts[k])
+        return f"#{r:02X}{g:02X}{b:02X}"
+    except Exception:
+        return None
+
+
+def has_source(path: Optional[Path]) -> bool:
+    """Return whether ``path`` is a readable existing file.
+
+    Args:
+        path: A candidate asset path, or ``None``.
+
+    Returns:
+        ``True`` when the path is a file that exists on disk.
+    """
+    return bool(path and os.path.isfile(path))