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

snowflake/sandbox/types.py

@@ -0,0 +1,193 @@
+"""Public data types for ``snowflake.sandbox``.
+
+Kept import-cheap (stdlib + ``typing`` only — no httpx, no pydantic) so the
+``__init__`` lazy loader can pull these in without breaking the import-time
+budget.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Literal, NamedTuple, get_args
+
+__all__ = [
+    "ExecResult",
+    "StreamLine",
+    "MemoryTier",
+    "SandboxStatus",
+    "SANDBOX_STATUSES",
+    "StreamName",
+    "RunStatus",
+    "JobStatus",
+    "TERMINAL_STATUSES",
+    "FileInfo",
+    "FileWatchEventType",
+    "FileWatchEvent",
+]
+
+
+MemoryTier = Literal["1g", "4g", "8g", "16g", "32g", "64g"]
+"""Snowflake memory tiers — a closed enum exposed at the SDK surface."""
+
+SandboxStatus = Literal["pending", "ready", "dead", "failed", "unknown"]
+"""Sandbox lifecycle state, mapped from the server's own vocabulary.
+
+``client._parse_status`` maps the server's word onto one of these five:
+
+| this value | server words that map to it |
+| --- | --- |
+| ``pending`` | ``starting``, ``pending``, ``not_started``, ``resuming``, ``suspending`` |
+| ``ready`` | ``running``, ``ready``, ``suspended`` |
+| ``dead`` | ``stopped``, ``crashed``, ``dead``, ``stopping`` |
+| ``failed`` | ``failed`` |
+| ``unknown`` | ``unknown``, anything else |
+
+Both terminal values mean "this sandbox will do no more work; make a new one".
+They differ only in WHEN it ended: ``failed`` is an async create (202 path) that
+hit a server-side error — platform failure, bad image — so no container ever ran,
+while ``dead`` is one that ran and then ended.
+
+Neither says WHETHER something went wrong, because ``dead`` covers a deliberate
+stop and a crash alike. `Sandbox.server_status` keeps the server's own word, so
+``dead`` + ``stopped`` and ``dead`` + ``crashed`` are distinguishable there — and
+``snow sandbox list`` shows it in its REASON column.
+
+A transition (``resuming``, ``suspending``) is ``pending`` rather than ``ready``: an exec
+would work -- every exec re-drives StartApp, which is what completes a resume -- but it can
+block for seconds, and a status a caller checks BEFORE acting must not promise a sandbox is
+servable when it is not yet. `Sandbox.server_status` keeps the transition's own word, so it
+stays visible without ``status`` over-promising.
+
+``unknown`` covers two cases that are the same answer to the caller: the server said
+``unknown`` (a state it declines to name) or it said a word this SDK does not
+recognize. Only the second warns (`exceptions.SandboxContractWarning`) — advising an
+SDK upgrade for a word the server chose deliberately is noise. Neither is collapsed
+into ``ready``, which is what made a contract drift read as a healthy sandbox.
+"""
+
+SANDBOX_STATUSES: frozenset[str] = frozenset(get_args(SandboxStatus))
+"""The `SandboxStatus` values, as a runtime-checkable set.
+
+ Derived from the `SandboxStatus` Literal with ``get_args`` rather than written out
+again, so the two can never drift. `Literal` is a static-only construct -- nothing
+enforces it at runtime -- so callers that need to *validate* a caller-supplied
+status (rather than merely annotate one) need this.
+
+These are the SDK's mapped statuses, not the server's raw vocabulary: a caller
+filtering by state wants ``ready``, not the server's ``running``. The mapping is
+one-to-many (``ready`` <- running|ready|suspended, ``pending`` <- starting|pending|
+not_started|resuming|suspending, ``dead`` <- crashed|stopped|dead|stopping), which is
+why a single ``?status=`` query param cannot express it and why ``list_sandboxes``
+filters client-side. The authoritative table is ``_wire._SERVER_STATUS``.
+
+Every value here is a legitimate filter input, including ``failed``, which describes
+how a status was *arrived at* rather than what the server said: it is produced only by
+the async-create (202) path, where a server-side error makes the create terminal
+without any container running.
+
+``unknown`` is a filter input for two different reasons, and both are answerable
+because ``list_sandboxes`` filters locally on the mapped value: the server has its own
+``unknown`` (a state it declines to name), and the SDK produces ``unknown`` for a word
+it does not recognize. So ``status="unknown"`` answers both "which sandboxes is the
+server unsure about" and the occasionally urgent "which is this SDK failing to parse",
+e.g. after a server upgrade.
+
+None of that splits the set: a separate FILTERABLE_STATUSES would have been right when
+the filter was applied server-side, and would now wrongly reject answerable queries.
+"""
+
+RunStatus = Literal["succeeded", "failed", "timed_out"]
+"""Terminal outcome of a detached run (`RunResult.status`) -- the states a
+``get``/``wait`` resolves to. A closed enum; unknown wire values are clamped to
+``failed`` at the parse boundary."""
+
+JobStatus = Literal["succeeded", "failed", "running"]
+"""Lifecycle status reported by `Job.status()` / `SyncJob.status()`: a finished
+run's ``succeeded``/``failed``, or ``running`` while still live. ``timed_out`` is a
+``get()`` outcome, not a live status, so it is not a member here."""
+
+StreamName = Literal["stdout", "stderr"]
+"""SSE stream channel for a streaming exec frame."""
+
+TERMINAL_STATUSES: frozenset[str] = frozenset({"dead", "failed"})
+"""Statuses after which a container produces no further output.
+
+``failed`` is added for the async create (202) path: a server-side error
+makes the create terminal without the container ever being live.
+
+Lives here rather than in ``client`` so ``log_stream`` can read it without an
+import cycle.
+"""
+
+
+class ExecResult(NamedTuple):
+    """Result of a non-streaming `Sandbox.exec()`.
+
+    ``stdout`` / ``stderr`` are decoded strings when ``text=True`` (the
+    default). ``exit_code`` is the in-container process exit. ``elapsed_ms``
+    is wall-clock time on the server side, not including network round-trip.
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int
+    elapsed_ms: int
+
+
+class StreamLine(NamedTuple):
+    """One logical line yielded by `Sandbox.exec_stream()`.
+
+    ``data`` has its trailing ``\\n`` stripped. ``stream`` indicates which
+    channel (``"stdout"`` or ``"stderr"``) the line came from.
+    """
+
+    stream: StreamName
+    data: str
+
+
+class FileInfo(NamedTuple):
+    """Metadata for one path, returned by `Sandbox.list_files()` / `.stat()`.
+
+    Mirrors Modal's ``Sandbox.filesystem.stat`` shape. Both producers are
+    implemented (``files.py`` runs an in-container ``python3`` helper over
+    ``exec``); ``modified_at`` is a Unix epoch (seconds, UTC) or ``None`` when the
+    server did not report it.
+    """
+
+    path: str
+    is_dir: bool
+    size_bytes: int
+    modified_at: float | None = None
+
+
+class FileWatchEventType(StrEnum):
+    """Coarse change class for a `Sandbox.watch()` event.
+
+    Mirrors Modal's ``FileWatchEventType``. The sandbox observes raw Linux
+    ``inotify(7)`` masks and maps them onto this small enum — several inotify
+    bits collapse to one class (e.g. ``IN_MODIFY`` and ``IN_CLOSE_WRITE`` both
+    read as `Modify`; ``IN_CREATE`` and ``IN_MOVED_TO`` both as `Create`). A
+    mask that maps to nothing meaningful surfaces as `Unknown` rather than being
+    dropped, so a contract drift is visible instead of silent.
+
+    ``str``-valued so it compares equal to its wire string and JSON-serializes
+    cleanly.
+    """
+
+    Unknown = "Unknown"
+    Access = "Access"
+    Create = "Create"
+    Modify = "Modify"
+    Delete = "Delete"
+
+
+class FileWatchEvent(NamedTuple):
+    """One filesystem-change event yielded by `Sandbox.watch()`.
+
+    Mirrors Modal's ``FileWatchEvent``: ``paths`` are the absolute in-sandbox
+    path(s) the change concerns (usually one), and ``type`` is the coarse
+    `FileWatchEventType`.
+    """
+
+    paths: list[str]
+    type: FileWatchEventType