pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/project/runtime_assets.py

@@ -0,0 +1,183 @@
+"""Embedded CPython runtime acquisition for iOS builds.
+
+iOS apps can't rely on a system Python, so PythonNative bundles a copy of
+CPython built for iOS by the excellent
+[Python-Apple-support](https://github.com/beeware/Python-Apple-support)
+project. This module downloads the pinned release asset for the
+project's ``app.python_version``, verifies its checksum, extracts it
+once (cached under the build directory), and exposes the path to
+``Python.xcframework``.
+
+The xcframework is linked and embedded by the bundled Xcode template at
+build time; its ``build/utils.sh`` helper (shipped inside the framework
+by BeeWare) installs the standard library and converts binary modules
+into signed frameworks during the Xcode build. There is no post-build
+copy step.
+
+Android doesn't need any of this: Chaquopy ships its own CPython via
+Gradle, so there's no Android equivalent here.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import tarfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+# Pinned, checksum-verified Python-Apple-support assets. Every version in
+# ``config.SUPPORTED_PYTHON_VERSIONS`` must have an entry here; iOS builds
+# refuse to run against an unpinned, unverified runtime.
+#
+# Both builds target iOS 13.0 and ship ``ios-arm64`` (device) and
+# ``ios-arm64_x86_64-simulator`` slices, so a single package covers every
+# ``pn run ios`` / ``pn build ios`` destination.
+PINNED_ASSETS = {
+    "3.13": (
+        "3.13-b14",
+        "Python-3.13-iOS-support.b14.tar.gz",
+        "8b5cb76ef8d8a2946052479358eeec9d54b4496cb60920e175ec1489b5cf7963",
+    ),
+    "3.14": (
+        "3.14-b10",
+        "Python-3.14-iOS-support.b10.tar.gz",
+        "200ef60eb67be0483ceb638daa9048f84f41a9a952707a5ad4c3198037c7b583",
+    ),
+}
+
+_DOWNLOAD_URL = "https://github.com/beeware/Python-Apple-support/releases/download/{tag}/{name}"
+_USER_AGENT = "pythonnative-cli"
+
+Logger = Callable[[str], None]
+
+
+@dataclass
+class IOSRuntime:
+    """A resolved, extracted iOS CPython support package.
+
+    Attributes:
+        python_version: The CPython ``major.minor`` version.
+        xcframework_dir: Path to the extracted ``Python.xcframework``.
+    """
+
+    python_version: str
+    xcframework_dir: Path
+
+    @property
+    def install_script(self) -> Path:
+        """Path to BeeWare's ``utils.sh`` build helper inside the framework."""
+        return self.xcframework_dir / "build" / "utils.sh"
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _safe_extract(tar_path: Path, dest: Path) -> None:
+    """Extract a tarball, refusing entries that escape ``dest``."""
+    dest = dest.resolve()
+    with tarfile.open(tar_path, "r:gz") as tar:
+        members = tar.getmembers()
+        for member in members:
+            target = (dest / member.name).resolve()
+            if not str(target).startswith(str(dest)):
+                raise RuntimeError(f"Refusing to extract unsafe path: {member.name}")
+        # ``filter='data'`` (3.12+) blocks unsafe members; older Pythons
+        # fall back to the manual check above.
+        try:
+            tar.extractall(dest, filter="data")
+        except TypeError:
+            tar.extractall(dest)
+
+
+def _locate_runtime(extract_root: Path, python_version: str) -> IOSRuntime:
+    xcframework = extract_root / "Python.xcframework"
+    if not xcframework.is_dir():
+        raise RuntimeError("Python.xcframework not found in extracted Python-Apple-support package.")
+    runtime = IOSRuntime(python_version=python_version, xcframework_dir=xcframework)
+    if not runtime.install_script.is_file():
+        raise RuntimeError(
+            "The extracted Python.xcframework is missing build/utils.sh; the support "
+            "package layout is older than PythonNative expects. Delete the "
+            "build/ios_runtime cache and re-run to fetch the pinned asset."
+        )
+    return runtime
+
+
+def prepare_ios_runtime(
+    cache_dir: Path,
+    python_version: str = "3.13",
+    *,
+    log: Optional[Logger] = None,
+) -> IOSRuntime:
+    """Download (if needed), verify, and extract the iOS CPython package.
+
+    The download and extraction are cached under ``cache_dir`` so repeat
+    builds are fast. Only pinned, checksum-verified versions are
+    accepted; there is no unverified fallback.
+
+    Args:
+        cache_dir: Directory to store downloads and extractions in.
+        python_version: CPython ``major.minor`` to fetch.
+        log: Optional callback for progress messages.
+
+    Returns:
+        A resolved [`IOSRuntime`][pythonnative.project.runtime_assets.IOSRuntime].
+
+    Raises:
+        RuntimeError: If the version has no pinned asset, the download
+            fails, the checksum doesn't match, or the package layout is
+            unexpected.
+    """
+    emit: Logger = log or (lambda _message: None)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    pinned = PINNED_ASSETS.get(python_version)
+    if pinned is None:
+        supported = ", ".join(sorted(PINNED_ASSETS))
+        raise RuntimeError(
+            f"No pinned iOS runtime for Python {python_version}. Set app.python_version to one of: {supported}."
+        )
+    tag, asset_name, expected_sha = pinned
+
+    extract_root = cache_dir / f"python-{python_version}"
+    if extract_root.is_dir():
+        try:
+            return _locate_runtime(extract_root, python_version)
+        except RuntimeError:
+            # Stale/partial extraction: re-extract below.
+            pass
+
+    url = _DOWNLOAD_URL.format(tag=tag, name=asset_name)
+    tar_path = cache_dir / asset_name
+    if not tar_path.exists() or _sha256(tar_path) != expected_sha:
+        emit(f"Downloading embedded Python runtime ({python_version} iOS): {asset_name}")
+        req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+        try:
+            with urllib.request.urlopen(req) as response, open(tar_path, "wb") as handle:
+                handle.write(response.read())
+        except OSError as exc:
+            tar_path.unlink(missing_ok=True)
+            raise RuntimeError(
+                f"Could not download the iOS Python runtime from {url}: {exc}. "
+                "Check your network connection and re-run."
+            ) from exc
+
+    actual = _sha256(tar_path)
+    if actual != expected_sha:
+        tar_path.unlink(missing_ok=True)
+        raise RuntimeError(
+            f"Checksum mismatch for {asset_name}: expected {expected_sha}, got {actual}. "
+            "The download may be corrupt; re-run to try again."
+        )
+
+    emit("Extracting embedded Python runtime...")
+    extract_root.mkdir(parents=True, exist_ok=True)
+    _safe_extract(tar_path, extract_root)
+    return _locate_runtime(extract_root, python_version)

