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

snowflake/sandbox/_sync_files_mixin.py

@@ -0,0 +1,272 @@
+"""The file-transfer / filesystem method group mixed into ``Sandbox``.
+
+The synchronous twin of ``_files_mixin._FilesMixin``: the same file-ops surface,
+blocking instead of awaitable, delegating to the sync mechanism modules
+(``sync_files`` for the ``/files`` byte route, ``_sync_fs_ops`` for the exec-driven
+directory ops, ``_sync_watch`` for the watcher). Extracted from ``Sandbox`` so the
+file-ops surface lives in one place per calling style, exactly as the async half
+was extracted from ``AsyncSandbox``.
+
+Not a public base class: an implementation detail of the two clients, inherited by
+``Sandbox``, never exposed on its own. It performs no I/O itself and imports nothing
+from the package at runtime.
+
+The delegate functions are typed against the concrete ``Sandbox``, so each call
+narrows ``self`` with a ``cast`` — a type-checker-only no-op: at run time ``self``
+already *is* a ``Sandbox``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator, Sequence
+    from pathlib import Path
+
+    from snowflake.sandbox._sync_transport import SyncTransport
+    from snowflake.sandbox._upload_plan import UploadPlan
+    from snowflake.sandbox.sync_client import Sandbox
+    from snowflake.sandbox.types import FileInfo, FileWatchEvent, FileWatchEventType
+
+__all__ = ["_FilesMixin"]
+
+
+class _FilesMixin:
+    """File-transfer and filesystem methods shared into ``Sandbox``.
+
+    ``_transport`` is set by the client's own ``__init__``; it is declared here so
+    the delegating methods type-check against it, mirroring ``_SandboxState``.
+    """
+
+    _transport: SyncTransport
+
+    # ----- file I/O ---------------------------------------------------
+
+    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:
+            sb.upload_file("./data.csv", "/app/data.csv")
+        """
+        from snowflake.sandbox.sync_files import upload_file
+
+        upload_file(cast("Sandbox", self), local, remote, transport=self._transport)
+
+    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 = sb.upload_dir("./project", "/app", exclude=["*.csv"])
+            print(f"sent {plan.file_count} files, skipped {plan.skipped_by_reason()}")
+        """
+        from snowflake.sandbox.sync_files import upload_dir
+
+        return upload_dir(
+            cast("Sandbox", 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,
+        )
+
+    def download_file(self, remote: str, local: str | Path) -> None:
+        """Download a file from the running sandbox to a local path.
+
+        Example:
+            sb.download_file("/app/output.csv", "./output.csv")
+        """
+        from snowflake.sandbox.sync_files import download_file
+
+        download_file(cast("Sandbox", self), remote, local, transport=self._transport)
+
+    def stage_put(self, local: str, stage_path: str) -> None:
+        """Upload a local file to a Snowflake stage from within the sandbox.
+
+        Example:
+            sb.stage_put("./results.parquet", "MY_STAGE/results.parquet")
+        """
+        from snowflake.sandbox.sync_files import stage_put
+
+        stage_put(cast("Sandbox", self), local, stage_path, transport=self._transport)
+
+    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:
+            sb.stage_get("MY_STAGE/model.pkl", "/app/model.pkl")
+        """
+        from snowflake.sandbox.sync_files import stage_get
+
+        stage_get(cast("Sandbox", 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 sync_files.py, _sync_fs_ops.py, _sync_watch.py.
+
+    def list_files(self, path: str) -> Sequence[FileInfo]:
+        """List files and directories at `path` inside the sandbox.
+
+        Example:
+            entries = sb.list_files("/app")
+            for entry in entries:
+                print(entry.path, entry.size_bytes, entry.is_dir)
+        """
+        from snowflake.sandbox._sync_fs_ops import list_files
+
+        return list_files(cast("Sandbox", self), path, transport=self._transport)
+
+    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:
+            sb.make_directory("/app/output", create_parents=True)
+        """
+        from snowflake.sandbox._sync_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
+        make_directory(
+            cast("Sandbox", self), path, create_parents=effective, transport=self._transport
+        )
+
+    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 = sb.read_text("/app/output.txt")
+        """
+        from snowflake.sandbox.sync_files import read_text
+
+        return read_text(cast("Sandbox", self), path, encoding=encoding, transport=self._transport)
+
+    def read_bytes(self, path: str) -> bytes:
+        """Read a binary file from the sandbox and return its contents.
+
+        Example:
+            data = sb.read_bytes("/app/output.bin")
+        """
+        from snowflake.sandbox.sync_files import read_bytes
+
+        return read_bytes(cast("Sandbox", self), path, transport=self._transport)
+
+    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:
+            sb.write_text("/app/config.json", '{"key": "value"}')
+        """
+        from snowflake.sandbox.sync_files import write_text
+
+        write_text(cast("Sandbox", self), path, data, encoding=encoding, transport=self._transport)
+
+    def write_bytes(self, path: str, data: bytes) -> None:
+        """Write bytes to a file inside the sandbox.
+
+        Example:
+            sb.write_bytes("/app/model.pkl", model_bytes)
+        """
+        from snowflake.sandbox.sync_files import write_bytes
+
+        write_bytes(cast("Sandbox", self), path, data, transport=self._transport)
+
+    def stat(self, path: str) -> FileInfo:
+        """Return metadata for a file or directory inside the sandbox.
+
+        Example:
+            info = sb.stat("/app/output.txt")
+            print(info.size_bytes)
+        """
+        from snowflake.sandbox._sync_fs_ops import stat as _stat
+
+        return _stat(cast("Sandbox", self), path, transport=self._transport)
+
+    def remove(self, path: str, *, recursive: bool = False) -> None:
+        """Remove a file or directory inside the sandbox.
+
+        Example:
+            sb.remove("/app/temp", recursive=True)
+        """
+        from snowflake.sandbox._sync_fs_ops import remove
+
+        remove(cast("Sandbox", self), path, recursive=recursive, transport=self._transport)
+
+    def watch(
+        self,
+        path: str,
+        *,
+        filter: Sequence[FileWatchEventType] | None = None,
+        recursive: bool = False,
+        timeout: float | None = None,
+    ) -> Iterator[FileWatchEvent]:
+        """Stream filesystem-change events under `path` as an iterator.
+
+        Example:
+            for event in sb.watch("/app"):
+                print(event.type, event.paths)
+        """
+        from snowflake.sandbox._sync_watch import watch
+
+        return watch(
+            cast("Sandbox", self),
+            path,
+            filter=filter,
+            recursive=recursive,
+            timeout=timeout,
+            transport=self._transport,
+        )

snowflake/sandbox/_sync_fs_ops.py

@@ -0,0 +1,185 @@
+"""Sync in-container directory operations, driven by ``exec`` — for ``Sandbox``.
+
+Synchronous counterpart to `_fs_ops`; see that module for why these run a
+``python3`` helper in the container instead of an HTTP route, and for the way their
+path handling differs from the ``/files`` byte transfers in `files`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from snowflake.sandbox._fs_ops import (
+    _fileinfo,
+    _raise_fs_error,
+    _reject_anomalous_path,
+    _reject_dangerous_remove,
+)
+
+# The in-container half is shared with the async side via _runtime; both modes
+# ship the same program text and parse the same sentinel.
+from snowflake.sandbox._runtime._fs_helper import _FS_HELPER_PREAMBLE
+from snowflake.sandbox._runtime._protocol import _FS_SENTINEL
+from snowflake.sandbox._sync_transport import SyncTransport
+from snowflake.sandbox.exceptions import SandboxError
+from snowflake.sandbox.types import FileInfo
+
+if TYPE_CHECKING:
+    from snowflake.sandbox.sync_client import Sandbox
+
+__all__ = [
+    "list_files",
+    "stat",
+    "make_directory",
+    "remove",
+]
+
+
+def _fs_op(sandbox: Sandbox, source: str) -> dict[str, Any]:
+    """Run *source* in the sandbox and return the parsed JSON result (sync version)."""
+    if not sandbox.id:
+        raise SandboxError("sandbox must be created before filesystem operations")
+    result = 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 list_files(
+    sandbox: Sandbox, path: str, *, transport: SyncTransport | None = None
+) -> list[FileInfo]:
+    """Enumerate a directory's contents (sync version).
+
+    See ``_fs_ops.list_files`` for full documentation.
+    """
+    _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 = _fs_op(sandbox, src)
+    _raise_fs_error(res, path)
+    return [_fileinfo(e) for e in res.get("entries", [])]
+
+
+def stat(sandbox: Sandbox, path: str, *, transport: SyncTransport | None = None) -> FileInfo:
+    """Return metadata for one path (sync version).
+
+    See ``_fs_ops.stat`` for full documentation.
+    """
+    _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 = _fs_op(sandbox, src)
+    _raise_fs_error(res, path)
+    return _fileinfo(res["info"])
+
+
+def make_directory(
+    sandbox: Sandbox,
+    path: str,
+    *,
+    create_parents: bool = False,
+    transport: SyncTransport | None = None,
+) -> None:
+    """Create a directory (sync version).
+
+    See ``_fs_ops.make_directory`` for full documentation.
+    """
+    _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 = _fs_op(sandbox, src)
+    _raise_fs_error(res, path)
+
+
+def remove(
+    sandbox: Sandbox,
+    path: str,
+    *,
+    recursive: bool = False,
+    transport: SyncTransport | None = None,
+) -> None:
+    """Delete a file or directory (sync version).
+
+    See ``_fs_ops.remove`` for full documentation.
+    """
+    _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 = _fs_op(sandbox, src)
+    _raise_fs_error(res, path)