pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/devserver/watcher.py

@@ -0,0 +1,267 @@
+"""Source snapshots and change detection for the dev server.
+
+The dev server treats the project's ``app/`` directory as a content-
+addressed tree: every dev client gets the same manifest (relative path
+to SHA-256), so a client can tell exactly which files it is missing
+after a reconnect, and a change notification can carry the new bytes.
+
+[`FileWatcher`][pythonnative.devserver.watcher.FileWatcher] polls the
+tree with ``os.stat`` rather than a native file-system event API so it
+behaves identically on every host OS without a dependency; the poll
+interval is short enough that saves feel instant.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Sequence, Set, Tuple
+
+__all__ = ["FileWatcher", "SourceSnapshot", "SourceChange", "is_synced_file", "snapshot_sources"]
+
+MAX_SYNC_FILE_BYTES = 8 * 1024 * 1024
+"""Files larger than this are left out of the sync set (they belong in a real build)."""
+
+_IGNORED_DIRS = {"__pycache__", ".git", ".hg", ".svn", ".mypy_cache", ".pytest_cache", ".ruff_cache", "node_modules"}
+_IGNORED_SUFFIXES = (".pyc", ".pyo", ".swp", ".swo", ".tmp", "~")
+_IGNORED_NAMES = {".DS_Store", "Thumbs.db"}
+
+
+def is_synced_file(rel_path: str) -> bool:
+    """Whether a file under ``app/`` takes part in dev sync.
+
+    Editor swap files, byte-code caches, and VCS metadata are skipped;
+    everything else (Python modules and data files an app reads at
+    runtime) is synced so the on-device overlay mirrors the source tree.
+    """
+    parts = rel_path.replace("\\", "/").split("/")
+    if any(part in _IGNORED_DIRS for part in parts[:-1]):
+        return False
+    name = parts[-1]
+    if not name or name in _IGNORED_NAMES:
+        return False
+    if name.startswith(".#"):
+        return False
+    return not name.endswith(_IGNORED_SUFFIXES)
+
+
+@dataclass(frozen=True)
+class SourceSnapshot:
+    """The state of a source tree at one instant.
+
+    Attributes:
+        root: Absolute directory the relative paths are resolved against
+            (the project root; paths start with ``app/``).
+        files: ``relative_path -> sha256`` for every synced file.
+        mtimes: ``relative_path -> (mtime_ns, size)`` used to skip
+            re-hashing unchanged files between polls.
+        version: A digest of the whole tree, stable across processes
+            for identical contents.
+    """
+
+    root: str
+    files: Dict[str, str] = field(default_factory=dict)
+    mtimes: Dict[str, Tuple[int, int]] = field(default_factory=dict)
+    version: str = ""
+
+    def read(self, rel_path: str) -> Optional[bytes]:
+        """Return the current bytes of ``rel_path`` (``None`` if it is gone)."""
+        try:
+            with open(os.path.join(self.root, rel_path), "rb") as handle:
+                return handle.read()
+        except OSError:
+            return None
+
+    def diff(self, other: "SourceSnapshot") -> "SourceChange":
+        """Describe how to get from ``self`` to ``other``."""
+        changed = sorted(path for path, digest in other.files.items() if self.files.get(path) != digest)
+        removed = sorted(path for path in self.files if path not in other.files)
+        return SourceChange(changed=changed, removed=removed, version=other.version)
+
+
+@dataclass(frozen=True)
+class SourceChange:
+    """Paths that changed (added or modified) and paths that disappeared."""
+
+    changed: List[str]
+    removed: List[str]
+    version: str
+
+    def __bool__(self) -> bool:
+        return bool(self.changed or self.removed)
+
+
+def _tree_version(files: Dict[str, str]) -> str:
+    digest = hashlib.sha256()
+    for path in sorted(files):
+        digest.update(path.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(files[path].encode("ascii"))
+        digest.update(b"\n")
+    return digest.hexdigest()[:16]
+
+
+def snapshot_sources(
+    root: str,
+    subdirs: Sequence[str] = ("app",),
+    *,
+    previous: Optional[SourceSnapshot] = None,
+) -> SourceSnapshot:
+    """Hash every synced file under ``root/<subdir>`` for each of ``subdirs``.
+
+    Args:
+        root: Project root.
+        subdirs: Directories (relative to ``root``) to include.
+        previous: An earlier snapshot; files whose ``(mtime, size)`` are
+            unchanged reuse their digest instead of being re-read.
+    """
+    files: Dict[str, str] = {}
+    mtimes: Dict[str, Tuple[int, int]] = {}
+    prev_mtimes = previous.mtimes if previous is not None else {}
+    prev_files = previous.files if previous is not None else {}
+    for subdir in subdirs:
+        base = os.path.join(root, subdir)
+        if not os.path.isdir(base):
+            continue
+        for dirpath, dirnames, filenames in os.walk(base):
+            dirnames[:] = sorted(d for d in dirnames if d not in _IGNORED_DIRS)
+            for name in sorted(filenames):
+                full = os.path.join(dirpath, name)
+                rel = os.path.relpath(full, root).replace(os.sep, "/")
+                if not is_synced_file(rel):
+                    continue
+                try:
+                    stat = os.stat(full)
+                except OSError:
+                    continue
+                if stat.st_size > MAX_SYNC_FILE_BYTES:
+                    continue
+                key = (stat.st_mtime_ns, stat.st_size)
+                if prev_mtimes.get(rel) == key and rel in prev_files:
+                    files[rel] = prev_files[rel]
+                    mtimes[rel] = key
+                    continue
+                try:
+                    with open(full, "rb") as handle:
+                        data = handle.read()
+                except OSError:
+                    continue
+                files[rel] = hashlib.sha256(data).hexdigest()
+                mtimes[rel] = key
+    return SourceSnapshot(root=os.path.abspath(root), files=files, mtimes=mtimes, version=_tree_version(files))
+
+
+class FileWatcher:
+    """Poll a source tree and report changes on a background thread.
+
+    Args:
+        root: Project root.
+        on_change: Called with a
+            [`SourceChange`][pythonnative.devserver.watcher.SourceChange]
+            and the new snapshot after every poll that found changes.
+        subdirs: Directories under ``root`` to watch.
+        interval: Seconds between polls.
+        settle: Seconds a change must be stable before it is reported,
+            so an editor's write-then-rename or a multi-file save lands
+            as one reload instead of several.
+    """
+
+    def __init__(
+        self,
+        root: str,
+        on_change: Callable[[SourceChange, SourceSnapshot], None],
+        *,
+        subdirs: Sequence[str] = ("app",),
+        interval: float = 0.25,
+        settle: float = 0.08,
+    ) -> None:
+        self.root = os.path.abspath(root)
+        self.on_change = on_change
+        self.subdirs = tuple(subdirs)
+        self.interval = interval
+        self.settle = settle
+        self._snapshot = snapshot_sources(self.root, self.subdirs)
+        self._thread: Optional[threading.Thread] = None
+        self._stop = threading.Event()
+        self._lock = threading.Lock()
+
+    @property
+    def snapshot(self) -> SourceSnapshot:
+        """The most recent snapshot."""
+        with self._lock:
+            return self._snapshot
+
+    def start(self) -> None:
+        """Start polling on a daemon thread (idempotent)."""
+        if self._thread is not None:
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._loop, name="pn-file-watcher", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop polling and join the thread."""
+        self._stop.set()
+        thread, self._thread = self._thread, None
+        if thread is not None:
+            thread.join(timeout=max(1.0, self.interval * 4))
+
+    def poll(self) -> Optional[SourceChange]:
+        """Scan once and return the change since the last scan (or ``None``)."""
+        with self._lock:
+            previous = self._snapshot
+        current = snapshot_sources(self.root, self.subdirs, previous=previous)
+        change = previous.diff(current)
+        if not change:
+            return None
+        if self.settle > 0:
+            # Wait for the tree to stop changing so partial writes never ship.
+            deadline = time.monotonic() + max(self.settle * 20, 2.0)
+            while time.monotonic() < deadline:
+                time.sleep(self.settle)
+                settled = snapshot_sources(self.root, self.subdirs, previous=current)
+                if settled.version == current.version:
+                    break
+                current = settled
+            change = previous.diff(current)
+            if not change:
+                return None
+        with self._lock:
+            self._snapshot = current
+        return change
+
+    def _loop(self) -> None:
+        while not self._stop.wait(self.interval):
+            try:
+                change = self.poll()
+            except Exception:
+                continue
+            if change is None:
+                continue
+            try:
+                self.on_change(change, self.snapshot)
+            except Exception:
+                pass
+
+
+def modules_for_paths(paths: Sequence[str]) -> List[str]:
+    """Map synced ``.py`` paths (``app/screens/home.py``) to dotted modules."""
+    modules: List[str] = []
+    seen: Set[str] = set()
+    for path in paths:
+        norm = path.replace("\\", "/")
+        if not norm.endswith(".py"):
+            continue
+        parts = norm[:-3].split("/")
+        if parts and parts[-1] == "__init__":
+            parts = parts[:-1]
+        if not parts or not all(part.isidentifier() for part in parts):
+            continue
+        dotted = ".".join(parts)
+        if dotted not in seen:
+            seen.add(dotted)
+            modules.append(dotted)
+    return modules

