chalkcompute 2.6.2__tar.gz → 2.7.0__tar.gz

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chalkcompute
-Version: 2.6.2
+Version: 2.7.0
 Requires-Dist: grpcio>=1.60.0
 Requires-Dist: protobuf>=4.25.0
 Requires-Dist: httpx>=0.25.0

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/chalkcompute/__init__.py

@@ -102,6 +102,7 @@ _LAZY_MAP: dict[str, tuple[str, str]] = {
     "ReadinessProbe": ("chalkcompute._scaling_group", "ReadinessProbe"),
     # _volume.py
     "FileInfo": ("chalkcompute._volume", "FileInfo"),
+    "ForkInfo": ("chalkcompute._volume", "ForkInfo"),
     "VersionInfo": ("chalkcompute._volume", "VersionInfo"),
     "Volume": ("chalkcompute._volume", "Volume"),
     "VolumeClient": ("chalkcompute._volume", "VolumeClient"),
@@ -109,6 +110,7 @@ _LAZY_MAP: dict[str, tuple[str, str]] = {
     "VolumeError": ("chalkcompute._volume", "VolumeError"),
     "VolumeFileNotFoundError": ("chalkcompute._volume", "VolumeFileNotFoundError"),
     "VolumeInfo": ("chalkcompute._volume", "VolumeInfo"),
+    "VolumeMount": ("chalkcompute._volume", "VolumeMount"),
     "VolumeNotFoundError": ("chalkcompute._volume", "VolumeNotFoundError"),
     # Imported by chalkpy's model-deploy path; every volume mounts as
     # MOUNT_TYPE, so this only validates existence now.

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/chalkcompute/__init__.pyi

@@ -73,6 +73,7 @@ from chalkcompute._secret import resolve_lazy_secrets as resolve_lazy_secrets
 from chalkcompute._tracing import span as span
 from chalkcompute._tracing import traced as traced
 from chalkcompute._volume import FileInfo as FileInfo
+from chalkcompute._volume import ForkInfo as ForkInfo
 from chalkcompute._volume import VersionInfo as VersionInfo
 from chalkcompute._volume import Volume as Volume
 from chalkcompute._volume import VolumeClient as VolumeClient
@@ -80,6 +81,7 @@ from chalkcompute._volume import VolumeClosedError as VolumeClosedError
 from chalkcompute._volume import VolumeError as VolumeError
 from chalkcompute._volume import VolumeFileNotFoundError as VolumeFileNotFoundError
 from chalkcompute._volume import VolumeInfo as VolumeInfo
+from chalkcompute._volume import VolumeMount as VolumeMount
 from chalkcompute._volume import VolumeNotFoundError as VolumeNotFoundError
 from chalkcompute._volume import (
     resolve_referenced_volume_type as resolve_referenced_volume_type,
@@ -162,12 +164,14 @@ __all__ = [
     "ScalingGroupInfo",
     "ReadinessProbe",
     "FileInfo",
+    "ForkInfo",
     "Volume",
     "VolumeClient",
     "VolumeClosedError",
     "VolumeError",
     "VolumeFileNotFoundError",
     "VolumeInfo",
+    "VolumeMount",
     "VolumeNotFoundError",
     "VersionInfo",
     "resolve_referenced_volume_type",

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/chalkcompute/_cls.py

@@ -85,6 +85,7 @@ from chalkcompute._rate_limit import RateLimitPolicy
 from chalkcompute._retry import RetryPolicy
 from chalkcompute._tracing import _instrumented
 from chalkcompute._volume import (
+    Volume,
     VolumeClient,
     VolumeMount,
     cleanup_owned_volumes,
@@ -652,7 +653,7 @@ class RemoteClass:
         gpu: str | None = None,
         env: dict[str, str] | None = None,
         secrets: list[_Secret] | None = None,
-        volumes: list[tuple[str, str]] | None = None,
+        volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
         min_replicas: int = 1,
         max_replicas: int = 1,
         shutdown_delay_seconds: int | None = None,
@@ -684,7 +685,7 @@ class RemoteClass:
         self._env = env or {}
         self._secrets: list[_Secret] = list(secrets or [])
         # Existence is checked once at deploy time, not here.
-        self._referenced_volumes: list[tuple[str, str]] = normalize_volume_refs(volumes)
+        self._referenced_volumes: list[VolumeMount] = normalize_volume_refs(volumes)
         # Populated at deploy time: referenced volumes plus any freshly
         # uploaded volumes.
         self._volumes: list[VolumeMount] = []
@@ -1067,8 +1068,8 @@ class RemoteClass:
             # A missing user-referenced volume fails the deploy. Checked once
             # here, then reused across every per-method spec.
             referenced_volumes = [
-                referenced_volume_mount(self._client, name, mount_path)
-                for name, mount_path in self._referenced_volumes
+                referenced_volume_mount(self._client, mount)
+                for mount in self._referenced_volumes
             ]
             self._volumes = [*referenced_volumes, *new_vols]
             self._volume_driver = driver
@@ -1499,7 +1500,7 @@ def cls(
     name: str | None = None,
     env: dict[str, str] | None = None,
     secrets: list[_Secret] | None = None,
-    volumes: list[tuple[str, str]] | None = None,
+    volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
     min_replicas: int = 1,
     max_replicas: int = 1,
     shutdown_delay_seconds: int | None = None,
@@ -1529,7 +1530,7 @@ def cls(
     name: str | None = None,
     env: dict[str, str] | None = None,
     secrets: list[_Secret] | None = None,
-    volumes: list[tuple[str, str]] | None = None,
+    volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
     min_replicas: int = 1,
     max_replicas: int = 1,
     shutdown_delay_seconds: int | None = None,
@@ -1560,7 +1561,7 @@ def cls(
     name: str | None = None,
     env: dict[str, str] | None = None,
     secrets: list[_Secret] | None = None,
-    volumes: list[tuple[str, str]] | None = None,
+    volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
     min_replicas: int = 1,
     max_replicas: int = 1,
     shutdown_delay_seconds: int | None = None,

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/chalkcompute/_container.py

@@ -47,6 +47,7 @@ from chalkcompute._naming import (
 )
 from chalkcompute._tracing import _instrumented
 from chalkcompute._volume import (
+    Volume,
     VolumeClient,
     VolumeMount,
     cleanup_owned_volumes,
@@ -972,7 +973,7 @@ class Container:
         gpu: str | None = None,
         env: dict[str, str] | None = None,
         secrets: list[Secret] | None = None,
-        volumes: list[tuple[str, str]] | None = None,
+        volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
         port: int | None = None,
         entrypoint: list[str] | None = None,
         lifetime: str | None = None,
@@ -1009,7 +1010,7 @@ class Container:
         self._env = dict(env) if env else {}
         self._secrets = list(secrets or [])
         # Existence is checked at run() time, not here.
-        self._referenced_volumes: list[tuple[str, str]] = normalize_volume_refs(volumes)
+        self._referenced_volumes: list[VolumeMount] = normalize_volume_refs(volumes)
         # Populated at run() time: referenced volumes plus any freshly
         # uploaded volumes.
         self._volumes: list[VolumeMount] = []
@@ -1232,7 +1233,7 @@ class Container:
         """
         # Referenced volume: its mount type is resolved from the backend at
         # run() time, not defaulted here.
-        self._referenced_volumes.append((name, mount_path))
+        self._referenced_volumes.append(VolumeMount(name=name, mount_path=mount_path))
         return self
 
     # -- Lifecycle -------------------------------------------------------------
@@ -1340,8 +1341,8 @@ class Container:
 
             # 2a. A missing user-referenced volume fails run().
             self._volumes = [
-                referenced_volume_mount(self._client, name, mount_path)
-                for name, mount_path in self._referenced_volumes
+                referenced_volume_mount(self._client, mount)
+                for mount in self._referenced_volumes
             ]
 
             # 2b. Upload lazy local files to a volume (if any)

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/chalkcompute/_function.py

@@ -81,6 +81,7 @@ from chalkcompute._tracing import (
     remote_function_call_span,
 )
 from chalkcompute._volume import (
+    Volume,
     VolumeClient,
     VolumeMount,
     normalize_volume_refs,
@@ -1501,7 +1502,7 @@ class RemoteFunction:
         gpu: str | None = None,
         env: dict[str, str] | None = None,
         secrets: list[_Secret] | None = None,
-        volumes: list[tuple[str, str]] | None = None,
+        volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
         min_replicas: int = 1,
         max_replicas: int = 1,
         shutdown_delay_seconds: int | None = None,
@@ -1548,7 +1549,7 @@ class RemoteFunction:
             self._env[MODELS_ENV_VAR] = encode_models_env(models)
         self._secrets: list[_Secret] = list(secrets or [])
         # Existence is checked at deploy time, not here.
-        self._referenced_volumes: list[tuple[str, str]] = normalize_volume_refs(volumes)
+        self._referenced_volumes: list[VolumeMount] = normalize_volume_refs(volumes)
         # Populated at deploy time: referenced volumes plus any freshly
         # uploaded volumes.
         self._volumes: list[VolumeMount] = []
@@ -1895,8 +1896,8 @@ class RemoteFunction:
             )
             # A missing user-referenced volume fails the deploy.
             referenced_volumes = [
-                referenced_volume_mount(self._client, name, mount_path)
-                for name, mount_path in getattr(self, "_referenced_volumes", [])
+                referenced_volume_mount(self._client, mount)
+                for mount in getattr(self, "_referenced_volumes", [])
             ]
             deploy_volumes = [
                 *referenced_volumes,
@@ -2833,7 +2834,7 @@ def function(
     name: str | None = None,
     env: dict[str, str] | None = None,
     secrets: list[_Secret] | None = None,
-    volumes: list[tuple[str, str]] | None = None,
+    volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
     min_replicas: int = 1,
     max_replicas: int = 1,
     shutdown_delay_seconds: int | None = None,
@@ -2865,7 +2866,7 @@ def function(
     name: str | None = None,
     env: dict[str, str] | None = None,
     secrets: list[_Secret] | None = None,
-    volumes: list[tuple[str, str]] | None = None,
+    volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
     min_replicas: int = 1,
     max_replicas: int = 1,
     shutdown_delay_seconds: int | None = None,
@@ -2898,7 +2899,7 @@ def function(
     name: str | None = None,
     env: dict[str, str] | None = None,
     secrets: list[_Secret] | None = None,
-    volumes: list[tuple[str, str]] | None = None,
+    volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
     min_replicas: int = 1,
     max_replicas: int = 1,
     shutdown_delay_seconds: int | None = None,

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/chalkcompute/_image.py

@@ -27,7 +27,6 @@ import logging
 import os
 import tarfile
 import tempfile
-import warnings
 from collections.abc import Sequence
 from dataclasses import dataclass
 from pathlib import Path
@@ -380,8 +379,9 @@ class Image:
             Absolute destination path in the image.
         mode
             Optional POSIX file permission mode. Written in octal with a
-            ``0o`` prefix; if omitted, the file is created with the image's
-            default permissions. Common values:
+            ``0o`` prefix; if omitted, ``strategy="volume"`` preserves the
+            source file's on-disk permissions and ``strategy="copy"`` uses
+            the image's default permissions. Common values:
 
             - ``0o755`` (``rwxr-xr-x``) — executable scripts and binaries;
               owner can read/write/execute, everyone else read/execute.
@@ -434,13 +434,6 @@ class Image:
             )
         new = self._copy()
         if strategy == "volume":
-            if mode is not None:
-                warnings.warn(
-                    "add_local_file: `mode` is ignored for strategy='volume' files "
-                    "(served as 0644); it is honored only for strategy='copy', which "
-                    "is limited to files <=32 KiB.",
-                    stacklevel=2,
-                )
             _validate_lazy_local_file_destination(dest)
             src_path = Path(src).resolve()
             if not src_path.exists():

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/chalkcompute/_native.pyi

@@ -63,6 +63,7 @@ class VersionedVolumeNativeClient:
         volume: str,
         source: Any,
         config: dict[str, Any] | None = None,
+        ref_name: str | None = None,
     ) -> list[dict[str, Any]]: ...
     def stage(
         self,
@@ -70,13 +71,19 @@ class VersionedVolumeNativeClient:
         source: Any,
         config: dict[str, Any] | None = None,
     ) -> StagedFiles: ...
-    def staged_intent(self, volume: str, staged: StagedFiles) -> bytes: ...
+    def staged_intent(
+        self,
+        volume: str,
+        staged: StagedFiles,
+        ref_name: str | None = None,
+    ) -> bytes: ...
     def commit_staged(
         self,
         volume: str,
         staged: StagedFiles,
         commit_id: str | None = None,
         max_commit_retries: int = 3,
+        ref_name: str | None = None,
     ) -> dict[str, Any]: ...
     def download_bytes(
         self,
@@ -105,6 +112,7 @@ class VersionedVolumeNativeClient:
         volume: str,
         paths: Sequence[tuple[str, bool]],
         max_commit_retries: int = 3,
+        ref_name: str | None = None,
     ) -> dict[str, Any]: ...
     def create_volume(
         self, name: str, volume_type: str | None = None
@@ -126,6 +134,7 @@ class VersionedVolumeNativeClient:
         name: str,
         limit: int | None = None,
         cursor: str | None = None,
+        ref_name: str | None = None,
     ) -> dict[str, Any]: ...
     def list_files(
         self,
@@ -137,6 +146,11 @@ class VersionedVolumeNativeClient:
         cursor: str | None = None,
     ) -> dict[str, Any]: ...
     def get_commit_status(self, volume: str, commit_id: str) -> dict[str, Any]: ...
+    def create_ref(
+        self, volume: str, name: str, from_version_id: int
+    ) -> dict[str, Any]: ...
+    def list_refs(self, volume: str) -> list[dict[str, Any]]: ...
+    def delete_ref(self, volume: str, name: str) -> None: ...
 
 def configure_volume_client_logging(
     level: str = "info",

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/chalkcompute/_sandbox.py

@@ -59,6 +59,7 @@ from chalkcompute._naming import validate_dns_label, validate_env
 from chalkcompute._tracing import _instrumented
 from chalkcompute._volume import (
     MOUNT_TYPE,
+    Volume,
     VolumeClient,
     VolumeMount,
     cleanup_owned_volumes,
@@ -69,7 +70,7 @@ from chalkcompute._volume import (
 # Aliases defined before SandboxClient, which has a ``.list()`` method that
 # would otherwise shadow the builtin ``list`` in class-scope name resolution.
 _GrpcMetadata = list[tuple[str, str]]
-_VolumeList = list[tuple[str, str]]
+_VolumeList = list[tuple[str, str] | Volume | VolumeMount]
 
 
 # ---------------------------------------------------------------------------
@@ -89,14 +90,8 @@ class SandboxNotFoundError(SandboxError):
     pass
 
 
-class SandboxTerminatedError(SandboxError):
-    """Raised when a sandbox has terminated."""
-
-    pass
-
-
-class SandboxBuildError(SandboxError):
-    """Raised when a custom sandbox image build fails."""
+class SandboxStatusError(SandboxError):
+    """Sandbox error carrying the backend's lifecycle status details."""
 
     def __init__(
         self,
@@ -114,23 +109,16 @@ class SandboxBuildError(SandboxError):
         super().__init__(message)
 
 
-class SandboxCreationError(SandboxError):
-    """Raised when sandbox creation or startup fails."""
+class SandboxTerminatedError(SandboxStatusError):
+    """Raised when a sandbox has terminated."""
 
-    def __init__(
-        self,
-        message: str,
-        *,
-        sandbox_id: str | None = None,
-        status: str | None = None,
-        status_message: str | None = None,
-        build_id: str | None = None,
-    ) -> None:
-        self.sandbox_id = sandbox_id
-        self.status = status
-        self.status_message = status_message
-        self.build_id = build_id
-        super().__init__(message)
+
+class SandboxBuildError(SandboxStatusError):
+    """Raised when a custom sandbox image build fails."""
+
+
+class SandboxCreationError(SandboxStatusError):
+    """Raised when sandbox creation or startup fails."""
 
 
 class ExecError(SandboxError):
@@ -454,7 +442,7 @@ class Sandbox:
         cpu: str | None = None,
         memory: str | None = None,
         env: dict[str, str] | None = None,
-        volumes: list[tuple[str, str]] | None = None,
+        volumes: _VolumeList | None = None,
         entrypoint: list[str] | None = None,
         network_policy: NetworkPolicy | None = None,
         restart_policy: RestartPolicy | None = None,
@@ -519,7 +507,7 @@ class Sandbox:
         self._memory: str | None = None
         self._env: dict[str, str] = {}
         # Existence is checked at run() time, not here.
-        self._referenced_volumes: list[tuple[str, str]] = []
+        self._referenced_volumes: list[VolumeMount] = []
         # Populated at run() time: referenced volumes plus any freshly
         # uploaded volumes.
         self._volumes: list[VolumeMount] = []
@@ -642,7 +630,7 @@ class Sandbox:
         ...     .run()
         ... )
         """
-        self._referenced_volumes.append((name, mount_path))
+        self._referenced_volumes.append(VolumeMount(name=name, mount_path=mount_path))
         return self
 
     @_instrumented("chalkcompute.sandbox.run")
@@ -691,8 +679,8 @@ class Sandbox:
         # A missing user-referenced volume fails run().
         connect = self._connect_client(client)
         self._volumes = [
-            referenced_volume_mount(connect, name, mount_path)
-            for name, mount_path in self._referenced_volumes
+            referenced_volume_mount(connect, mount)
+            for mount in self._referenced_volumes
         ]
         # Upload the image's lazy local files (add_local_file / add_local_dir
         # with the default strategy="volume") and mount them alongside.
@@ -1272,12 +1260,8 @@ class SandboxClient:
                 poll_interval=poll_interval,
                 timeout=timeout,
             )
-        elif wait and info.status in ("failed", "error", "unknown"):
+        elif wait and info.status in ("failed", "error", "unknown", "terminated"):
             raise _sandbox_creation_error(info)
-        elif wait and info.status == "terminated":
-            raise SandboxTerminatedError(
-                f"Sandbox {info.id} was terminated during creation"
-            )
 
         sandbox._id = info.id
         sandbox._info = info
@@ -1303,12 +1287,8 @@ class SandboxClient:
             info = _pb_to_sandbox_info(resp.sandbox)
             if info.status == "running":
                 return info
-            if info.status in ("failed", "error", "unknown"):
+            if info.status in ("failed", "error", "unknown", "terminated"):
                 raise _sandbox_creation_error(info)
-            if info.status == "terminated":
-                raise SandboxTerminatedError(
-                    f"Sandbox {sandbox_id} was terminated during creation"
-                )
             time.sleep(poll_interval)
         raise SandboxError(
             f"Timed out after {timeout}s waiting for sandbox {sandbox_id} to become ready"
@@ -1363,12 +1343,17 @@ def _pb_to_sandbox_info(info: pb.SandboxInfo) -> SandboxInfo:
     )
 
 
-def _sandbox_creation_error(info: SandboxInfo) -> SandboxCreationError:
+def _sandbox_creation_error(info: SandboxInfo) -> SandboxStatusError:
     """Build a detailed error from the backend's sandbox status."""
-    message = f"Sandbox {info.id} entered {info.status} state during creation"
+    if info.status == "terminated":
+        exc_cls: type[SandboxStatusError] = SandboxTerminatedError
+        message = f"Sandbox {info.id} was terminated during creation"
+    else:
+        exc_cls = SandboxCreationError
+        message = f"Sandbox {info.id} entered {info.status} state during creation"
     if info.status_message:
         message = f"{message}: {info.status_message}"
-    return SandboxCreationError(
+    return exc_cls(
         message,
         sandbox_id=info.id,
         status=info.status,
@@ -1435,10 +1420,17 @@ def _handle_rpc_error(e: grpc.RpcError, sandbox_id: str) -> None:
 def _volume_mounts_to_proto(
     volumes: list[VolumeMount],
 ) -> list[container_pb.VolumeMount]:
-    return [
-        container_pb.VolumeMount(name=v.name, mount_path=v.mount_path, type=MOUNT_TYPE)
-        for v in volumes
-    ]
+    mounts: list[container_pb.VolumeMount] = []
+    for volume in volumes:
+        mount = container_pb.VolumeMount(
+            name=volume.name,
+            mount_path=volume.mount_path,
+            type=MOUNT_TYPE,
+        )
+        if volume.version_id is not None:
+            mount.version_id = volume.version_id
+        mounts.append(mount)
+    return mounts
 
 
 def connect(target: str = "localhost:50051", **kwargs) -> SandboxClient:

{chalkcompute-2.6.2 → chalkcompute-2.7.0}/chalkcompute/_scaling_group.py

@@ -39,6 +39,7 @@ from chalkcompute._connect import ConnectClient, build_image, rpc_with_retries
 from chalkcompute._naming import sanitize_dns_label, validate_dns_label, validate_env
 from chalkcompute._tracing import _instrumented
 from chalkcompute._volume import (
+    Volume,
     VolumeClient,
     VolumeMount,
     cleanup_owned_volumes,
@@ -195,7 +196,7 @@ class ScalingGroup:
         gpu: str | None = None,
         env: dict[str, str] | None = None,
         secrets: list[_Secret] | None = None,
-        volumes: list[tuple[str, str]] | None = None,
+        volumes: list[tuple[str, str] | Volume | VolumeMount] | None = None,
         entrypoint: list[str] | None = None,
         port: int = 8080,
         protocol: str = "http",
@@ -219,7 +220,7 @@ class ScalingGroup:
         self._env = env or {}
         self._secrets: list[_Secret] = list(secrets or [])
         # Existence is checked at deploy time, not here.
-        self._referenced_volumes: list[tuple[str, str]] = normalize_volume_refs(volumes)
+        self._referenced_volumes: list[VolumeMount] = normalize_volume_refs(volumes)
         # Populated at deploy time: referenced volumes plus any freshly
         # uploaded volumes.
         self._volumes: list[VolumeMount] = []
@@ -402,8 +403,8 @@ class ScalingGroup:
 
         # 2a. A missing user-referenced volume fails the deploy.
         self._volumes = [
-            referenced_volume_mount(self._client, name, mount_path)
-            for name, mount_path in self._referenced_volumes
+            referenced_volume_mount(self._client, mount)
+            for mount in self._referenced_volumes
         ]
 
         # 2b. Upload lazy local files to volumes (if any)