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

snowflake/cli_sandbox/_upload_plan.py

@@ -0,0 +1,187 @@
+"""Resolving `snow sandbox run`'s TARGETs — the argv half of the upload plan.
+
+The *selection* engine (the walk, the skip reasons, `UploadPlan`) lives in
+`snowflake.sandbox._upload_plan`, because the library needs it too: `Sandbox.upload_dir`
+and the `from_local` bundle are the same decision about the same trees. What stays here
+is the part that is genuinely about a command line — turning argv tokens into targets,
+and the errors that name CLI flags in their remediation.
+
+The engine's names are re-exported so this module remains the CLI's single view of the
+plan, and `build_plan` is wrapped to keep the CLI's error type: the engine raises
+`SandboxValidationError` for a malformed pattern, which the CLI reports as `TargetError`
+alongside every other bad-input message.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from snowflake.sandbox._upload_plan import (
+    SKIP_DIRS,
+    ResolvedTarget,
+    Selected,
+    Skipped,
+    SkipReason,
+    UploadPlan,
+    _reject_unusable_name,
+)
+from snowflake.sandbox._upload_plan import build_plan as _engine_build_plan
+from snowflake.sandbox.exceptions import SandboxValidationError
+
+__all__ = [
+    "SKIP_DIRS",
+    "ResolvedTarget",
+    "Selected",
+    "SkipReason",
+    "Skipped",
+    "TargetError",
+    "UploadPlan",
+    "build_plan",
+    "resolve_targets",
+]
+
+
+class TargetError(Exception):
+    """A target cannot be used. The message is user-facing and names the fix."""
+
+
+def build_plan(
+    targets: tuple[ResolvedTarget, ...],
+    *,
+    dest_root: str,
+    exclude: list[str] | None = None,
+    include: list[str] | None = None,
+    allow_credential_files: list[str] | None = None,
+    max_file_bytes: int | None = None,
+) -> UploadPlan:
+    """The engine's `build_plan`, with pattern errors reported as `TargetError`.
+
+    A malformed ``--exclude``/``--include`` is bad argv like any other, so it has to
+    arrive at the CLI's one bad-input handler rather than as a library exception the
+    command layer does not catch.
+    """
+    _reject_bang_patterns(exclude, include)
+    try:
+        return _engine_build_plan(
+            targets,
+            dest_root=dest_root,
+            exclude=exclude,
+            include=include,
+            allow_credential_files=allow_credential_files,
+            max_file_bytes=max_file_bytes,
+        )
+    except SandboxValidationError as exc:
+        raise TargetError(str(exc)) from exc
+
+
+def _reject_bang_patterns(exclude: list[str] | None, include: list[str] | None) -> None:
+    """Reject a leading ``!`` in CLI vocabulary, before the engine sees it.
+
+    The engine refuses it too, but as a library it can only talk about ``include=``.
+    Here the remediation can name the flag that actually works, which is the whole
+    value of the message -- so the check is duplicated rather than translated.
+    """
+    for pattern in (*(exclude or []), *(include or [])):
+        if pattern.startswith("!"):
+            raise TargetError(
+                f"{pattern!r}: '!' is not accepted here — use --include to re-admit "
+                f"paths instead of negating an --exclude."
+            )
+
+
+def resolve_targets(given: list[str] | None) -> tuple[ResolvedTarget, ...]:
+    """Validate and resolve every TARGET, or raise `TargetError`.
+
+    Enforces, in order: existence, the dangerous-root guard, a usable basename,
+    de-duplication, no basename collisions, and no nesting.
+    """
+    raw = list(given or [])
+    if not raw:
+        return ()
+
+    home = Path.home().resolve()
+    resolved: list[ResolvedTarget] = []
+    seen: dict[Path, str] = {}
+
+    for token in raw:
+        expanded = Path(token).expanduser()
+        try:
+            path = expanded.resolve()
+            is_file, is_dir = path.is_file(), path.is_dir()
+        except OSError as exc:
+            raise TargetError(f"cannot read {token!r}: {exc.strerror or exc}") from exc
+
+        if not is_file and not is_dir:
+            if expanded.is_symlink():
+                raise TargetError(
+                    f"{token!r} is a broken symlink (points at {os.readlink(expanded)!r})."
+                )
+            if expanded.exists():
+                raise TargetError(
+                    f"{token!r} is not a regular file or directory; TARGET must be "
+                    f"a file, a directory, or a .py App module."
+                )
+            raise TargetError(
+                f"no such file or directory: {token!r}. TARGET is a local path (file, "
+                f"directory, or .py App module); to run an image, pass it as "
+                f"`--image {token}` with no TARGET."
+            )
+
+        # The dangerous-root guard. These are never what anyone meant, and no
+        # per-file filter can make them safe: the credential denylist is a
+        # project-tree filter and misses ~/.kube/config, ~/.config/gcloud/..., and
+        # ~/.gitconfig outright. A merely *broad* upload is left to the size gate.
+        if path == home:
+            raise TargetError(
+                f"refusing to upload your home directory ({path}). Name the "
+                f"project directory or the files you meant instead."
+            )
+        if path.parent == path or path in home.parents:
+            raise TargetError(
+                f"refusing to upload {path} — it contains your home directory. "
+                f"Name the project directory or the files you meant instead."
+            )
+
+        # `Path('..').name` is '..' and `Path('.').name` is '' -- both would escape or
+        # empty the destination -- so the basename comes from the resolved path. '/'
+        # still resolves to an empty name, but the root guard above already caught it.
+        basename = path.name
+        if not basename or basename == ".." or "/" in basename or "\\" in basename:
+            raise TargetError(f"cannot derive a destination name for {token!r} ({path}).")
+        if bad := _reject_unusable_name(basename):
+            raise TargetError(f"cannot upload {token!r}: its name {bad}.")
+
+        if path in seen:
+            continue  # './project' and '/abs/project' are one target, not two
+        seen[path] = token
+        resolved.append(ResolvedTarget(token, path, is_dir, basename))
+
+    _reject_collisions(resolved)
+    _reject_nesting(resolved)
+    return tuple(resolved)
+
+
+def _reject_collisions(targets: list[ResolvedTarget]) -> None:
+    """Two targets sharing a basename would overwrite each other silently."""
+    by_name: dict[str, ResolvedTarget] = {}
+    for target in targets:
+        if clash := by_name.get(target.basename):
+            raise TargetError(
+                f"{target.given!r} and {clash.given!r} would both upload as "
+                f"{target.basename!r}. Rename one, or pass their parent directory."
+            )
+        by_name[target.basename] = target
+
+
+def _reject_nesting(targets: list[ResolvedTarget]) -> None:
+    """A target inside another would upload twice, to two different places."""
+    for outer in targets:
+        if not outer.is_dir:
+            continue
+        for inner in targets:
+            if inner is not outer and outer.path in inner.path.parents:
+                raise TargetError(
+                    f"{inner.given!r} is inside {outer.given!r}; it would upload "
+                    f"twice. Pass one or the other."
+                )