snowflake-sandbox-python 0.2.2a3__tar.gz → 0.2.2a4__tar.gz

{snowflake_sandbox_python-0.2.2a3/src/snowflake_sandbox_python.egg-info → snowflake_sandbox_python-0.2.2a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-sandbox-python
-Version: 0.2.2a3
+Version: 0.2.2a4
 Summary: Snowflake sandboxes — Python SDK and CLI.
 Author: Snowflake, Inc.
 License: 

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "snowflake-sandbox-python"
-version = "0.2.2a3"
+version = "0.2.2a4"
 description = "Snowflake sandboxes — Python SDK and CLI."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -146,11 +146,28 @@ testpaths = ["tests"]
 addopts = "-m 'not live'"
 markers = [
     "live: tests that run against a real sandbox-api deployment",
-    # The promotion gate. A fast (~10 creates, 3-5 min) subset of `live` that a
-    # deployment must pass before it is promoted to the next tier. Chosen so every
-    # member fails LOUDLY on an unhealthy deployment: no egress tests (they assert
-    # "BLOCKED" and so pass for the wrong reason when networking is dead), nothing
-    # that skips on error, and nothing unbounded. Run with `-m smoke`.
+    # The promotion gate. A fast subset of `live` that a deployment must pass before it
+    # is promoted to the next tier. Chosen so every member fails LOUDLY on an unhealthy
+    # deployment: nothing that skips on error, and nothing unbounded. Run with `-m smoke`.
+    #
+    # Measured on qa6, 2026-09-24: **15 tests, ~47s**. (The previous note here said
+    # "~10 creates, 3-5 min" — the count was right for its time but the duration was never
+    # close; don't budget against it.) Adding the two egress rows cost +16.6s over the
+    # 13-test predecessor's 29.9s. Worth re-measuring rather than trusting this line if the
+    # gate's cost ever becomes the question.
+    #
+    # This used to say "no egress tests (they assert 'BLOCKED' and so pass for the wrong
+    # reason when networking is dead)". That reasoning was correct and is why egress was
+    # excluded — but it no longer describes the gate. The egress level's EXPLICIT rows are
+    # now gated, because the test that carries them defeats that specific objection: its
+    # restrictive leg asserts a liveness CONTROL (the sandbox can still reach its Snowflake
+    # account) so "refused" cannot be confused with "the proxy is refusing everything", and
+    # its permissive leg asserts a 200, which a dead network cannot produce.
+    #
+    # Still excluded, deliberately: the tier's DEFAULT egress level. Its correct value is
+    # tier-dependent while the opt-in flip rolls (permissive before, closed after), so
+    # gating it would freeze the train on precisely the change being rolled out. It stays in
+    # the broader `-m live` suite, where a human reads it against a known switch state.
     "smoke: promotion-gate subset of the live suite",
 ]
 filterwarnings = [

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/src/snowflake/cli_sandbox/_egress_flags.py

@@ -106,7 +106,12 @@ def build_egress(
 
     egress = Egress(
         external_access_integrations=integrations,
-        **({"allow_default_egress": False} if no_default_egress else {}),
+        # Uses the current parameter name. The CLI FLAG stays `--no-default-egress`: it is
+        # released, renaming it would break users' scripts, and that is a separate decision
+        # from the library parameter's name. So the flag spelling and the parameter spelling
+        # differ here deliberately — the alternative is the CLI depending on a deprecated
+        # parameter, which is worse.
+        **({"allow_public_package_registries": False} if no_default_egress else {}),
     )
     # Validate now, not at create time. `compile_egress` is pure and is what the client
     # runs anyway -- but it runs *after* connecting, so a mistyped host pair otherwise

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/src/snowflake/cli_sandbox/_run_command.py

@@ -312,7 +312,13 @@ def _print_inferred_plan(plan: _RunPlan) -> None:
     typer.echo(f"command:    {plan.command or '(image default)'}")
     if plan.egress is not None:
         eais = getattr(plan.egress, "external_access_integrations", ())
-        closed = getattr(plan.egress, "allow_default_egress", None) is False
+        # Read the RESOLVER, not any one spelling. There are three accepted names for this
+        # control and reading a specific field goes silently blind when a caller (or this
+        # CLI) uses a different one — which is exactly what happened: switching the flag's
+        # construction to allow_public_package_registries made this summary stop reporting
+        # "default-egress=closed" while the sandbox was still correctly closed. A dry run
+        # that under-reports the egress posture is worse than no dry run.
+        closed = getattr(plan.egress, "default_egress_allowed", None) is False
         bits = [f"eai={','.join(eais)}" if eais else "", "default-egress=closed" if closed else ""]
         if plan.secrets:
             bits.append(f"secrets={len(plan.secrets)}")

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/src/snowflake/sandbox/_diagnostics.py

@@ -127,19 +127,19 @@ def preflight_checks(spec: DeploySpec, bundle_root: Path | None = None) -> list[
         problems.append(Problem("error", str(exc)))
 
     # A secret's `host` and Snowflake reachability are different controls: the first is
-    # enforced at the credential swap, the second by allow_internet / the group
-    # booleans. A secret scoped to a host the sandbox cannot reach on Snowflake is
+    # enforced at the credential swap, the second by the egress level
+    # (allow_public_package_registries) / the group booleans. A secret scoped to a host the sandbox cannot reach on Snowflake is
     # silently useless, so say so. (eai_hosts is the SPCS perimeter and does not
     # affect Snowflake reachability, so it is deliberately not consulted here.)
     # Only warn when egress was *explicitly* closed AND no EAI was granted:
-    #   - allow_internet is tri-state: left unset the platform applies its permissive
+    #   - the egress level is tri-state: left unset the platform applies its permissive
     #     default, and actual reachability is then an Istio question we cannot answer
     #     from here — warning on it would be noise on the common path.
     #   - allow_github / allow_pypi are NOT credited here, and now never could be: both
     #     are inert, so neither makes a host reachable in any mode. The retired
     #     allowed_egress_hosts is likewise not consulted — hosts named there are ignored
     #     platform-side.
-    #   - Under allow_internet=False the only grant left is an EAI, whose network rules
+    #   - Under allow_public_package_registries=False the only grant left is an EAI, whose rules
     #     live in Snowflake and cannot be resolved from here — so an EAI being present is
     #     taken as "the caller has said how" (loop-invariant, hence hoisted out below).
     eg = spec.egress
@@ -153,13 +153,15 @@ def preflight_checks(spec: DeploySpec, bundle_root: Path | None = None) -> list[
                 hint = (
                     f"grant {h!r} with an External Access Integration and pass "
                     f'external_access_integrations=("MY_EAI",) — under '
-                    f"allow_internet=False that is the only grant the platform applies"
+                    f"allow_public_package_registries=False that is the only grant the "
+                    f"platform applies"
                 )
                 problems.append(
                     Problem(
                         "warn",
                         f"secret {s.fqn!r} is scoped to host {h!r}, which the sandbox cannot "
-                        f"reach with allow_internet=False — the credential could never be used",
+                        f"reach with allow_public_package_registries=False — the credential "
+                        f"could never be used",
                         hint,
                     )
                 )

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/src/snowflake/sandbox/_version.py

@@ -29,7 +29,7 @@ __all__ = ["__version__"]
 _DIST_NAME = "snowflake-sandbox-python"
 
 # Keep in sync with [project].version in pyproject.toml.
-_FALLBACK_VERSION = "0.2.2a3"
+_FALLBACK_VERSION = "0.2.2a4"
 
 try:
     __version__: str = _pkg_version(_DIST_NAME)

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/src/snowflake/sandbox/client.py

@@ -132,7 +132,7 @@ async def _coerce_image(image: str | Image, transport: Transport | None) -> str:
 
 
 class AsyncSandbox(_FilesMixin, _SandboxState):
-    """A Snowflake sandbox container (async API).
+    """A Cortex Sandbox (async API).
 
     ``await create()`` is the factory, and the only creation path -- ``AsyncSandbox(...)``
     raises. A constructor cannot be awaited, which is the deeper reason it was never the
@@ -769,12 +769,26 @@ class AsyncSandbox(_FilesMixin, _SandboxState):
             return
         await self._wait_until_ready(timeout=timeout)
 
-    async def logs(self, *, tail: int = 0, since_ts_ms: int = 0) -> str:
+    async def logs(
+        self, *, tail: int = 0, since_ts_ms: int = 0, source: str | None = None, pid: int = 0
+    ) -> str:
         """Return the container's captured stdout and stderr as a string.
 
         `tail` limits to the last N lines. Only meaningful for command containers
         (created with `command=`).
 
+        `source` selects which stream to read, defaulting to the server's `all` -- the
+        entrypoint plus the `command=` process:
+
+        - ``"exec"`` -- what the commands you ran with `exec()` printed, which no other
+          source includes. `exec()` also returns that output directly; this is how you
+          read it again afterwards.
+        - ``"base"`` / ``"managed"`` -- one of the two long-lived streams on its own.
+
+        `pid` narrows an exec read to one producer. Without it every exec is merged and
+        the returned text carries no per-line attribution; `pid=` is how you read one
+        command's output on its own.
+
         SDK-internal protocol markers are suppressed: the in-sandbox runner reports a
         run's outcome as `__SANDBOX_RESULT__<b64>` on stdout and the session daemon
         reports replies as `__SANDBOX_REPLY__<...>`, so both land in the log stream
@@ -785,10 +799,13 @@ class AsyncSandbox(_FilesMixin, _SandboxState):
         Example:
             output = await sb.logs(tail=100)
             print(output)
+
+            # What the commands you ran with `exec()` printed.
+            print(await sb.logs(source="exec"))
         """
         fetch = _logs_overfetch(tail)
         while True:
-            raw = await self._logs_raw(tail=fetch, since_ts_ms=since_ts_ms)
+            raw = await self._logs_raw(tail=fetch, since_ts_ms=since_ts_ms, source=source, pid=pid)
             raw_count = len(raw.split("\n")) if raw else 0
             visible = _visible_log_lines(raw)
             if tail <= 0 or len(visible) >= tail:
@@ -806,7 +823,9 @@ class AsyncSandbox(_FilesMixin, _SandboxState):
             visible = visible[-tail:]
         return "\n".join(visible)
 
-    async def _logs_raw(self, *, tail: int = 0, since_ts_ms: int = 0) -> str:
+    async def _logs_raw(
+        self, *, tail: int = 0, since_ts_ms: int = 0, source: str | None = None, pid: int = 0
+    ) -> str:
         """The log snapshot EXACTLY as the server returns it, markers included.
 
         Internal consumers that read the runner's or daemon's stdout protocol
@@ -825,6 +844,14 @@ class AsyncSandbox(_FilesMixin, _SandboxState):
             q.append(f"tail={tail}")
         if since_ts_ms:
             q.append(f"since={since_ts_ms}")
+        # Forwarded verbatim rather than validated here: the server owns the vocabulary
+        # and names the valid values in its rejection, so a client-side allowlist would go
+        # stale as soon as a source is added and would turn a 400 that explains itself
+        # into one that does not.
+        if source:
+            q.append(f"source={source}")
+        if pid:
+            q.append(f"pid={pid}")
         path = f"containers/{self._id}/logs" + ("?" + "&".join(q) if q else "")
         try:
             resp = await self._transport.request(

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/src/snowflake/sandbox/connect.py

@@ -251,7 +251,7 @@ def _make_connection(**kwargs: Any) -> Any:
 
 
 def get_snowflake_connection(**kwargs: Any) -> Any:
-    """Return a Snowflake connection for code running inside a Snowflake sandbox.
+    """Return a Snowflake connection for code running inside a Cortex Sandbox.
 
     Resolves the credential the way the platform provides it, in order: the
     ``SNOWFLAKE_PAT``/``SNOWFLAKE_TOKEN`` env value; a token file named by

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/src/snowflake/sandbox/egress.py

@@ -48,7 +48,7 @@ def _retired_host_list_message(spelling: str) -> str:
         f"locally instead: the sandbox would start healthy and silently fail to reach "
         f"them.\n\n"
         f"Grant the hosts with an External Access Integration and name it instead:\n"
-        f'    Egress(allow_default_egress=False, external_access_integrations=("MY_EAI",))\n\n'
+        f'    Egress(allow_public_package_registries=False, external_access_integrations=("MY_EAI",))\n\n'
         f"Creating one (the network rule cannot live in a personal USER$ database):\n"
         f"    CREATE NETWORK RULE db.schema.my_rule MODE = EGRESS TYPE = HOST_PORT\n"
         f"        VALUE_LIST = ('example.com:443');\n"
@@ -71,11 +71,30 @@ def _nonempty_host_value(raw: object) -> bool:
     return len(raw) > 0
 
 
-# The REST spelling of the default-egress tri-state. Named once: the SDK parameter was
-# renamed to allow_default_egress, the wire key was not, and two places translate between
-# them (Egress.to_wire and compile_egress's raw-dict path).
+# The REST spelling this client SENDS for the egress tri-state. Named once because the
+# client parameter and the wire key have diverged and two places translate between them
+# (Egress.to_wire and compile_egress's raw-dict path).
+#
+# DELIBERATELY still "allow_internet", even though sandbox-api now has
+# allow_public_package_registries (sandbox-api#349) and every tier accepts it (measured
+# 2026-09-24). Do NOT "fix" this to the new key as a tidy-up — that couples a client-side
+# naming improvement to a deployment risk:
+#
+#   - sandbox-api keeps honouring allow_internet deliberately, for pinned SDKs exactly like
+#     this one (containers/egress.go: "the superseded one and still means exactly the same
+#     thing"; containers/models.go names "every pinned sandbox-sdk" as the reason).
+#   - A prod rollback to a pre-#349 build would 400 every create carrying the NEW key, while
+#     the old key keeps working against every build, reverted or not.
+#
+# Switching it is its own decision, gated on the prod rollback window closing — not on the
+# field being accepted. Until then this is the one spelling that is safe everywhere.
 _DEFAULT_EGRESS_WIRE_KEY = "allow_internet"
 
+# The current, honest client parameter name; it matches sandbox-api's field and the Snowsight
+# dialog copy ("Snowflake and public package registries"). The two older spellings below stay
+# accepted because they shipped.
+_EGRESS_LEVEL_PARAM = "allow_public_package_registries"
+
 
 @dataclass(frozen=True)
 class Egress:
@@ -87,8 +106,8 @@ class Egress:
 
     | level | how | reaches |
     |---|---|---|
-    | baseline | the default, or `allow_default_egress=True` | Snowflake, the cloud-storage stages, and ~43 package-manager hosts |
-    | closed | `allow_default_egress=False` / `Egress.only()` | Snowflake and its stages only |
+    | baseline | the default, or `allow_public_package_registries=True` | Snowflake, the cloud-storage stages, and ~43 package-manager hosts |
+    | closed | `allow_public_package_registries=False` / `Egress.only()` | Snowflake and its stages only |
     | granted | `external_access_integrations=(...)` | the above, plus whatever the EAI's network rules resolve to |
 
     **The baseline is not the internet.** It is a curated host set the platform
@@ -96,17 +115,30 @@ class Egress:
     list requires an External Access Integration whichever level you pick. A
     caller-supplied host list used to be the third option and is now retired.
 
-    `allow_internet` is the former name of `allow_default_egress` and still works, with a
-    DeprecationWarning. It was misleading in both directions: it never granted the whole
-    internet, and False does not stop egress because an EAI still grants.
+    **The parameter is `allow_public_package_registries`.** Two earlier spellings still work
+    and are deprecated — `allow_default_egress` and, before it, `allow_internet`. Setting more
+    than one to *different* values raises, since they are one control.
+
+    Neither older name survived contact with what the field does. `allow_internet` was wrong
+    in both directions: it never granted the internet (the baseline is a curated ~43-host set,
+    GET/HEAD only), and `False` does not stop egress because an EAI still grants.
+    `allow_default_egress` then named the value's *provenance* rather than what it grants, and
+    self-contradicts the moment the platform default changes — at which point
+    `default_egress=False` would *be* the default. The current name says what is granted.
+
+    Neither older name emits a DeprecationWarning yet. That is deliberate and not an
+    oversight: the warning would fire on construction, so adding it means migrating every
+    test and example that still uses an old name, for no behaviour change. It arrives with the
+    release that removes them.
 
     Example:
         egress = Egress()                                # baseline
         egress = Egress.only()                           # closed: nothing arbitrary
-        egress = Egress(allow_default_egress=False, external_access_integrations=("MY_EAI",))
+        egress = Egress(allow_public_package_registries=False,
+                        external_access_integrations=("MY_EAI",))
 
-    `allow_github` and `allow_pypi` are both **deprecated and inert**. `allow_internet` is
-    the only egress control. Public PyPI is already reachable via the package-managers
+    `allow_github` and `allow_pypi` are both **deprecated and inert**; the egress level is the
+    only control that does anything. Public PyPI is already reachable via the package-managers
     group, and the six GitHub/dbt hosts now need an External Access Integration like any
     other host outside that group. Both flags will be removed in a future release.
     """
@@ -118,8 +150,8 @@ class Egress:
     # baseline and disables the group flags below.
     allow_internet: bool | None = None
     # Deprecated and inert. It set EgressConfig.allow_egress_to_github_and_dbt, the six-host
-    # GitHub/dbt group, which the platform is removing — leaving allow_internet as the only
-    # egress control. Those hosts need an External Access Integration now. Setting it does
+    # GitHub/dbt group, which the platform is removing — leaving the egress level as the only
+    # control. Those hosts need an External Access Integration now. Setting it does
     # nothing and, unlike allow_pypi, does not even warn (see __new__); to_wire() no longer
     # sends it. Retained and still defaulting True, so existing callers keep constructing
     # without a TypeError and no value of it reads as meaningful; remove in a later major.
@@ -139,7 +171,25 @@ class Egress:
     # replaces. Appended last so positional Egress(None, True, False, (...)) callers are
     # unaffected. The WIRE key is still allow_internet — this is a client-side rename, so
     # no server change is needed and old and new SDKs interoperate.
+    #
+    # SUPERSEDED by allow_public_package_registries below. Kept working, not removed: it
+    # shipped in v0.2.1a1 / v0.2.2.dev1 / v0.2.2a2 / v0.2.2a3, so deleting it would break
+    # callers who adopted it.
     allow_default_egress: bool | None = None
+    # The current name, and the one to use. Matches sandbox-api's request field
+    # (allow_public_package_registries, sandbox-api#349) and the Snowsight dialog's wording,
+    # so the client, the wire contract and the UI finally agree on what this knob is called.
+    #
+    # Why the two names above are not it. "internet" was wrong in both directions: it never
+    # granted the internet (the baseline is ~43 curated hosts, GET/HEAD only) and False does
+    # not stop egress, because an EAI still grants. "default egress" then described the
+    # value's PROVENANCE rather than what it grants, and self-contradicts the moment the
+    # platform default changes — at which point "default_egress=False" would BE the default.
+    # This name says what is actually granted: access to public package registries.
+    #
+    # Appended last so positional Egress(None, True, False, (...), None) callers are
+    # unaffected. Tri-state exactly like the fields it supersedes.
+    allow_public_package_registries: bool | None = None
 
     def __post_init__(self) -> None:
         # A dataclass enforces no types, so Egress(allow_internet="false") kept the string and
@@ -148,6 +198,7 @@ class Egress:
         for name, nullable in (
             ("allow_internet", True),
             ("allow_default_egress", True),
+            ("allow_public_package_registries", True),
             ("allow_github", False),
             ("allow_pypi", False),
         ):
@@ -158,17 +209,21 @@ class Egress:
                 raise SandboxError(
                     f"Egress({name}=) must be True or False, got {type(value).__name__} {value!r}"
                 )
-        # Both spellings set and disagreeing is ambiguous, and picking one silently would
+        # Any two spellings set and disagreeing is ambiguous, and picking one silently would
         # apply an egress posture the caller did not ask for. Raise at the call instead.
-        if (
-            self.allow_internet is not None
-            and self.allow_default_egress is not None
-            and self.allow_internet != self.allow_default_egress
-        ):
+        # Checked pairwise across all THREE names, not just the newest pair: a caller
+        # mid-migration can easily have the oldest and newest both set.
+        spellings = [
+            ("allow_public_package_registries", self.allow_public_package_registries),
+            ("allow_default_egress", self.allow_default_egress),
+            ("allow_internet", self.allow_internet),
+        ]
+        given = [(n, v) for n, v in spellings if v is not None]
+        if len({v for _, v in given}) > 1:
+            shown = ", ".join(f"{n}={v!r}" for n, v in given)
             raise SandboxError(
-                "Egress(allow_internet=) and Egress(allow_default_egress=) disagree "
-                f"({self.allow_internet!r} vs {self.allow_default_egress!r}). They are the "
-                "same control — pass only allow_default_egress."
+                f"Egress spellings of the egress level disagree ({shown}). They are all the "
+                f"same control — pass only {_EGRESS_LEVEL_PARAM}."
             )
         # NOT warned on deliberately. The suite runs filterwarnings=error, so emitting a
         # DeprecationWarning here fails all 21 tests that construct Egress(allow_internet=)
@@ -194,7 +249,8 @@ class Egress:
     def only() -> Egress:
         """Close egress — ``Egress.only()``, with no arguments.
 
-        Sets ``allow_default_egress=False``, which withholds the platform baseline as well: no
+        Sets ``allow_public_package_registries=False``, which withholds the platform baseline as
+        well: no
         arbitrary internet host is reachable, not even the package-manager set the default
         mode grants. Snowflake and its stages stay reachable regardless — see the danger
         note below, which is why this is not described as total confinement.
@@ -203,7 +259,7 @@ class Egress:
         caller-supplied host list; to confine and then grant a specific host, pair
         confinement with an External Access Integration:
 
-            Egress(allow_default_egress=False, external_access_integrations=("MY_EAI",))
+            Egress(allow_public_package_registries=False, external_access_integrations=("MY_EAI",))
 
         !!! danger "Not an exfiltration boundary for Snowflake destinations"
             ``only()`` does **not** confine the sandbox to *just* a chosen set of hosts.
@@ -220,9 +276,9 @@ class Egress:
             restriction. See *Reachability is not credential scope* above and the
             ``Secret`` docs.
         """
-        # New spelling deliberately: only() must not emit a DeprecationWarning at a
-        # caller who never touched the old name.
-        return Egress(allow_default_egress=False)
+        # Current spelling deliberately: only() must not attribute a deprecated name to a
+        # caller who never typed one.
+        return Egress(allow_public_package_registries=False)
 
     @property
     def default_egress_allowed(self) -> bool | None:
@@ -232,6 +288,8 @@ class Egress:
         look "unset" to logic that checks the old one, which is the bug a plain alias
         would introduce.
         """
+        if self.allow_public_package_registries is not None:
+            return self.allow_public_package_registries
         if self.allow_default_egress is not None:
             return self.allow_default_egress
         return self.allow_internet
@@ -246,7 +304,11 @@ class Egress:
         if effective is not None:
             # Sent even when False: the platform reads an absent key as its permissive
             # default, so omitting it would silently discard a request to close egress.
-            # The key stays allow_internet — the rename is client-side only.
+            #
+            # EXACTLY ONE spelling goes on the wire. sandbox-api refuses a request carrying
+            # two spellings that disagree (containers/egress.go), so a client that sent both
+            # could produce a refusal that reads as a server bug. See
+            # _DEFAULT_EGRESS_WIRE_KEY for why that one spelling is still allow_internet.
             body[_DEFAULT_EGRESS_WIRE_KEY] = effective
         # Neither group flag is sent: the platform is removing the GitHub/dbt flag and already
         # reserved the one allow_pypi fed, so either would describe a grant that never happens.
@@ -302,8 +364,10 @@ def compile_egress(
     the two now coincide: the only meaningful field is the default-egress tri-state, whose
     default is the platform's own, so a default `Egress` serialises to nothing. A dict is
     taken as authored, since that path is the raw-wire escape hatch — except that
-    ``allow_default_egress`` is translated to the wire key, because a raw-dict caller who
-    used the name the docs now teach would otherwise have it silently ignored.
+    ``allow_public_package_registries`` and the older ``allow_default_egress`` are both
+    translated to the single wire key this client sends, because a raw-dict caller who used
+    the name the docs teach would otherwise have it silently ignored — and because sandbox-api
+    refuses a request that carries two disagreeing spellings of the same control.
     """
     if isinstance(egress, Egress):
         body = egress.to_wire()
@@ -312,18 +376,28 @@ def compile_egress(
     else:
         body = dict(egress)
         # A raw dict is otherwise passed through verbatim, which would make
-        # {"allow_default_egress": False} a silent no-op: the server sees no
-        # allow_internet key and applies its PERMISSIVE default, so a caller asking to
-        # close egress would get the baseline instead. Translate to the wire key rather
-        # than refuse, matching what the typed path accepts.
-        if "allow_default_egress" in body:
-            renamed = body.pop("allow_default_egress")
+        # {"allow_public_package_registries": False} or {"allow_default_egress": False} a
+        # silent no-op ON A CLIENT PATH THAT SENDS THE OLD KEY: the server would see no
+        # allow_internet key and apply its PERMISSIVE default, so a caller asking to close
+        # egress would get the baseline instead. Translate to the one wire key this client
+        # sends, rather than refuse, matching what the typed path accepts.
+        #
+        # EXACTLY ONE spelling may survive. sandbox-api refuses a request carrying two
+        # spellings that disagree, so collapsing them here turns a confusing server refusal
+        # into a local error naming the caller's own keys. Note allow_public_package_registries
+        # is BOTH a client name and a real wire key the server accepts — it is still collapsed
+        # onto _DEFAULT_EGRESS_WIRE_KEY so that one client cannot emit two spellings at once.
+        _level_aliases = ("allow_public_package_registries", "allow_default_egress")
+        for _alias in _level_aliases:
+            if _alias not in body:
+                continue
+            renamed = body.pop(_alias)
             existing = body.get(_DEFAULT_EGRESS_WIRE_KEY)
             if existing is not None and renamed is not None and existing != renamed:
                 raise SandboxError(
-                    f"egress dict sets both {_DEFAULT_EGRESS_WIRE_KEY!r} and "
-                    f"'allow_default_egress' to different values ({existing!r} vs "
-                    f"{renamed!r}). They are the same control — pass one."
+                    f"egress dict sets both {_DEFAULT_EGRESS_WIRE_KEY!r} and {_alias!r} to "
+                    f"different values ({existing!r} vs {renamed!r}). They are the same "
+                    f"control — pass one, and {_EGRESS_LEVEL_PARAM!r} is the current name."
                 )
             if renamed is not None:
                 body[_DEFAULT_EGRESS_WIRE_KEY] = renamed

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/src/snowflake/sandbox/sync_client.py

@@ -149,7 +149,7 @@ def _raise_if_stream_terminated(abort: StreamAbort) -> None:
 
 
 class Sandbox(_FilesMixin, _SandboxState):
-    """A Snowflake sandbox container (sync API).
+    """A Cortex Sandbox (sync API).
 
     `create()` is the factory, and the only creation path -- ``Sandbox(...)`` raises.
     Reconnect to an existing sandbox with ``Sandbox.connect(name)`` / `get_sandbox` /
@@ -768,12 +768,26 @@ class Sandbox(_FilesMixin, _SandboxState):
             return
         self._wait_until_ready(timeout=timeout)
 
-    def logs(self, *, tail: int = 0, since_ts_ms: int = 0) -> str:
+    def logs(
+        self, *, tail: int = 0, since_ts_ms: int = 0, source: str | None = None, pid: int = 0
+    ) -> str:
         """Return the container's captured stdout and stderr as a string.
 
         `tail` limits to the last N lines. Only meaningful for command containers
         (created with `command=`).
 
+        `source` selects which stream to read, defaulting to the server's `all` -- the
+        entrypoint plus the `command=` process:
+
+        - ``"exec"`` -- what the commands you ran with `exec()` printed, which no other
+          source includes. `exec()` also returns that output directly; this is how you
+          read it again afterwards.
+        - ``"base"`` / ``"managed"`` -- one of the two long-lived streams on its own.
+
+        `pid` narrows an exec read to one producer. Without it every exec is merged and
+        the returned text carries no per-line attribution; `pid=` is how you read one
+        command's output on its own.
+
         SDK-internal protocol markers are suppressed: the in-sandbox runner reports a
         run's outcome as `__SANDBOX_RESULT__<b64>` on stdout and the session daemon
         reports replies as `__SANDBOX_REPLY__<...>`, so both land in the log stream
@@ -784,10 +798,13 @@ class Sandbox(_FilesMixin, _SandboxState):
         Example:
             output = sb.logs(tail=100)
             print(output)
+
+            # What the commands you ran with `exec()` printed.
+            print(sb.logs(source="exec"))
         """
         fetch = _logs_overfetch(tail)
         while True:
-            raw = self._logs_raw(tail=fetch, since_ts_ms=since_ts_ms)
+            raw = self._logs_raw(tail=fetch, since_ts_ms=since_ts_ms, source=source, pid=pid)
             raw_count = len(raw.split("\n")) if raw else 0
             visible = _visible_log_lines(raw)
             if tail <= 0 or len(visible) >= tail:
@@ -805,7 +822,9 @@ class Sandbox(_FilesMixin, _SandboxState):
             visible = visible[-tail:]
         return "\n".join(visible)
 
-    def _logs_raw(self, *, tail: int = 0, since_ts_ms: int = 0) -> str:
+    def _logs_raw(
+        self, *, tail: int = 0, since_ts_ms: int = 0, source: str | None = None, pid: int = 0
+    ) -> str:
         """The log snapshot EXACTLY as the server returns it, markers included.
 
         Internal consumers that read the runner's or daemon's stdout protocol
@@ -824,6 +843,14 @@ class Sandbox(_FilesMixin, _SandboxState):
             q.append(f"tail={tail}")
         if since_ts_ms:
             q.append(f"since={since_ts_ms}")
+        # Forwarded verbatim rather than validated here: the server owns the vocabulary
+        # and names the valid values in its rejection, so a client-side allowlist would go
+        # stale as soon as a source is added and would turn a 400 that explains itself
+        # into one that does not.
+        if source:
+            q.append(f"source={source}")
+        if pid:
+            q.append(f"pid={pid}")
         path = f"containers/{self._id}/logs" + ("?" + "&".join(q) if q else "")
         try:
             resp = self._transport.request("GET", path, retry_500_delays=DEFAULT_LOGS_500_DELAYS_S)

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4/src/snowflake_sandbox_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-sandbox-python
-Version: 0.2.2a3
+Version: 0.2.2a4
 Summary: Snowflake sandboxes — Python SDK and CLI.
 Author: Snowflake, Inc.
 License: 

{snowflake_sandbox_python-0.2.2a3 → snowflake_sandbox_python-0.2.2a4}/tests/test_docs_references.py

@@ -563,3 +563,289 @@ def test_surface_table_excludes_error_page_types_by_type_not_by_name() -> None:
             assert f"`{name}`" not in section, (
                 f"{name} is covered by the error page but also appears in the surface table"
             )
+
+
+# ---------------------------------------------------------------------------
+# Content gate: the class of defect `--check` structurally cannot see
+# ---------------------------------------------------------------------------
+#
+# The drift gate compares a committed page against fresh generator output,
+# SHA-normalised. That proves the two agree; it does not prove either is right.
+# Prose hardcoded inside a generator is therefore checked against its own output
+# and always passes -- and 41% of generate_docs_reference.py and 16% of
+# generate_cli_reference.py is hardcoded prose.
+#
+# Five strings reached customer-facing pages that way, each found by reading:
+#
+#   prod_snowhouse as the example connection name          (fixed in #431)
+#   sandbox-api#337/#226 cited in an idle_suspend docstring (fixed in #432)
+#   SMASON / ENGINEER as sample output                      (already pinned below)
+#   RELATED_TOPICS grown to 16 entries                      (fixed in #433/#434)
+#   "a Snowflake sandbox", a product that does not exist    (fixed in #444)
+#
+# These assertions run over the EMITTED pages rather than generator source, which
+# is the point: two of those five originated in docstrings and three in generator
+# literals, and a check on either source alone would miss the other. Moving a
+# string between a docstring and a generator cannot evade this.
+
+_GENERATED_PAGES = (
+    "docs/generated/sdk-reference.mdx",
+    "docs/generated/cli-reference.mdx",
+    "docs/generated/error-reference.mdx",
+)
+
+# (regex, why it must never appear). Matched case-insensitively.
+#
+# Every pattern is a literal or an explicitly escaped regex. An unescaped dot is
+# not a cosmetic slip here: `snowflake.sandbox` matches 13 strings on these pages
+# where `snowflake\.sandbox` matches 9, because the extra four are
+# `snowflake-sandbox` in the DO-NOT-EDIT banner of every page. A pattern written
+# that way fails on a clean tree.
+_BANNED_IN_GENERATED = (
+    (
+        r"snowflake sandbox(?:es)?\b",
+        'the product is "Cortex Sandboxes"; "Snowflake Sandboxes" is only the reserved '
+        "public-preview fallback and must not be published before that decision is taken",
+    ),
+    (
+        r"cortex cloud sandboxes",
+        'a name explicitly rejected in the naming decision -- "cloud sandbox" is CoCo\'s, '
+        "so the qualifier recreates the collision it was meant to remove",
+    ),
+    (
+        r"snowhouse",
+        "Snowhouse is Snowflake's internal production account; it must never appear as a "
+        'customer-facing example (use "prod_account" or similar)',
+    ),
+    (
+        r"sandbox-(?:api|sdk)#\d+",
+        "internal issue references do not belong in customer prose -- state the behaviour, "
+        "or leave it out until it is settled",
+    ),
+    (
+        r"\bsmason\b",
+        "a real username -- sample output must use a placeholder such as MY_USER",
+    ),
+    (
+        r"\bengineer\b",
+        "a real role name from a developer's account -- sample output must use a "
+        "placeholder such as MY_ROLE",
+    ),
+)
+
+
+def _generated_pages() -> list[tuple[str, str]]:
+    root = Path(__file__).resolve().parent.parent
+    pages = []
+    for rel in _GENERATED_PAGES:
+        path = root / rel
+        assert path.is_file(), (
+            f"{rel} not found at {path}. If the generated pages moved, update "
+            "_GENERATED_PAGES -- otherwise every content check below passes vacuously."
+        )
+        pages.append((rel, path.read_text(encoding="utf-8")))
+    return pages
+
+
+def test_the_generated_pages_are_present_and_substantial() -> None:
+    """Guard the guard, the same way `test_docs_directory_is_present` does.
+
+    A content assertion that reads an empty or missing file reports success. That is
+    the worse failure than a wrong string, because it is silent: the gate goes on
+    passing while checking nothing. So establish the corpus exists and is real
+    before anything below relies on it.
+    """
+    pages = _generated_pages()
+    assert len(pages) == 3, "expected three generated pages"
+    for rel, text in pages:
+        assert len(text) > 2_000, (
+            f"{rel} is only {len(text)} bytes -- too short to be a real reference page. "
+            "Either generation failed or the path is wrong; either way the checks below "
+            "are not checking anything."
+        )
+
+
+def test_generated_pages_carry_no_banned_string() -> None:
+    """Wrong names, internal identifiers and personal information, all previously shipped.
+
+    Each pattern here corresponds to a string that actually reached a customer-facing
+    page, not a hypothetical. The drift gate passed every one of them.
+    """
+    offenders: list[str] = []
+    for rel, text in _generated_pages():
+        for pattern, reason in _BANNED_IN_GENERATED:
+            for hit in set(re.findall(pattern, text, re.IGNORECASE)):
+                offenders.append(f"  {rel}: {hit!r}\n      {reason}")
+
+    assert not offenders, "banned strings in generated pages:\n" + "\n".join(sorted(offenders))
+
+
+def test_the_banned_patterns_spare_the_protected_identifiers() -> None:
+    """The distribution name, the import path and the repo name all contain "sandbox".
+
+    Docs paths and prose carry the product name; code identifiers never do. So a
+    banned-string pattern that is slightly too greedy breaks the build on a clean
+    tree rather than catching anything -- `snowflake-sandbox-sdk@<sha>` sits in the
+    DO-NOT-EDIT banner of all three pages, so it is the first thing an over-broad
+    pattern hits.
+
+    This asserts the gate above is compatible with those three identifiers, using
+    strings taken from the real pages rather than invented ones.
+    """
+    protected = (
+        "snowflake-sandbox-python",
+        "snowflake.sandbox",
+        "{/* DO NOT EDIT — generated from snowflake-sandbox-sdk@abc1234.",
+        "from snowflake.sandbox import Sandbox",
+        "pip install snowflake-sandbox-python",
+    )
+    for sample in protected:
+        for pattern, _ in _BANNED_IN_GENERATED:
+            assert not re.search(pattern, sample, re.IGNORECASE), (
+                f"pattern {pattern!r} matches the protected identifier {sample!r}. "
+                "Tighten the pattern -- an unescaped dot or a missing word boundary will "
+                "fire on every page's banner."
+            )
+
+
+# The Cortex Sandboxes doc set, in reading order: overview, the two entry paths,
+# conceptual grounding, tutorials, then the references and support pages. Every page's
+# Related Content is this list minus its own slug, so the right-hand pane is identical
+# and complete across the set.
+#
+# The eight individual tutorials are deliberately absent. They are represented by their
+# landing page, `overview-tutorials`, whose body already indexes all eight. A page that
+# links one tutorial and not its siblings is making an editorial claim nobody made.
+_CANONICAL_RELATED_TOPICS = (
+    "overview",
+    "sdk-quickstart",
+    "cli-quickstart",
+    "concepts-and-security",
+    "connections",
+    "overview-tutorials",
+    "sdk-reference",
+    "cli-reference",
+    "error-reference",
+    "troubleshooting",
+    "limitations-and-faq",
+)
+
+_OWN_SLUG = {
+    "docs/generated/sdk-reference.mdx": "sdk-reference",
+    "docs/generated/cli-reference.mdx": "cli-reference",
+    "docs/generated/error-reference.mdx": "error-reference",
+}
+
+
+def test_related_topics_matches_the_canonical_list_exactly() -> None:
+    """Related Content must be the canonical doc set minus the page's own slug.
+
+    This replaces a `3 <= len(entries) <= 7` range check. The range was added after
+    Related Content ballooned to 16 entries and a blind copy then reverted the fix, so
+    it was built to catch *growth* -- and it did. What it could not see was omission.
+    Under it, the three generated pages carried bespoke 5-7 entry lists that between
+    them were missing 14 canonical links, and every page but one omitted the tutorials
+    landing page while linking a single individual tutorial instead. All of it passed.
+
+    So assert the exact sequence. That catches four failure modes the range could not:
+    a missing page, an extra one, an individual-tutorial link, and a reordering.
+
+    Pinning is deliberate here, and is the opposite of the choice made in
+    `test_the_egress_key_fields_table_names_only_real_parameters` a few lines down --
+    worth explaining, because the two look contradictory. The egress table documents an
+    evolving API, where the set of parameter names legitimately changes and pinning
+    would fight ordinary development; the invariant there is only that every documented
+    name still exists. This list is not evolving incidentally: it *is* the spec. Adding
+    a page to the doc set is a deliberate act that should update this tuple once, in one
+    place, and fail every page that has not caught up.
+
+    Covers the three generated pages only, since they are the ones this repo owns. The
+    16 hand-authored pages live in snowflake-prod-docs and are not reachable from here.
+    """
+    for rel, text in _generated_pages():
+        own = _OWN_SLUG.get(rel)
+        assert own is not None, (
+            f"{rel} has no entry in _OWN_SLUG. A generated page was added without "
+            "recording which slug it must omit from its own Related Content."
+        )
+
+        block = text.split("<RelatedTopics>", 1)
+        assert len(block) == 2, f"{rel} has no <RelatedTopics> block"
+        entries = [
+            line
+            for line in block[1].split("</RelatedTopics>", 1)[0].splitlines()
+            if line.startswith("- [")
+        ]
+        assert entries, (
+            f"{rel} has a <RelatedTopics> block with no `- [` entries -- the block shape "
+            "changed, and this check is now passing without checking anything"
+        )
+
+        slugs = []
+        for line in entries:
+            match = re.search(
+                r"\]\(/LIMITEDACCESS/developer-guide/cortex-sandboxes/([^)]+)\)", line
+            )
+            assert match is not None, (
+                f"{rel}: could not parse a docs slug out of {line!r}. Related Content "
+                "links must be absolute under the Cortex Sandboxes base path."
+            )
+            slugs.append(match.group(1))
+
+        expected = [slug for slug in _CANONICAL_RELATED_TOPICS if slug != own]
+        assert slugs == expected, (
+            f"{rel} Related Content does not match the canonical list.\n"
+            f"  missing:   {sorted(set(expected) - set(slugs))}\n"
+            f"  unexpected:{sorted(set(slugs) - set(expected))}\n"
+            f"  got order: {slugs}\n"
+            f"  expected:  {expected}\n"
+            "Fix the RELATED_TOPICS block in the generator, not the page. If a page was "
+            "genuinely added to or removed from the doc set, update "
+            "_CANONICAL_RELATED_TOPICS -- every page then updates with it."
+        )
+
+
+def test_the_egress_key_fields_table_names_only_real_parameters() -> None:
+    """The egress table is hardcoded in the generator, so a rename can orphan it silently.
+
+    This already happened: `test_common_operations_table_names_only_real_api` was added
+    because "the egress section came to assert a parameter that had been renamed" (#392),
+    and the same section was rewritten again when `allow_default_egress` became
+    `allow_public_package_registries` (#445).
+
+    Neither the drift gate nor a banned-string list can catch that. The gate compares the
+    generator against its own output, and a stale parameter name is not a banned string --
+    it is a name that simply no longer exists. So check the table against the dataclass.
+
+    Deliberately not a list of expected names. Pinning the contents would fail on every
+    ordinary edit, and the failure being guarded against is a name that has stopped
+    existing, not a set that has changed size.
+    """
+    import dataclasses
+
+    from snowflake.sandbox import Egress
+
+    page = (Path(__file__).resolve().parent.parent / "docs/generated/sdk-reference.mdx").read_text()
+
+    assert "### Egress" in page, "the Egress section is gone from the reference"
+    section = page.split("### Egress", 1)[1].split("\n### ", 1)[0]
+    assert "Key fields:" in section, (
+        "the Egress section no longer has a Key fields table -- if it moved, update this "
+        "test, because otherwise nothing checks those parameter names against the dataclass"
+    )
+    table = section.split("Key fields:", 1)[1]
+
+    documented = {m.group(1) for m in re.finditer(r"^\|\s*`([a-z_]+)`\s*\|", table, re.MULTILINE)}
+    assert documented, (
+        "no parameter rows parsed out of the Key fields table -- the table shape changed, "
+        "and this check is now passing without checking anything"
+    )
+
+    real = {f.name for f in dataclasses.fields(Egress)}
+    orphaned = sorted(documented - real)
+    assert not orphaned, (
+        f"the egress Key fields table documents {orphaned}, which are not fields on Egress. "
+        "A parameter was renamed or removed and the hardcoded table in "
+        "generate_docs_reference.py was not updated with it -- the exact failure that "
+        "produced #392 and #445."
+    )