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

snowflake/sandbox/_files_mixin.py

@@ -0,0 +1,280 @@
+"""The file-transfer / filesystem method group mixed into ``AsyncSandbox``.
+
+These are the thin ``async`` wrappers the client exposes over the filesystem
+mechanisms that live in their own modules (``files`` for the ``/files`` byte
+route, ``_fs_ops`` for the exec-driven directory ops, ``_watch`` for the inotify
+watcher). They were byte-identical delegators sitting inline on ``AsyncSandbox``;
+holding them here keeps the file-ops surface in one place. ``Sandbox`` carries the
+same surface via the sync twin ``_sync_files_mixin._FilesMixin``.
+
+Not a public base class: an implementation detail of the two clients, inherited by
+``AsyncSandbox`` (and its sync counterpart), never exposed on its own. It performs
+no I/O itself — every method defers to the module that owns the mechanism — so it
+holds no transport and imports nothing from the package at runtime.
+
+The delegate functions (``files.upload_file(sandbox: AsyncSandbox, ...)`` etc.) are
+typed against the concrete client, so each call narrows ``self`` with a
+``cast`` — a type-checker-only no-op: at run time ``self`` already *is* an
+``AsyncSandbox``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Callable, Sequence
+    from pathlib import Path
+
+    from snowflake.sandbox._transport import Transport
+    from snowflake.sandbox._upload_plan import UploadPlan
+    from snowflake.sandbox.client import AsyncSandbox
+    from snowflake.sandbox.types import FileInfo, FileWatchEvent, FileWatchEventType
+
+__all__ = ["_FilesMixin"]
+
+
+class _FilesMixin:
+    """File-transfer and filesystem methods shared into ``AsyncSandbox``.
+
+    ``_transport`` is set by the client's own ``__init__``; it is declared here so
+    the delegating methods type-check against it, mirroring ``_SandboxState``.
+    """
+
+    _transport: Transport
+
+    # ----- file I/O ---------------------------------------------------
+
+    async def upload_file(self, local: str | Path, remote: str) -> None:
+        """Upload a local file into the running sandbox.
+
+        Raises the standard-library ``FileNotFoundError`` if ``local`` does not
+        exist (it is a local-filesystem miss, not a sandbox error).
+
+        Example:
+            await sb.upload_file("./data.csv", "/app/data.csv")
+        """
+        from snowflake.sandbox.files import upload_file
+
+        await upload_file(cast("AsyncSandbox", self), local, remote, transport=self._transport)
+
+    async def upload_dir(
+        self,
+        local_dir: str | Path,
+        remote_dir: str,
+        *,
+        exclude: list[str] | None = None,
+        include: list[str] | None = None,
+        allow_credential_files: list[str] | None = None,
+        dry_run: bool = False,
+        on_file: Callable[[int, int, str], None] | None = None,
+    ) -> UploadPlan:
+        """Upload a local directory into the running sandbox and report what it sent.
+
+        The directory's *contents* land at ``remote_dir`` -- ``upload_dir("./site",
+        "/app")`` puts ``site/index.html`` at ``/app/index.html``, as ``cp -r site/.
+        /app`` would. Build output, VCS state and credential-shaped files are left
+        behind by default; the returned `UploadPlan` says what was sent and, through
+        ``skipped``, why anything else was not.
+
+        Note:
+            There is no bulk route, so this is one request per file and the
+            per-file `MAX_FILE_BYTES` ceiling still applies -- an oversize file is
+            refused before the first byte is sent, so a tree never half-uploads.
+            ``dry_run=True`` sends nothing and so raises nothing: it returns the plan
+            with any offenders listed in ``plan.oversized``. Mount a stage
+            (`StageMount`) for bulk data. Symlinks are never followed, in either
+            direction, and appear in `plan.skipped` as `symlink-dir` /
+            `symlink-file` rather than vanishing silently. An empty directory is not
+            uploaded -- there is no file to create it under -- and is reported as
+            `empty-dir`.
+
+        Example:
+            plan = await sb.upload_dir("./project", "/app", exclude=["*.csv"])
+            print(f"sent {plan.file_count} files, skipped {plan.skipped_by_reason()}")
+        """
+        from snowflake.sandbox.files import upload_dir
+
+        return await upload_dir(
+            cast("AsyncSandbox", self),
+            local_dir,
+            remote_dir,
+            exclude=exclude,
+            include=include,
+            allow_credential_files=allow_credential_files,
+            dry_run=dry_run,
+            on_file=on_file,
+            transport=self._transport,
+        )
+
+    async def download_file(self, remote: str, local: str | Path) -> None:
+        """Download a file from the running sandbox to a local path.
+
+        Example:
+            await sb.download_file("/app/output.csv", "./output.csv")
+        """
+        from snowflake.sandbox.files import download_file
+
+        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.
+
+        Example:
+            await sb.stage_put("./results.parquet", "MY_STAGE/results.parquet")
+        """
+        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.
+
+        Example:
+            await sb.stage_get("MY_STAGE/model.pkl", "/app/model.pkl")
+        """
+        from snowflake.sandbox.files import stage_get
+
+        await stage_get(cast("AsyncSandbox", self), stage_path, local, transport=self._transport)
+
+    # ----- filesystem (Modal Sandbox.filesystem.*, flattened) ---------
+    #
+    # Matches the upload_file/download_file/stage_put/stage_get convention
+    # above: flat on Sandbox, not nested under a `.filesystem` sub-object.
+    # read/write ride the /files byte route; list/stat/make_directory/remove run
+    # a python3 helper in-container over exec (the /files route transfers bytes
+    # only). watch has no backend and raises. See files.py, _fs_ops.py, _watch.py.
+
+    async def list_files(self, path: str) -> Sequence[FileInfo]:
+        """List files and directories at `path` inside the sandbox.
+
+        Example:
+            entries = await sb.list_files("/app")
+            for entry in entries:
+                print(entry.path, entry.size_bytes, entry.is_dir)
+        """
+        from snowflake.sandbox._fs_ops import list_files
+
+        return await list_files(cast("AsyncSandbox", self), path, transport=self._transport)
+
+    async def make_directory(
+        self, path: str, *, create_parents: bool = False, parents: bool | None = None
+    ) -> None:
+        """Create a directory inside the sandbox.
+
+        Args:
+            path: Absolute path to the directory to create.
+            create_parents: If True, create parent directories as needed.
+            parents: Alias for `create_parents` (Modal parity). If both are
+                specified, `parents` takes precedence.
+
+        Example:
+            await sb.make_directory("/app/output", create_parents=True)
+        """
+        from snowflake.sandbox._fs_ops import make_directory
+
+        # parents= is the Modal name; create_parents= is ours. parents wins if set.
+        effective = parents if parents is not None else create_parents
+        await make_directory(
+            cast("AsyncSandbox", self), path, create_parents=effective, transport=self._transport
+        )
+
+    async def read_text(self, path: str, *, encoding: str = "utf-8") -> str:
+        """Read a text file from the sandbox and return its contents.
+
+        A bad ``encoding`` surfaces the standard-library ``LookupError`` (unknown
+        codec) or ``UnicodeDecodeError`` (bytes that do not decode under it);
+        neither is wrapped in ``SandboxError``.
+
+        Example:
+            content = await sb.read_text("/app/output.txt")
+        """
+        from snowflake.sandbox.files import read_text
+
+        return await read_text(
+            cast("AsyncSandbox", self), path, encoding=encoding, transport=self._transport
+        )
+
+    async def read_bytes(self, path: str) -> bytes:
+        """Read a binary file from the sandbox and return its contents.
+
+        Example:
+            data = await sb.read_bytes("/app/output.bin")
+        """
+        from snowflake.sandbox.files import read_bytes
+
+        return await read_bytes(cast("AsyncSandbox", self), path, transport=self._transport)
+
+    async def write_text(self, path: str, data: str, *, encoding: str = "utf-8") -> None:
+        """Write a text string to a file inside the sandbox.
+
+        A bad ``encoding`` surfaces the standard-library ``LookupError`` (unknown
+        codec) or ``UnicodeEncodeError`` (characters that do not encode under it);
+        neither is wrapped in ``SandboxError``.
+
+        Example:
+            await sb.write_text("/app/config.json", '{"key": "value"}')
+        """
+        from snowflake.sandbox.files import write_text
+
+        await write_text(
+            cast("AsyncSandbox", self), path, data, encoding=encoding, transport=self._transport
+        )
+
+    async def write_bytes(self, path: str, data: bytes) -> None:
+        """Write bytes to a file inside the sandbox.
+
+        Example:
+            await sb.write_bytes("/app/model.pkl", model_bytes)
+        """
+        from snowflake.sandbox.files import write_bytes
+
+        await write_bytes(cast("AsyncSandbox", self), path, data, transport=self._transport)
+
+    async def stat(self, path: str) -> FileInfo:
+        """Return metadata for a file or directory inside the sandbox.
+
+        Example:
+            info = await sb.stat("/app/output.txt")
+            print(info.size_bytes)
+        """
+        from snowflake.sandbox._fs_ops import stat as _stat
+
+        return await _stat(cast("AsyncSandbox", self), path, transport=self._transport)
+
+    async def remove(self, path: str, *, recursive: bool = False) -> None:
+        """Remove a file or directory inside the sandbox.
+
+        Example:
+            await sb.remove("/app/temp", recursive=True)
+        """
+        from snowflake.sandbox._fs_ops import remove
+
+        await remove(
+            cast("AsyncSandbox", self), path, recursive=recursive, transport=self._transport
+        )
+
+    def watch(
+        self,
+        path: str,
+        *,
+        filter: Sequence[FileWatchEventType] | None = None,
+        recursive: bool = False,
+        timeout: float | None = None,
+    ) -> AsyncIterator[FileWatchEvent]:
+        """Stream filesystem-change events under `path` as an async iterator.
+
+        Example:
+            async for event in sb.watch("/app"):
+                print(event.type, event.paths)
+        """
+        from snowflake.sandbox._watch import watch
+
+        return watch(
+            cast("AsyncSandbox", self),
+            path,
+            filter=filter,
+            recursive=recursive,
+            timeout=timeout,
+            transport=self._transport,
+        )

snowflake/sandbox/_fs_ops.py

@@ -0,0 +1,304 @@
+"""Directory ops for ``AsyncSandbox``, over an in-container ``python3`` helper.
+
+One of the three separate mechanisms that reach a sandbox filesystem, split out of
+``files.py`` because none of them shares a route, a channel or — as below — path
+semantics with the others. `files` keeps the ``/files`` byte route; `_watch` the
+change monitor.
+
+``list_files`` / ``stat`` / ``make_directory`` / ``remove``
+run a tiny ``python3`` helper in the container over ``exec``, because the
+``/files`` route transfers bytes only: the runtime exposes no list/stat/mkdir/rm
+endpoint. ``exec`` already runs everything as ``python3`` (see
+``client._cmd_to_code``), so this adds no dependency the SDK did not already
+require. They are ordinary in-container filesystem calls, not the ``/files``
+HTTP surface. **Path handling differs from the byte transfers in `files`:** the byte
+helpers require an absolute path (``files._require_absolute``), but these directory ops
+do not — a relative path is passed through to the in-container helper and
+resolves against the exec working directory, so prefer absolute paths here too
+to avoid depending on that (unspecified) default.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from snowflake.sandbox._runtime._fs_helper import _FS_HELPER_PREAMBLE
+from snowflake.sandbox._runtime._protocol import _FS_SENTINEL
+from snowflake.sandbox._transport import Transport
+from snowflake.sandbox.exceptions import (
+    SandboxError,
+    SandboxNotFoundError,
+    SandboxValidationError,
+)
+from snowflake.sandbox.types import FileInfo
+
+if TYPE_CHECKING:
+    from snowflake.sandbox.client import AsyncSandbox
+
+__all__ = [
+    "list_files",
+    "stat",
+    "make_directory",
+    "remove",
+]
+
+
+# ---- in-container directory ops over a python3 helper (via exec) ----------
+#
+# The request (path, flags) is embedded in the helper program as repr'd Python
+# literals, never shell-interpolated, so a path with spaces/quotes/metacharacters
+# cannot break out. See the module docstring for why these ride exec() at all.
+
+
+async def _fs_op(sandbox: AsyncSandbox, source: str) -> dict[str, Any]:
+    """Run *source* (a python3 program that prints ``_FS_SENTINEL`` + JSON) in the
+    sandbox and return the parsed object. The helper always exits 0 and encodes any
+    error in the JSON, so exec()'s raise-on-nonzero never masks a structured result.
+    """
+    if not sandbox.id:
+        raise SandboxError("sandbox must be created before filesystem operations")
+    result = await sandbox.exec(["python3", "-c", source], timeout=30.0)
+    payload: dict[str, Any] | None = None
+    for line in result.stdout.splitlines():
+        idx = line.find(_FS_SENTINEL)
+        if idx == -1:
+            continue
+        try:
+            obj = json.loads(line[idx + len(_FS_SENTINEL) :])
+        except ValueError:
+            continue
+        if isinstance(obj, dict):
+            payload = obj
+    if payload is None:
+        raise SandboxError(
+            f"filesystem helper returned no result (stdout: {result.stdout[:200]!r})"
+        )
+    return payload
+
+
+def _reject_anomalous_path(op: str, path: str) -> None:
+    """Refuse a directory-op path carrying a NUL or newline **client-side**.
+
+    ``list_files``/``stat``/``make_directory`` embed the path as a ``repr()`` literal
+    in the in-container helper (injection-safe), but a NUL byte reaches
+    ``os.scandir``/``os.stat``/``os.mkdir`` as a Python ``ValueError`` the helper does
+    not catch, so the caller would otherwise see a generic "helper returned no result"
+    `SandboxError` instead of a clear one. Mirrors the NUL/newline half of
+    ``_reject_dangerous_remove``. Raises `SandboxValidationError`."""
+    if any(c in path for c in "\x00\n\r"):
+        raise SandboxValidationError(f"{op}() path must not contain NUL or newline characters.")
+
+
+def _fileinfo(entry: dict[str, Any]) -> FileInfo:
+    return FileInfo(
+        path=str(entry["path"]),
+        is_dir=bool(entry["is_dir"]),
+        size_bytes=int(entry["size_bytes"]),
+        modified_at=entry.get("modified_at"),
+    )
+
+
+async def list_files(
+    sandbox: AsyncSandbox, path: str, *, transport: Transport | None = None
+) -> list[FileInfo]:
+    """Enumerate a directory's immediate contents (Modal
+    Sandbox.filesystem.list_files). Runs in-container via ``exec`` — see the module
+    docstring. A missing directory raises `SandboxNotFoundError`."""
+    _reject_anomalous_path("list_files", path)
+    src = (
+        _FS_HELPER_PREAMBLE
+        + f"""\
+p = {path!r}
+try:
+    out = []
+    with os.scandir(p) as it:
+        for e in it:
+            try:
+                st = e.stat(follow_symlinks=False)
+                out.append({{"path": e.path, "is_dir": e.is_dir(follow_symlinks=False),
+                            "size_bytes": st.st_size, "modified_at": st.st_mtime}})
+            except OSError:
+                pass
+    _emit({{"ok": True, "entries": out}})
+except FileNotFoundError:
+    _emit({{"ok": False, "error": "not_found"}})
+except NotADirectoryError:
+    _emit({{"ok": False, "error": "not_a_directory"}})
+except OSError as e:
+    _emit({{"ok": False, "error": str(e)}})
+"""
+    )
+    res = await _fs_op(sandbox, src)
+    _raise_fs_error(res, path)
+    return [_fileinfo(e) for e in res.get("entries", [])]
+
+
+async def stat(sandbox: AsyncSandbox, path: str, *, transport: Transport | None = None) -> FileInfo:
+    """Return metadata for one path (Modal Sandbox.filesystem.stat). Runs
+    in-container via ``exec``. A missing path raises `SandboxNotFoundError`."""
+    _reject_anomalous_path("stat", path)
+    src = (
+        _FS_HELPER_PREAMBLE
+        + f"""\
+p = {path!r}
+try:
+    st = os.stat(p)
+    _emit({{"ok": True, "info": {{"path": p, "is_dir": os.path.isdir(p),
+           "size_bytes": st.st_size, "modified_at": st.st_mtime}}}})
+except FileNotFoundError:
+    _emit({{"ok": False, "error": "not_found"}})
+except OSError as e:
+    _emit({{"ok": False, "error": str(e)}})
+"""
+    )
+    res = await _fs_op(sandbox, src)
+    _raise_fs_error(res, path)
+    return _fileinfo(res["info"])
+
+
+async def make_directory(
+    sandbox: AsyncSandbox,
+    path: str,
+    *,
+    create_parents: bool = False,
+    transport: Transport | None = None,
+) -> None:
+    """Create a directory (Modal Sandbox.filesystem.make_directory). With
+    ``create_parents`` it is a ``mkdir -p`` (existing dirs are fine); without it, a
+    missing parent or an existing target raises `SandboxError`. Runs in-container
+    via ``exec``."""
+    _reject_anomalous_path("make_directory", path)
+    src = (
+        _FS_HELPER_PREAMBLE
+        + f"""\
+p = {path!r}
+parents = {bool(create_parents)!r}
+try:
+    os.makedirs(p, exist_ok=True) if parents else os.mkdir(p)
+    _emit({{"ok": True}})
+except FileExistsError:
+    _emit({{"ok": False, "error": "exists"}})
+except FileNotFoundError:
+    _emit({{"ok": False, "error": "no_parent"}})
+except OSError as e:
+    _emit({{"ok": False, "error": str(e)}})
+"""
+    )
+    res = await _fs_op(sandbox, src)
+    _raise_fs_error(res, path)
+
+
+# The filesystem root, the system directories the runtime depends on, and the
+# common per-user/data roots. Deleting any of these (the in-container helper runs
+# ``shutil.rmtree(p)`` for a directory, so ``recursive=True`` is a literal
+# ``rm -rf``) destroys the sandbox's rootfs, TLS trust store, credentials, or
+# binaries. Mirrors the StageMount ``mount_path`` denylist
+# (`mount._DENIED_MOUNT_ROOTS`) — the same class of catastrophic-root guard,
+# on the delete path this time. A path *under* one of these is still allowed;
+# only the roots themselves are refused.
+_DENIED_REMOVE_PATHS: frozenset[str] = frozenset(
+    {
+        "/",
+        "/etc",
+        "/usr",
+        "/bin",
+        "/sbin",
+        "/lib",
+        "/lib64",
+        "/proc",
+        "/sys",
+        "/dev",
+        "/boot",
+        "/snowflake",
+        "/root",
+        "/home",
+        "/var",
+        "/opt",
+    }
+)
+
+
+def _reject_dangerous_remove(path: str) -> None:
+    """Refuse a `remove()` of the filesystem root, a reserved system directory, or
+    a traversal escape, **client-side** — before it is ever sent as an ``rm``.
+
+    ``remove("/", recursive=True)`` would ``rm -rf`` the whole rootfs;
+    ``"/etc"``/``"/usr"``/``"/bin"``/``"/sys"``/``"/proc"`` wipe dirs the runtime
+    needs. The empty path, ``.`` (the working directory), and any ``..`` component
+    are refused too (they resolve to something other than the intended target).
+    A path *beneath* a system root (``/etc/app.conf``) is allowed — only the roots
+    themselves are refused. Raises `SandboxError`."""
+    from posixpath import normpath
+
+    if not path or not path.strip():
+        raise SandboxError("remove() refused an empty path; pass an explicit file or directory.")
+    if any(c in path for c in "\x00\n\r"):
+        raise SandboxError("remove() path must not contain NUL or newline characters.")
+    if ".." in path.split("/"):
+        raise SandboxError(
+            f"remove() refused {path!r}: a '..' component could escape to a parent "
+            "directory. Pass a fully-resolved path with no '..'."
+        )
+    # Collapse leading slashes before the denylist check so '//etc' (which Linux
+    # resolves to '/etc') can't slip past it, mirroring _normalize_mount_path.
+    norm = ("/" + normpath(path).lstrip("/")) if path.startswith("/") else normpath(path)
+    if norm == ".":
+        raise SandboxError(
+            f"remove() refused {path!r}: it resolves to the working directory, not a "
+            "specific file. Pass an explicit path."
+        )
+    if norm.lower() in _DENIED_REMOVE_PATHS:
+        raise SandboxError(
+            f"remove() refused {path!r}: it is the filesystem root or a reserved "
+            "system directory. Deleting it would destroy the sandbox's rootfs, TLS "
+            "trust store, credentials, or binaries. Delete a specific path beneath "
+            "it instead."
+        )
+
+
+async def remove(
+    sandbox: AsyncSandbox,
+    path: str,
+    *,
+    recursive: bool = False,
+    transport: Transport | None = None,
+) -> None:
+    """Delete a file or directory (Modal Sandbox.filesystem.remove). A directory
+    needs ``recursive=True``; a missing path raises `SandboxNotFoundError`. Runs
+    in-container via ``exec``.
+
+    The filesystem root and reserved system directories (``/``, ``/etc``,
+    ``/usr``, ...) are refused client-side with a `SandboxError`: a recursive
+    remove of one is an ``rm -rf`` that destroys the sandbox's rootfs. Delete a
+    specific path beneath them instead."""
+    _reject_dangerous_remove(path)
+    src = (
+        _FS_HELPER_PREAMBLE
+        + f"""\
+p = {path!r}
+recursive = {bool(recursive)!r}
+try:
+    if os.path.isdir(p) and not os.path.islink(p):
+        shutil.rmtree(p) if recursive else os.rmdir(p)
+    else:
+        os.remove(p)
+    _emit({{"ok": True}})
+except FileNotFoundError:
+    _emit({{"ok": False, "error": "not_found"}})
+except OSError as e:
+    _emit({{"ok": False, "error": str(e)}})
+"""
+    )
+    res = await _fs_op(sandbox, src)
+    _raise_fs_error(res, path)
+
+
+def _raise_fs_error(res: dict[str, Any], path: str) -> None:
+    """Map a helper ``{"ok": False, "error": ...}`` onto the SDK error taxonomy."""
+    if res.get("ok"):
+        return
+    err = str(res.get("error") or "unknown error")
+    if err == "not_found":
+        raise SandboxNotFoundError(f"no such path in sandbox: {path}")
+    raise SandboxError(f"filesystem operation on {path!r} failed: {err}")