pythonnative 0.20.0__py3-none-any.whl → 0.22.0__py3-none-any.whl

pythonnative/project/doctor.py

@@ -0,0 +1,233 @@
+"""Environment diagnostics for ``pn doctor``.
+
+Inspects the local toolchain and the project's ``pythonnative.toml`` and
+reports what's ready and what's missing for building on each platform —
+analogous to ``flutter doctor`` / ``npx react-native doctor``. The checks
+are deliberately read-only and fast; they shell out only to ask tools for
+their versions.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from . import icons
+from .config import IOS_SUPPORTED_PYTHON_VERSION, SUPPORTED_PYTHON_VERSIONS, AppConfig, ConfigError
+
+OK = "ok"
+WARN = "warn"
+ERROR = "error"
+INFO = "info"
+
+_SYMBOLS = {OK: "[ok]", WARN: "[!]", ERROR: "[x]", INFO: "[i]"}
+
+
+@dataclass
+class CheckResult:
+    """The outcome of a single diagnostic check.
+
+    Attributes:
+        name: Short label for the thing checked.
+        level: One of ``"ok"``, ``"warn"``, ``"error"``, ``"info"``.
+        detail: Human-readable detail / remediation hint.
+    """
+
+    name: str
+    level: str
+    detail: str = ""
+
+    def format(self) -> str:
+        """Return a single aligned line for terminal output."""
+        symbol = _SYMBOLS.get(self.level, "[?]")
+        suffix = f" — {self.detail}" if self.detail else ""
+        return f"  {symbol} {self.name}{suffix}"
+
+
+def _which_version(tool: str, version_args: List[str]) -> Optional[str]:
+    path = shutil.which(tool)
+    if not path:
+        return None
+    try:
+        out = subprocess.run([tool, *version_args], capture_output=True, text=True, timeout=20)
+    except Exception:
+        return path
+    text = (out.stdout or out.stderr or "").strip().splitlines()
+    return text[0] if text else path
+
+
+def check_common() -> List[CheckResult]:
+    """Run platform-agnostic checks (interpreter, Pillow).
+
+    Returns:
+        Check results for the host Python and optional dependencies.
+    """
+    results: List[CheckResult] = []
+    py_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    if py_version in SUPPORTED_PYTHON_VERSIONS:
+        results.append(CheckResult("Host Python", OK, f"{sys.version.split()[0]}"))
+    else:
+        results.append(
+            CheckResult(
+                "Host Python",
+                WARN,
+                f"{py_version} (PythonNative targets {', '.join(SUPPORTED_PYTHON_VERSIONS)})",
+            )
+        )
+    if icons.pillow_available():
+        results.append(CheckResult("Pillow (icon/splash generation)", OK))
+    else:
+        results.append(
+            CheckResult(
+                "Pillow (icon/splash generation)",
+                WARN,
+                "not installed; run: pip install 'pythonnative[build]'",
+            )
+        )
+    return results
+
+
+def check_android(config: Optional[AppConfig]) -> List[CheckResult]:
+    """Run Android toolchain and signing checks.
+
+    Args:
+        config: The loaded app config, or ``None`` if unavailable.
+
+    Returns:
+        Android-specific check results.
+    """
+    results: List[CheckResult] = []
+    adb = _which_version("adb", ["--version"])
+    results.append(CheckResult("adb (Android platform-tools)", OK if adb else WARN, adb or "not found on PATH"))
+
+    java_home = shutil.which("java")
+    import os
+
+    if os.environ.get("JAVA_HOME") or java_home:
+        results.append(CheckResult("Java (JDK 17 recommended)", OK, os.environ.get("JAVA_HOME") or java_home or ""))
+    else:
+        results.append(CheckResult("Java (JDK 17 recommended)", WARN, "JAVA_HOME not set and 'java' not on PATH"))
+
+    if config is not None:
+        signing = config.android.signing
+        if signing.is_configured:
+            keystore = config.resolve_path(signing.keystore) if signing.keystore else None
+            if keystore and keystore.is_file():
+                results.append(CheckResult("Android release keystore", OK, str(keystore)))
+            else:
+                results.append(CheckResult("Android release keystore", ERROR, f"not found: {keystore}"))
+            missing = [env for env in (signing.store_password_env, signing.key_password_env) if not os.environ.get(env)]
+            if missing:
+                results.append(CheckResult("Android signing passwords", WARN, f"unset env: {', '.join(missing)}"))
+        else:
+            results.append(
+                CheckResult(
+                    "Android release signing",
+                    INFO,
+                    "not configured; release builds will be unsigned (set [android.signing])",
+                )
+            )
+    return results
+
+
+def check_ios(config: Optional[AppConfig]) -> List[CheckResult]:
+    """Run iOS toolchain and signing checks.
+
+    Args:
+        config: The loaded app config, or ``None`` if unavailable.
+
+    Returns:
+        iOS-specific check results.
+    """
+    results: List[CheckResult] = []
+    if sys.platform != "darwin":
+        results.append(CheckResult("macOS (required for iOS)", ERROR, f"this is {sys.platform}; iOS builds need macOS"))
+        return results
+
+    xcodebuild = _which_version("xcodebuild", ["-version"])
+    results.append(CheckResult("Xcode (xcodebuild)", OK if xcodebuild else ERROR, xcodebuild or "not found on PATH"))
+    simctl = shutil.which("xcrun")
+    results.append(CheckResult("xcrun simctl (Simulators)", OK if simctl else WARN, simctl or "not found on PATH"))
+
+    if config is not None:
+        if config.python_version != IOS_SUPPORTED_PYTHON_VERSION:
+            results.append(
+                CheckResult(
+                    "iOS embedded Python",
+                    WARN,
+                    f"app.python_version={config.python_version}; only "
+                    f"{IOS_SUPPORTED_PYTHON_VERSION} has a pinned iOS build",
+                )
+            )
+        if config.ios.development_team:
+            results.append(CheckResult("iOS development team", OK, config.ios.development_team))
+        else:
+            results.append(
+                CheckResult(
+                    "iOS development team",
+                    INFO,
+                    "not set; required for device builds (set [ios].development_team)",
+                )
+            )
+    return results
+
+
+def check_config(project_root: Path) -> tuple[Optional[AppConfig], List[CheckResult]]:
+    """Load and validate the project config, returning it with a result.
+
+    Args:
+        project_root: Directory expected to contain ``pythonnative.toml``.
+
+    Returns:
+        A tuple of the loaded config (or ``None``) and the check results.
+    """
+    results: List[CheckResult] = []
+    try:
+        config = AppConfig.load(project_root)
+    except ConfigError as exc:
+        results.append(CheckResult("pythonnative.toml", ERROR, str(exc).splitlines()[0]))
+        return None, results
+    results.append(CheckResult("pythonnative.toml", OK, f"{config.app_id} (v{config.version})"))
+    return config, results
+
+
+def run_doctor(project_root: Path, *, platform: Optional[str] = None) -> List[CheckResult]:
+    """Run all diagnostics for ``project_root``.
+
+    Args:
+        project_root: The project directory.
+        platform: Restrict checks to ``"android"`` or ``"ios"``; ``None``
+            checks both.
+
+    Returns:
+        All check results in display order.
+    """
+    config, results = check_config(project_root)
+    results.extend(check_common())
+    if platform in (None, "android"):
+        results.extend(check_android(config))
+    if platform in (None, "ios"):
+        results.extend(check_ios(config))
+    return results
+
+
+def worst_level(results: List[CheckResult]) -> str:
+    """Return the most severe level among ``results``.
+
+    Args:
+        results: The diagnostic results.
+
+    Returns:
+        ``"error"`` if any error, else ``"warn"`` if any warning, else
+        ``"ok"``.
+    """
+    levels = {result.level for result in results}
+    if ERROR in levels:
+        return ERROR
+    if WARN in levels:
+        return WARN
+    return OK

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))