pythonnative/query.py

@@ -0,0 +1,153 @@
+"""Shared async query cache with deduplication and explicit invalidation."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Hashable
+
+from .runtime import TaskScope
+
+
+@dataclass(frozen=True)
+class QuerySnapshot:
+    """Immutable state shared by every subscriber to a query key."""
+
+    data: Any = None
+    loading: bool = False
+    error: BaseException | None = None
+    revision: int = 0
+
+
+class _Entry:
+    def __init__(self, initial: Any) -> None:
+        self.snapshot = QuerySnapshot(data=initial, loading=True)
+        self.listeners: set[Callable[[], None]] = set()
+        self.fetcher: Callable[[], Awaitable[Any]] | None = None
+        self.task: Any = None
+        self.expires = 0.0
+        self.generation = 0
+
+    def publish(self, *, data: Any, loading: bool, error: BaseException | None = None) -> None:
+        self.snapshot = QuerySnapshot(data, loading, error, self.snapshot.revision + 1)
+        for listener in tuple(self.listeners):
+            listener()
+
+
+class QueryClient:
+    """Own shared requests and cached immutable results for one application.
+
+    A final unsubscribe cancels pending work. Cached values remain bounded by
+    capacity. Invalidation cancels older requests before starting replacements.
+    """
+
+    def __init__(self, *, capacity: int = 128, stale_time: float = 30) -> None:
+        if capacity < 1 or stale_time < 0:
+            raise ValueError("Invalid query cache limits")
+        self.capacity = capacity
+        self.stale_time = stale_time
+        self._entries: OrderedDict[Hashable, _Entry] = OrderedDict()
+        self._scope = TaskScope("queries")
+
+    def _entry(self, key: Hashable, initial: Any = None) -> _Entry:
+        hash(key)
+        if key not in self._entries:
+            self._entries[key] = _Entry(initial)
+        self._entries.move_to_end(key)
+        for old_key, old in tuple(self._entries.items()):
+            if len(self._entries) <= self.capacity:
+                break
+            if old_key != key and not old.listeners and (old.task is None or old.task.done()):
+                del self._entries[old_key]
+        return self._entries[key]
+
+    def snapshot(self, key: Hashable, initial: Any = None) -> QuerySnapshot:
+        """Read a stable snapshot without starting network work."""
+        return self._entry(key, initial).snapshot
+
+    def subscribe(
+        self, key: Hashable, fetcher: Callable[[], Awaitable[Any]], listener: Callable[[], None]
+    ) -> Callable[[], None]:
+        """Subscribe and start one shared request when cached data is stale."""
+        entry = self._entry(key)
+        entry.fetcher = fetcher
+        entry.listeners.add(listener)
+        if entry.expires <= time.monotonic():
+            self._fetch(entry)
+
+        def remove() -> None:
+            entry.listeners.discard(listener)
+            if not entry.listeners and entry.task is not None and not entry.task.done():
+                entry.generation += 1
+                entry.task.cancel()
+                entry.task = None
+                entry.publish(data=entry.snapshot.data, loading=False)
+
+        return remove
+
+    def _fetch(self, entry: _Entry) -> None:
+        if entry.fetcher is None or entry.task is not None and not entry.task.done():
+            return
+        generation = entry.generation
+        fetcher = entry.fetcher
+        entry.publish(data=entry.snapshot.data, loading=True)
+
+        async def run() -> None:
+            try:
+                result = await fetcher()
+                if generation == entry.generation:
+                    entry.expires = time.monotonic() + self.stale_time
+                    entry.publish(data=result, loading=False)
+            except asyncio.CancelledError:
+                raise
+            except Exception as error:
+                if generation == entry.generation:
+                    entry.publish(data=entry.snapshot.data, loading=False, error=error)
+
+        entry.task = self._scope.create_task(run())
+
+    def invalidate(self, key: Hashable | None = None) -> None:
+        """Invalidate one key or every query and refresh active subscribers."""
+        for entry in [self._entry(key)] if key is not None else list(self._entries.values()):
+            entry.generation += 1
+            entry.expires = 0
+            if entry.task is not None:
+                entry.task.cancel()
+                entry.task = None
+            if entry.listeners:
+                self._fetch(entry)
+
+    def set_data(self, key: Hashable, value: Any) -> None:
+        """Publish an immutable optimistic result and supersede older requests."""
+        entry = self._entry(key)
+        entry.generation += 1
+        if entry.task is not None:
+            entry.task.cancel()
+            entry.task = None
+        entry.expires = time.monotonic() + self.stale_time
+        entry.publish(data=value, loading=False)
+
+    def close(self) -> None:
+        """Cancel shared tasks and release all cached data and listeners."""
+        self._scope.close()
+        self._entries.clear()
+
+
+_default: QueryClient | None = None
+
+
+def default_client() -> QueryClient:
+    """Return the application's default query cache."""
+    global _default
+    if _default is None or _default._scope.closed:
+        _default = QueryClient()
+    return _default
+
+
+def _reset_for_tests() -> None:
+    global _default
+    if _default is not None:
+        _default.close()
+    _default = None

pythonnative/reconciler/__init__.py

@@ -0,0 +1,29 @@
+"""Reconciler package: turns element trees into batched native mutations.
+
+The public surface is [`Reconciler`][pythonnative.reconciler.core.Reconciler] and
+[`VNode`][pythonnative.reconciler.vnode.VNode]; the remaining modules are
+implementation detail:
+
+- ``core``: render, diff, commit.
+- ``boundaries``: ``ErrorBoundary``
+  and ``Suspense``.
+- ``layout_pass``: the flexbox
+  pass and frame diffing.
+- ``children``: minimal move
+  planning for keyed child lists.
+- ``vnode``: the mounted-tree node and
+  pure helpers.
+"""
+
+from .children import plan_child_moves
+from .core import Reconciler
+from .vnode import VNode, next_tag, normalize_children, shallow_equal_props
+
+__all__ = [
+    "Reconciler",
+    "VNode",
+    "next_tag",
+    "normalize_children",
+    "plan_child_moves",
+    "shallow_equal_props",
+]