snowflake-sandbox-python 0.2.1a1__tar.gz → 0.2.2a2__tar.gz

{snowflake_sandbox_python-0.2.1a1/src/snowflake_sandbox_python.egg-info → snowflake_sandbox_python-0.2.2a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-sandbox-python
-Version: 0.2.1a1
+Version: 0.2.2a2
 Summary: Snowflake sandboxes — Python SDK and CLI.
 Author: Snowflake, Inc.
 License: 
@@ -251,14 +251,52 @@ exec, stage I/O, fire-and-forget async jobs, and keep-alive sessions.
 
 ## Install
 
+Python 3.11+. Three ways in, depending on whether you want the CLI alongside your
+project's dependencies or isolated from them.
+
+**uv, in your project:**
+
+```bash
+uv add snowflake-sandbox-python            # core SDK
+uv add 'snowflake-sandbox-python[cli]'     # + the `snow sandbox` CLI plugin
+uv run snow plugin enable snow-sandbox     # once — see below
+uv run snow sandbox --help
+```
+
+**pip, in your project:**
+
 ```bash
 pip install snowflake-sandbox-python          # core SDK
 pip install 'snowflake-sandbox-python[cli]'   # + the `snow sandbox` CLI plugin
-snow plugin enable snow-sandbox            # required once before `snow sandbox` works
+snow plugin enable snow-sandbox               # once — see below
+snow sandbox --help
+```
+
+**CLI only, isolated from your project's dependencies:**
+
+```bash
+uv tool install snowflake-cli --with snowflake-sandbox-python
+snow plugin enable snow-sandbox
+snow sandbox --help
 ```
 
-Python 3.11+. `snowflake-connector-python` is a core dependency, so
-password / OAuth / PAT connections work out of the box.
+Note the shape of that last one: `snow` is the tool and this package is injected into it.
+`uv tool install 'snowflake-sandbox-python[cli]'` **fails** — this package ships no
+executable of its own, so uv reports *"No executables are provided by package"*. pipx is
+the same shape: `pipx install snowflake-cli`, then
+`pipx inject snowflake-cli snowflake-sandbox-python`.
+
+Two things catch people out:
+
+- **`snow plugin enable snow-sandbox` is required.** Plugins install disabled, so until
+  you run it `snow sandbox` is an unknown command. It writes to
+  `~/.snowflake/config.toml`, which makes it once per machine, not once per project.
+- **The plugin must live in the same environment as the `snow` binary.** Enabling it in
+  `config.toml` while the package sits in a different venv still leaves `snow sandbox`
+  unknown.
+
+`snowflake-connector-python` is a core dependency, so password / OAuth / PAT connections
+work out of the box.
 
 > **Preview release, gated on the Snowflake side.** The SDK is published as PEP 440
 > pre-releases on two tracks: `.devN` (e.g. `0.2.1.dev9`) on Snowflake's internal

{snowflake_sandbox_python-0.2.1a1 → snowflake_sandbox_python-0.2.2a2}/README.md

@@ -11,14 +11,52 @@ exec, stage I/O, fire-and-forget async jobs, and keep-alive sessions.
 
 ## Install
 
+Python 3.11+. Three ways in, depending on whether you want the CLI alongside your
+project's dependencies or isolated from them.
+
+**uv, in your project:**
+
+```bash
+uv add snowflake-sandbox-python            # core SDK
+uv add 'snowflake-sandbox-python[cli]'     # + the `snow sandbox` CLI plugin
+uv run snow plugin enable snow-sandbox     # once — see below
+uv run snow sandbox --help
+```
+
+**pip, in your project:**
+
 ```bash
 pip install snowflake-sandbox-python          # core SDK
 pip install 'snowflake-sandbox-python[cli]'   # + the `snow sandbox` CLI plugin
-snow plugin enable snow-sandbox            # required once before `snow sandbox` works
+snow plugin enable snow-sandbox               # once — see below
+snow sandbox --help
+```
+
+**CLI only, isolated from your project's dependencies:**
+
+```bash
+uv tool install snowflake-cli --with snowflake-sandbox-python
+snow plugin enable snow-sandbox
+snow sandbox --help
 ```
 
-Python 3.11+. `snowflake-connector-python` is a core dependency, so
-password / OAuth / PAT connections work out of the box.
+Note the shape of that last one: `snow` is the tool and this package is injected into it.
+`uv tool install 'snowflake-sandbox-python[cli]'` **fails** — this package ships no
+executable of its own, so uv reports *"No executables are provided by package"*. pipx is
+the same shape: `pipx install snowflake-cli`, then
+`pipx inject snowflake-cli snowflake-sandbox-python`.
+
+Two things catch people out:
+
+- **`snow plugin enable snow-sandbox` is required.** Plugins install disabled, so until
+  you run it `snow sandbox` is an unknown command. It writes to
+  `~/.snowflake/config.toml`, which makes it once per machine, not once per project.
+- **The plugin must live in the same environment as the `snow` binary.** Enabling it in
+  `config.toml` while the package sits in a different venv still leaves `snow sandbox`
+  unknown.
+
+`snowflake-connector-python` is a core dependency, so password / OAuth / PAT connections
+work out of the box.
 
 > **Preview release, gated on the Snowflake side.** The SDK is published as PEP 440
 > pre-releases on two tracks: `.devN` (e.g. `0.2.1.dev9`) on Snowflake's internal

{snowflake_sandbox_python-0.2.1a1 → snowflake_sandbox_python-0.2.2a2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "snowflake-sandbox-python"
-version = "0.2.1a1"
+version = "0.2.2a2"
 description = "Snowflake sandboxes — Python SDK and CLI."
 readme = "README.md"
 requires-python = ">=3.11"

{snowflake_sandbox_python-0.2.1a1 → snowflake_sandbox_python-0.2.2a2}/src/snowflake/cli_sandbox/_run_command.py

@@ -447,6 +447,20 @@ def _reject_inapplicable_flags(
         )
     if idle_suspend is not None and not detach:
         raise typer.BadParameter("--idle-suspend applies only to a --detach run.")
+    if idle_suspend is not None:
+        # Parse it HERE, not at create time. The value only reaches the SDK's
+        # normalizer inside `AsyncSandbox.create`, which raises a bare ValueError --
+        # and the detached path's only handler catches SandboxError, so it escaped as
+        # "An unexpected exception occurred", making a typo look like an SDK bug. It
+        # also escaped *after* "Spinning up sandbox..." had printed. Validating with
+        # the rest of the flags turns it into the same `Invalid value:` the other
+        # --idle-suspend mistakes already get, before anything is created.
+        from snowflake.sandbox._wire import _idle_suspend_minutes
+
+        try:
+            _idle_suspend_minutes(idle_suspend)
+        except (ValueError, TypeError) as exc:
+            raise typer.BadParameter(f"--idle-suspend: {exc}") from exc
 
 
 def _memory_bytes(tier: str | None) -> int:

{snowflake_sandbox_python-0.2.1a1 → snowflake_sandbox_python-0.2.2a2}/src/snowflake/sandbox/__init__.py

@@ -1,6 +1,6 @@
 """Snowflake sandboxes — a Modal-style ergonomic Python client over Snowflake.
 
-The sandbox is the primitive — create it, run code in it, reconnect by id.
+The sandbox is the primitive — create it, run code in it, reconnect by name.
 ``Sandbox.create()`` is the factory (like Modal's ``Sandbox.create``); reconnect
 with ``Sandbox.connect(name)`` / ``get_sandbox_by_name``:
 
@@ -30,6 +30,7 @@ from snowflake.sandbox.exceptions import (
     SandboxAuthError,
     SandboxConflictError,
     SandboxContractWarning,
+    SandboxCreateError,
     SandboxError,
     SandboxExecError,
     SandboxExecTimeoutError,
@@ -41,6 +42,7 @@ from snowflake.sandbox.exceptions import (
     SandboxTransportError,
     SandboxValidationError,
 )
+from snowflake.sandbox.failure import SandboxFailure
 from snowflake.sandbox.types import (
     ExecResult,
     FileInfo,
@@ -119,6 +121,8 @@ __all__ = [
     # exceptions
     "SandboxError",
     "SandboxAuthError",
+    "SandboxCreateError",
+    "SandboxFailure",
     "SandboxValidationError",
     "SandboxConflictError",
     "SandboxNotFoundError",

{snowflake_sandbox_python-0.2.1a1 → snowflake_sandbox_python-0.2.2a2}/src/snowflake/sandbox/_files_mixin.py

@@ -110,6 +110,11 @@ class _FilesMixin:
     async def download_file(self, remote: str, local: str | Path) -> None:
         """Download a file from the running sandbox to a local path.
 
+        Note:
+            Written to a temp file beside the destination and renamed on success, so a
+            download that fails part-way leaves neither a truncated file where a whole
+            one is expected nor a directory tree the caller did not have before.
+
         Example:
             await sb.download_file("/app/output.csv", "./output.csv")
         """
@@ -118,20 +123,49 @@ class _FilesMixin:
         await download_file(cast("AsyncSandbox", self), remote, local, transport=self._transport)
 
     async def stage_put(self, local: str, stage_path: str) -> None:
-        """Upload a local file to a Snowflake stage from within the sandbox.
+        """Not implemented -- the ``stage/put`` route returns 501 on every backend.
+
+        *Would* server-side PUT from ``local`` (inside the sandbox) to ``stage_path``
+        without bytes traversing the caller's memory.
+
+        Note:
+            Not implemented on any backend: the ``stage/put`` route answers 501, so this
+            always raises `SandboxNotImplementedError`. Mount the stage with `StageMount`
+            and write through the mount instead.
 
         Example:
-            await sb.stage_put("./results.parquet", "MY_STAGE/results.parquet")
+            # This raises SandboxNotImplementedError. Mount the stage and write
+            # through the mount instead:
+            data = StageMount.from_stage("MY_STAGE", mount_path="/data")
+            async with await AsyncSandbox.create(stage_mounts=[data]) as sb:
+                await sb.write_bytes("/data/results.parquet", payload)
+
+        Raises:
+            SandboxNotImplementedError: always, until a backend wires the route.
         """
         from snowflake.sandbox.files import stage_put
 
         await stage_put(cast("AsyncSandbox", self), local, stage_path, transport=self._transport)
 
     async def stage_get(self, stage_path: str, local: str) -> None:
-        """Download a file from a Snowflake stage to a local path inside the sandbox.
+        """Not implemented -- the ``stage/get`` route returns 501 on every backend.
+
+        *Would* server-side GET from ``stage_path`` to ``local`` inside the sandbox.
+
+        Note:
+            Not implemented on any backend: the ``stage/get`` route answers 501, so this
+            always raises `SandboxNotImplementedError`. Mount the stage with `StageMount`
+            and read through the mount instead.
 
         Example:
-            await sb.stage_get("MY_STAGE/model.pkl", "/app/model.pkl")
+            # This raises SandboxNotImplementedError. Mount the stage and read
+            # through the mount instead:
+            data = StageMount.from_stage("MY_STAGE", mount_path="/data", readonly=True)
+            async with await AsyncSandbox.create(stage_mounts=[data]) as sb:
+                model = await sb.read_bytes("/data/model.pkl")
+
+        Raises:
+            SandboxNotImplementedError: always, until a backend wires the route.
         """
         from snowflake.sandbox.files import stage_get
 

{snowflake_sandbox_python-0.2.1a1 → snowflake_sandbox_python-0.2.2a2}/src/snowflake/sandbox/_hosts.py

@@ -1,7 +1,11 @@
 """Host-pattern matching for egress rules.
 
-Pure domain-string logic, shared by the `Egress` spec and by `Secret`'s
-host-scope validation. No spec types, so both can import it without a cycle.
+Pure domain-string logic, no spec types, so callers can import it without a cycle.
+
+Be careful which platform rule you are reasoning about: the sandbox platform has
+**two** host matchers and they disagree on a bare entry. `host_covered_by` (and
+`host_covered_by_all` over it) implements the secret-injection one, because that is
+what its caller needs — see its docstring before reusing either elsewhere.
 """
 
 from __future__ import annotations
@@ -20,8 +24,23 @@ __all__ = [
 def host_covered_by(host: str, allowed: Sequence[str]) -> bool:
     """Is *host* covered by any pattern in *allowed*?
 
-    Matches the platform's own rule: a bare entry covers itself and every subdomain,
-    while an explicit `*.suffix` entry covers subdomains only.
+    A bare entry covers itself and every subdomain; an explicit `*.suffix` entry
+    covers subdomains only, not the apex.
+
+    That mirrors the platform's **secret-injection** matcher, CNG
+    `EgressSecretRule.matchesHost` (`pkg/hostagent/network/credential_injection.go`),
+    which is the rule that governs this function's callers: `Secret.scope()` decides
+    which single `allowed_host` a multi-host secret collapses to, and CNG swaps that
+    secret's dummy at the bare host plus every subdomain under it. Live-verified on
+    qa6 2026-09-24 — one secret scoped `host="github.com"` had its dummy swapped for
+    the real token on a request to `api.github.com`.
+
+    It is deliberately NOT the platform's **reachability** matcher. CNG
+    `egressHostMatches` (`pkg/hostagent/network/outbound_proxy.go`) resolves a bare
+    entry with `strings.EqualFold` — exact — for both the built-in convenience groups
+    and EAI-resolved network rules, so a bare grant there does not open its subdomains
+    (live: an EAI granting `github.com` refuses `gist.github.com`). Do not reuse this
+    function to predict whether a host is reachable; it would answer yes too often.
     """
     h = host.lower().rstrip(".")
     for entry in allowed:

{snowflake_sandbox_python-0.2.1a1 → snowflake_sandbox_python-0.2.2a2}/src/snowflake/sandbox/_runtime/_protocol.py

@@ -19,7 +19,31 @@ from __future__ import annotations
 _RESULT_SENTINEL = "__SANDBOX_RESULT__"
 
 # The mailbox file the daemon tails inside the container.
-_MAILBOX_PATH = "/tmp/sandbox_mailbox.jsonl"
+#
+# On the PERSISTENT rootfs, not ``/tmp``. ``/tmp`` is tmpfs: an idle auto-suspend
+# tears the container down (pause -> filesystem snapshot -> stop + delete) and the
+# fresh container it resumes into has an empty ``/tmp``, so a mailbox there is
+# destroyed along with every queued and in-flight message. ``/var/tmp`` is part of
+# the snapshotted rootfs and survives.
+#
+# COMPATIBILITY: a container deployed by an SDK at or before 0.2.1.dev11 runs a
+# daemon that tails the old ``/tmp/sandbox_mailbox.jsonl``, so ``send()`` from a
+# newer client cannot reach it -- redeploy the session. The timeout message in
+# ``warm_session`` names this.
+_MAILBOX_PATH = "/var/tmp/sandbox_mailbox.jsonl"
+
+# Suffix of the daemon's consumed-offset sidecar, alongside the mailbox itself
+# (``<mailbox>.offset``). Written and read only inside the container, but by two
+# independent implementations that must agree: `session_loop` and the inlined loop
+# in the generated session shim.
+#
+# It exists because the mailbox now OUTLIVES the daemon. While both lived on tmpfs
+# they were destroyed together, so a restarting daemon starting at offset 0 always
+# faced an empty file; with a durable mailbox that same offset 0 would re-deliver
+# every historical message -- re-running the side effects of a conversation nobody
+# is waiting on any more. The sidecar is what makes a restart resume rather than
+# replay.
+_MAILBOX_OFFSET_SUFFIX = ".offset"
 
 # The stdout sentinel the in-container daemon prints per reply. The payload is
 # ``<msg_id>__<nonce>__<base64(json(reply))>`` so a reply is matched to its message

{snowflake_sandbox_python-0.2.1a1 → snowflake_sandbox_python-0.2.2a2}/src/snowflake/sandbox/_runtime/_shims.py

@@ -21,6 +21,7 @@ import textwrap
 
 from snowflake.sandbox._runtime._protocol import (
     _ENTER_FLAG,
+    _MAILBOX_OFFSET_SUFFIX,
     _MAILBOX_PATH,
     _REPLY_SENTINEL,
     _RESULT_SENTINEL,
@@ -54,6 +55,14 @@ def _session_runner_shim(module: str, name: str) -> str:
        ``instance.on_message(msg)`` and print
        ``__SANDBOX_REPLY__<id>__<base64(json(reply))>`` to stdout (flushed).
        Malformed lines and handler exceptions never kill the daemon.
+
+    The mailbox is on the persistent rootfs and so outlives this process, so the
+    loop also keeps a consumed-offset sidecar next to it and starts from the
+    recorded byte count — without which a restarted daemon would re-deliver the
+    whole conversation. It also ignores SIGUSR1/SIGUSR2: the platform sends SIGUSR1
+    before the checkpoint and its default action is terminate, so an unguarded
+    daemon dies on the way into a suspend — including the suspend that then *fails*
+    and leaves the container running (see `session_loop` and sandbox-sdk#399).
     """
     return textwrap.dedent(f"""\
         import base64
@@ -65,6 +74,7 @@ def _session_runner_shim(module: str, name: str) -> str:
         import time
 
         _MAILBOX_PATH = {_MAILBOX_PATH!r}
+        _OFFSET_PATH = _MAILBOX_PATH + {_MAILBOX_OFFSET_SUFFIX!r}
         _REPLY_SENTINEL = {_REPLY_SENTINEL!r}
         _ENTER_FLAG = {_ENTER_FLAG!r}
 
@@ -96,14 +106,13 @@ def _session_runner_shim(module: str, name: str) -> str:
         if _enter is not None:
             _enter()
 
-        # --- survive the platform's own idle checkpoint -------------------
-        # Snowflake's idle auto-suspend sends SIGUSR1 immediately before the
-        # gVisor memory checkpoint and SIGUSR2 after restore. SIGUSR1's default
-        # action is *terminate*, so a daemon that installs nothing is killed on
-        # suspend; ignoring both keeps it alive. Nothing else is wired to these
-        # signals -- every reply is printed with flush=True, so there is no
-        # buffered output to drain, and warm state on _instance survives the
-        # checkpoint by itself.
+        # --- survive the pre-suspend signal ------------------------------
+        # The platform sends SIGUSR1 unconditionally 500ms before it checkpoints,
+        # and SIGUSR1's default action is terminate. Across a COMPLETED suspend
+        # this buys nothing (the container is deleted and the restore is not
+        # wired), but a suspend whose checkpoint FAILS leaves the container
+        # running -- and then the difference is a working daemon versus a dead
+        # one behind a "running" status. See `session_loop` (sandbox-sdk#399).
         try:
             signal.signal(signal.SIGUSR1, signal.SIG_IGN)
             signal.signal(signal.SIGUSR2, signal.SIG_IGN)
@@ -111,12 +120,44 @@ def _session_runner_shim(module: str, name: str) -> str:
             pass
 
         # --- inline mailbox loop (no session_loop import) ---
-        _offset = 0
+        #
+        # The mailbox is on the persistent rootfs, so it OUTLIVES this process and
+        # a fresh daemon can start up facing a conversation a previous incarnation
+        # already handled. The sidecar tells those apart. Mirrors
+        # `warm_session._initial_offset`, including why NO sidecar means 0 (nothing
+        # was ever consumed, and skipping would drop a first message that arrived
+        # while this process was still importing the user's module) while an
+        # unusable one skips to the end (something was consumed, we cannot tell
+        # what, and replaying side effects is the worse way to be wrong).
+        def _write_offset(_value):
+            try:
+                with open(_OFFSET_PATH + ".tmp", "w") as _fh:
+                    _fh.write(str(_value))
+                os.replace(_OFFSET_PATH + ".tmp", _OFFSET_PATH)
+            except OSError:
+                pass
+
         try:
             open(_MAILBOX_PATH, "a").close()
         except OSError:
             pass
 
+        try:
+            _size = os.path.getsize(_MAILBOX_PATH)
+        except OSError:
+            _size = 0
+        try:
+            with open(_OFFSET_PATH) as _fh:
+                _raw = _fh.read().strip()
+        except OSError:
+            _offset = 0
+        else:
+            try:
+                _recorded = int(_raw)
+            except ValueError:
+                _recorded = -1
+            _offset = _size if (_recorded < 0 or _recorded > _size) else _recorded
+
         while True:
             try:
                 _size = os.path.getsize(_MAILBOX_PATH)
@@ -125,15 +166,30 @@ def _session_runner_shim(module: str, name: str) -> str:
                 continue
             if _size < _offset:
                 _offset = 0
+                _write_offset(_offset)
             if _size == _offset:
                 time.sleep(0.5)
                 continue
-            with open(_MAILBOX_PATH, "r") as _fh:
+            # Binary, so _offset stays a true byte count comparable with
+            # getsize(); a text-mode tell() is an opaque cookie.
+            with open(_MAILBOX_PATH, "rb") as _fh:
                 _fh.seek(_offset)
-                _new_lines = _fh.readlines()
-                _offset = _fh.tell()
-            for _line in _new_lines:
-                _line = _line.strip()
+                _chunk = _fh.read()
+            # A trailing line with no newline is a partial append still in
+            # flight; leave _offset behind it so it is re-read whole next poll.
+            if _chunk and not _chunk.endswith(b"\\n"):
+                _partial = _chunk.rpartition(b"\\n")[2]
+                _chunk = _chunk[: len(_chunk) - len(_partial)]
+            if not _chunk:
+                time.sleep(0.5)
+                continue
+            for _raw in _chunk.splitlines(True):
+                # Consumed BEFORE handling: with a durable mailbox, advancing
+                # afterwards makes a daemon killed mid-turn re-run that turn on
+                # the next incarnation.
+                _offset += len(_raw)
+                _write_offset(_offset)
+                _line = _raw.decode("utf-8", "replace").strip()
                 if not _line:
                     continue
                 try:
@@ -228,17 +284,27 @@ def _detached_wrapper_source(payload: str, nonce: str) -> str:
     *payload* is the JSON-encoded inner argv and *nonce* the per-run token the
     sentinel is stamped with. See `_args._wrap_detached`, which mints both, for
     why the nonce never reaches the inner command's environment.
+
+    The wrapper ignores SIGUSR1/SIGUSR2, and that choice is load-bearing *here* in
+    a way it is not for the daemon: this process `subprocess.run`s the **user's own
+    command**. The platform sends SIGUSR1 before a suspend, unconditionally, and its
+    default action is terminate — so without this, a third-party program that never
+    asked to care about SIGUSR1 is killed by a platform signal the SDK never told it
+    about, and on a suspend whose checkpoint then fails the container is left
+    ``running`` with the managed process dead inside it.
+
+    The cost, stated plainly because it is a real one: ``SIG_IGN`` **is inherited
+    across ``exec``**, so the inner command starts with SIGUSR1/SIGUSR2 ignored. A
+    program that installs its own handler overrides that and is unaffected; only one
+    relying on the *default* terminate-on-SIGUSR1 behaviour would notice. Being
+    alive is the better default (sandbox-sdk#399).
     """
     return f"""\
 import base64, json, os, signal, subprocess, sys
 argv = json.loads({payload!r})
 nonce = {nonce!r}
-# Survive the platform's idle checkpoint. Snowflake's auto-suspend sends SIGUSR1
-# immediately before the gVisor memory checkpoint and SIGUSR2 after restore, and
-# SIGUSR1's default action is *terminate* -- so without this the wrapper (and with it
-# the managed process) is killed the first time a detached sandbox goes idle, instead
-# of being suspended and resumed. The session shim and the warm-session loop already
-# do exactly this; this path was missed.
+# Pre-suspend SIGUSR1 would otherwise terminate this wrapper and orphan the managed
+# process. Inherited across exec by the inner command -- see _detached_wrapper_source.
 try:
     signal.signal(signal.SIGUSR1, signal.SIG_IGN)
     signal.signal(signal.SIGUSR2, signal.SIG_IGN)