snowflake-sandbox-python 0.2.1a1__py3-none-any.whl

snowflake/sandbox/_sync_watch.py

@@ -0,0 +1,99 @@
+"""Sync filesystem change notifications — for ``Sandbox``.
+
+Synchronous counterpart to `_watch`: the same ctypes ``inotify(7)`` monitor in the
+container, streamed over the synchronous ``exec_stream``. See `_watch` for the
+mechanism and its caveats.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+# The in-container half is shared with the async side via _runtime; both modes
+# ship the same program text and parse the same sentinel.
+from snowflake.sandbox._runtime._fs_helper import _watch_program
+from snowflake.sandbox._runtime._protocol import _WATCH_SENTINEL
+from snowflake.sandbox._sync_transport import SyncTransport
+from snowflake.sandbox._watch import _WATCH_WINDOW_S, _mask_to_event_type
+from snowflake.sandbox.files import _require_absolute
+from snowflake.sandbox.types import FileWatchEvent, FileWatchEventType
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator, Sequence
+
+    from snowflake.sandbox.sync_client import Sandbox
+
+__all__ = ["watch"]
+
+
+def watch(
+    sandbox: Sandbox,
+    path: str,
+    *,
+    filter: Sequence[FileWatchEventType] | None = None,
+    recursive: bool = False,
+    timeout: float | None = None,
+    transport: SyncTransport | None = None,
+) -> Iterator[FileWatchEvent]:
+    """Stream filesystem-change events under ``path`` — synchronous counterpart of
+    ``_watch.watch``. A generator: ``for ev in sb.watch(...)``.
+
+    ``path`` must be absolute. ``filter`` restricts the yielded
+    `FileWatchEventType`\\ s (``None`` = all). ``recursive`` also watches nested
+    subdirectories (and directories created later). ``timeout`` bounds the watch in
+    seconds; ``None`` watches until the caller stops iterating.
+
+    Runs the same ctypes ``inotify(7)`` monitor in the container as the async
+    version, over the synchronous ``exec_stream``, so the two clients behave the
+    same.
+
+    Caveats are the async ones, unchanged: one logical save commonly yields a
+    `Modify`, while atomic save-by-rename editors surface `Create`/`Delete` of a
+    temp plus a move; a large ``recursive`` watch consumes one kernel watch
+    descriptor per directory; and ``timeout=None`` is realised as a relaunch loop
+    of bounded windows, so events during the sub-second relaunch gap can be missed
+    (a bounded ``timeout`` runs as one stream and has no such gap).
+    """
+    p = _require_absolute(path)
+    allowed = frozenset(filter) if filter else None
+    prog = _watch_program()
+
+    def _one_window(window_timeout: float | None) -> Iterator[FileWatchEvent]:
+        argv = [
+            "python3",
+            "-c",
+            prog,
+            p,
+            "1" if recursive else "0",
+            "" if window_timeout is None else repr(window_timeout),
+        ]
+        stream = sandbox.exec_stream(argv, timeout=window_timeout)
+        for line in stream:
+            if line.stream != "stdout":
+                continue
+            idx = line.data.find(_WATCH_SENTINEL)
+            if idx == -1:
+                continue
+            payload = line.data[idx + len(_WATCH_SENTINEL) :]
+            if payload.startswith("READY"):
+                continue
+            try:
+                obj = json.loads(payload)
+            except ValueError:
+                continue
+            etype = _mask_to_event_type(int(obj.get("mask", 0)))
+            if allowed is not None and etype not in allowed:
+                continue
+            yield FileWatchEvent(paths=[str(obj.get("path", p))], type=etype)
+
+    if timeout is not None:
+        # Bounded: one stream, kept alive across GOAWAYs by exec_stream's resume.
+        yield from _one_window(timeout)
+        return
+
+    # Indefinite: relaunch bounded windows until the caller stops iterating.
+    # Breaking the for-loop closes this generator, which closes the stream and
+    # kills the in-container monitor.
+    while True:
+        yield from _one_window(_WATCH_WINDOW_S)