pythonnative/devserver/ws.py

@@ -0,0 +1,421 @@
+"""A small RFC 6455 (WebSocket) implementation on the standard library.
+
+The dev server and the on-device dev client both need WebSockets, and
+neither can assume a third-party package: the client runs inside the
+embedded interpreter on iOS and Android, where every dependency has to
+be bundled. This module provides just enough of the protocol for a
+trusted development network:
+
+- [`encode_frame`][pythonnative.devserver.ws.encode_frame] and
+  [`FrameDecoder`][pythonnative.devserver.ws.FrameDecoder] handle the
+  wire format (masking, 7/16/64-bit lengths, fragmentation, control
+  frames).
+- [`server_handshake`][pythonnative.devserver.ws.server_handshake] and
+  [`client_handshake_request`][pythonnative.devserver.ws.client_handshake_request]
+  build the HTTP upgrade.
+- [`WebSocketClient`][pythonnative.devserver.ws.WebSocketClient] is a
+  blocking client meant to live on a background thread (the dev client
+  uses one; the main thread never waits on the network).
+
+Extensions (compression) and subprotocols are not negotiated.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import socket
+import struct
+import threading
+from typing import Dict, Iterator, List, Optional, Tuple
+from urllib.parse import urlsplit
+
+__all__ = [
+    "CLOSE",
+    "BINARY",
+    "CONTINUATION",
+    "PING",
+    "PONG",
+    "TEXT",
+    "FrameDecoder",
+    "HandshakeError",
+    "WebSocketClient",
+    "WebSocketError",
+    "accept_key",
+    "client_handshake_request",
+    "encode_close",
+    "encode_frame",
+    "parse_http_headers",
+    "server_handshake",
+]
+
+_GUID = b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+CONTINUATION = 0x0
+TEXT = 0x1
+BINARY = 0x2
+CLOSE = 0x8
+PING = 0x9
+PONG = 0xA
+
+_CONTROL_OPCODES = {CLOSE, PING, PONG}
+MAX_MESSAGE_BYTES = 64 * 1024 * 1024
+"""Upper bound on one reassembled message; anything larger is a protocol error."""
+
+
+class WebSocketError(Exception):
+    """A framing or protocol violation on the connection."""
+
+
+class HandshakeError(WebSocketError):
+    """The HTTP upgrade did not complete."""
+
+
+# ======================================================================
+# Handshake
+# ======================================================================
+
+
+def accept_key(client_key: str) -> str:
+    """Return the ``Sec-WebSocket-Accept`` value for ``client_key``."""
+    digest = hashlib.sha1(client_key.strip().encode("ascii") + _GUID).digest()
+    return base64.b64encode(digest).decode("ascii")
+
+
+def parse_http_headers(raw: bytes) -> Tuple[str, Dict[str, str]]:
+    """Split an HTTP request or response head into ``(start_line, headers)``.
+
+    Header names are lower-cased. ``raw`` should be the bytes up to
+    (and optionally including) the blank line that ends the head.
+    """
+    text = raw.decode("iso-8859-1")
+    lines = text.split("\r\n")
+    start_line = lines[0].strip()
+    headers: Dict[str, str] = {}
+    for line in lines[1:]:
+        if not line.strip():
+            break
+        name, sep, value = line.partition(":")
+        if sep:
+            headers[name.strip().lower()] = value.strip()
+    return start_line, headers
+
+
+def server_handshake(headers: Dict[str, str]) -> bytes:
+    """Build the ``101 Switching Protocols`` response for an upgrade request.
+
+    Args:
+        headers: Lower-cased request headers (see
+            [`parse_http_headers`][pythonnative.devserver.ws.parse_http_headers]).
+
+    Raises:
+        HandshakeError: When the request is not a WebSocket upgrade.
+    """
+    if "websocket" not in headers.get("upgrade", "").lower():
+        raise HandshakeError("not a WebSocket upgrade request")
+    key = headers.get("sec-websocket-key")
+    if not key:
+        raise HandshakeError("missing Sec-WebSocket-Key")
+    return (
+        "HTTP/1.1 101 Switching Protocols\r\n"
+        "Upgrade: websocket\r\n"
+        "Connection: Upgrade\r\n"
+        f"Sec-WebSocket-Accept: {accept_key(key)}\r\n"
+        "\r\n"
+    ).encode("ascii")
+
+
+def client_handshake_request(host: str, path: str, key: Optional[str] = None) -> Tuple[bytes, str]:
+    """Build a client upgrade request; returns ``(request_bytes, key)``."""
+    if key is None:
+        key = base64.b64encode(os.urandom(16)).decode("ascii")
+    request = (
+        f"GET {path or '/'} HTTP/1.1\r\n"
+        f"Host: {host}\r\n"
+        "Upgrade: websocket\r\n"
+        "Connection: Upgrade\r\n"
+        f"Sec-WebSocket-Key: {key}\r\n"
+        "Sec-WebSocket-Version: 13\r\n"
+        "\r\n"
+    ).encode("ascii")
+    return request, key
+
+
+# ======================================================================
+# Framing
+# ======================================================================
+
+
+def encode_frame(opcode: int, payload: bytes, *, mask: bool = False, fin: bool = True) -> bytes:
+    """Encode one frame.
+
+    Clients must send masked frames and servers unmasked ones; the
+    caller picks. Text payloads must already be UTF-8 encoded.
+    """
+    head = bytearray()
+    head.append((0x80 if fin else 0x00) | (opcode & 0x0F))
+    length = len(payload)
+    mask_bit = 0x80 if mask else 0x00
+    if length < 126:
+        head.append(mask_bit | length)
+    elif length < 65536:
+        head.append(mask_bit | 126)
+        head += struct.pack("!H", length)
+    else:
+        head.append(mask_bit | 127)
+        head += struct.pack("!Q", length)
+    if not mask:
+        return bytes(head) + payload
+    key = os.urandom(4)
+    head += key
+    return bytes(head) + _apply_mask(payload, key)
+
+
+def encode_close(code: int = 1000, reason: str = "", *, mask: bool = False) -> bytes:
+    """Encode a close frame carrying ``code`` and ``reason``."""
+    body = struct.pack("!H", code) + reason.encode("utf-8")
+    return encode_frame(CLOSE, body, mask=mask)
+
+
+def _apply_mask(data: bytes, key: bytes) -> bytes:
+    """XOR ``data`` with the repeating 4-byte ``key`` (masking is symmetric)."""
+    if not data:
+        return b""
+    # Extend the key across the payload and XOR the two as big integers;
+    # this is far faster than a per-byte loop in pure Python.
+    repeated = (key * (len(data) // 4 + 1))[: len(data)]
+    return (int.from_bytes(data, "big") ^ int.from_bytes(repeated, "big")).to_bytes(len(data), "big")
+
+
+class FrameDecoder:
+    """Incremental frame parser that reassembles fragmented messages.
+
+    Feed raw bytes with [`feed`][pythonnative.devserver.ws.FrameDecoder.feed];
+    it yields complete ``(opcode, payload)`` messages. Control frames
+    (ping, pong, close) are yielded as they arrive, even in the middle
+    of a fragmented data message, as the RFC allows.
+    """
+
+    def __init__(self) -> None:
+        self._buffer = bytearray()
+        self._fragments: List[bytes] = []
+        self._fragment_opcode: Optional[int] = None
+
+    def feed(self, data: bytes) -> Iterator[Tuple[int, bytes]]:
+        """Consume ``data`` and yield every message it completes."""
+        self._buffer += data
+        while True:
+            parsed = self._parse_one()
+            if parsed is None:
+                return
+            fin, opcode, payload = parsed
+            if opcode in _CONTROL_OPCODES:
+                if not fin:
+                    raise WebSocketError("fragmented control frame")
+                yield opcode, payload
+                continue
+            if opcode == CONTINUATION:
+                if self._fragment_opcode is None:
+                    raise WebSocketError("continuation frame without a start")
+                self._fragments.append(payload)
+            else:
+                if self._fragment_opcode is not None:
+                    raise WebSocketError("new data frame while a message is fragmented")
+                self._fragment_opcode = opcode
+                self._fragments = [payload]
+            if sum(len(f) for f in self._fragments) > MAX_MESSAGE_BYTES:
+                raise WebSocketError("message exceeds the size limit")
+            if fin:
+                message_opcode = self._fragment_opcode
+                message = b"".join(self._fragments)
+                self._fragments = []
+                self._fragment_opcode = None
+                yield message_opcode, message
+
+    def _parse_one(self) -> Optional[Tuple[bool, int, bytes]]:
+        buf = self._buffer
+        if len(buf) < 2:
+            return None
+        first, second = buf[0], buf[1]
+        fin = bool(first & 0x80)
+        if first & 0x70:
+            raise WebSocketError("reserved bits set (extensions are not negotiated)")
+        opcode = first & 0x0F
+        masked = bool(second & 0x80)
+        length = second & 0x7F
+        offset = 2
+        if length == 126:
+            if len(buf) < 4:
+                return None
+            length = struct.unpack("!H", bytes(buf[2:4]))[0]
+            offset = 4
+        elif length == 127:
+            if len(buf) < 10:
+                return None
+            length = struct.unpack("!Q", bytes(buf[2:10]))[0]
+            offset = 10
+        if length > MAX_MESSAGE_BYTES:
+            raise WebSocketError("frame exceeds the size limit")
+        key = b""
+        if masked:
+            if len(buf) < offset + 4:
+                return None
+            key = bytes(buf[offset : offset + 4])
+            offset += 4
+        if len(buf) < offset + length:
+            return None
+        payload = bytes(buf[offset : offset + length])
+        del buf[: offset + length]
+        if masked:
+            payload = _apply_mask(payload, key)
+        return fin, opcode, payload
+
+
+# ======================================================================
+# Blocking client
+# ======================================================================
+
+
+class WebSocketClient:
+    """A blocking WebSocket client for background threads.
+
+    ``recv`` blocks until a text message arrives and transparently
+    answers pings; ``send_text`` is safe to call from any thread.
+
+    Args:
+        url: ``ws://host:port/path`` (``wss`` is not supported; dev
+            traffic stays on the local network).
+        timeout: Connect and read timeout in seconds. Reads that time
+            out raise ``socket.timeout``, letting the owning thread
+            check for shutdown between waits.
+    """
+
+    def __init__(self, url: str, *, timeout: Optional[float] = 30.0) -> None:
+        parts = urlsplit(url)
+        if parts.scheme not in ("ws", "http"):
+            raise ValueError(f"unsupported WebSocket scheme in {url!r} (use ws://)")
+        if not parts.hostname:
+            raise ValueError(f"missing host in {url!r}")
+        self.host = parts.hostname
+        self.port = parts.port or 80
+        self.path = (parts.path or "/") + (f"?{parts.query}" if parts.query else "")
+        self.timeout = timeout
+        self._sock: Optional[socket.socket] = None
+        self._decoder = FrameDecoder()
+        self._send_lock = threading.Lock()
+        self._closed = False
+
+    @property
+    def connected(self) -> bool:
+        """Whether the socket is open."""
+        return self._sock is not None and not self._closed
+
+    def connect(self) -> None:
+        """Open the TCP connection and complete the upgrade handshake."""
+        sock = socket.create_connection((self.host, self.port), timeout=self.timeout)
+        sock.settimeout(self.timeout)
+        request, key = client_handshake_request(f"{self.host}:{self.port}", self.path)
+        sock.sendall(request)
+        head = b""
+        while b"\r\n\r\n" not in head:
+            chunk = sock.recv(4096)
+            if not chunk:
+                sock.close()
+                raise HandshakeError("connection closed during the WebSocket handshake")
+            head += chunk
+            if len(head) > 65536:
+                sock.close()
+                raise HandshakeError("oversized handshake response")
+        head_bytes, _, rest = head.partition(b"\r\n\r\n")
+        status, headers = parse_http_headers(head_bytes)
+        if " 101 " not in f" {status} ":
+            sock.close()
+            raise HandshakeError(f"server refused the upgrade: {status}")
+        if headers.get("sec-websocket-accept") != accept_key(key):
+            sock.close()
+            raise HandshakeError("bad Sec-WebSocket-Accept from server")
+        self._sock = sock
+        self._closed = False
+        if rest:
+            # Frames may already trail the handshake; keep them.
+            self._pending = list(self._decoder.feed(rest))
+        else:
+            self._pending = []
+
+    def send_text(self, text: str) -> None:
+        """Send one text message (masked, as clients must)."""
+        self._send(encode_frame(TEXT, text.encode("utf-8"), mask=True))
+
+    def _send(self, frame: bytes) -> None:
+        sock = self._sock
+        if sock is None or self._closed:
+            raise WebSocketError("socket is closed")
+        with self._send_lock:
+            sock.sendall(frame)
+
+    def recv(self) -> Optional[str]:
+        """Block until a text message arrives.
+
+        Returns ``None`` once the peer closes. Raises ``socket.timeout``
+        when the read timeout elapses with no data, so callers can poll
+        a shutdown flag.
+        """
+        while True:
+            if self._pending:
+                opcode, payload = self._pending.pop(0)
+            else:
+                sock = self._sock
+                if sock is None or self._closed:
+                    return None
+                chunk = sock.recv(65536)
+                if not chunk:
+                    self._mark_closed()
+                    return None
+                messages = list(self._decoder.feed(chunk))
+                if not messages:
+                    continue
+                opcode, payload = messages[0]
+                self._pending = messages[1:]
+            if opcode == TEXT:
+                return payload.decode("utf-8")
+            if opcode == PING:
+                try:
+                    self._send(encode_frame(PONG, payload, mask=True))
+                except OSError:
+                    self._mark_closed()
+                    return None
+                continue
+            if opcode == CLOSE:
+                try:
+                    self._send(encode_close(mask=True))
+                except OSError:
+                    pass
+                self._mark_closed()
+                return None
+            # Binary and pong frames are ignored by the dev protocol.
+
+    def close(self, code: int = 1000, reason: str = "") -> None:
+        """Send a close frame (best effort) and shut the socket."""
+        sock = self._sock
+        if sock is None:
+            return
+        if not self._closed:
+            try:
+                self._send(encode_close(code, reason, mask=True))
+            except OSError:
+                pass
+        self._mark_closed()
+
+    def _mark_closed(self) -> None:
+        self._closed = True
+        sock, self._sock = self._sock, None
+        if sock is not None:
+            try:
+                sock.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+            try:
+                sock.close()
+            except OSError:
+                pass