code-sandboxes 1.4.6__tar.gz → 1.7.0__tar.gz

{code_sandboxes-1.4.6 → code_sandboxes-1.7.0}/CHANGELOG.md

@@ -8,6 +8,24 @@
 
 ## Unreleased
 
+## 1.7.0
+
+- **A version is resolved into one lock** (`code_sandboxes.environments.resolve`,
+  PLAN_ENV.md E1-04, D-9). Datalayer's protected constraints are merged over the
+  user's requirements — a requirement that agrees with a pin is dropped for it,
+  one that contradicts it is `DL_ENV_PROTECTED_PACKAGE` with the supported range
+  — the base is resolved to a digest per requested variant, and uv's refusals
+  are read into the error taxonomy: a conflict with the pair that cannot hold, a
+  package no index has, a protected pin, and `DL_ENV_PROVIDER_ERROR`, which is
+  retryable, for a failure that is not about the version.
+
+  The lock is uv's hashed output with the apt pins and the protected pins above
+  it as comments: one document that says everything a build installs, and still
+  a requirements file. `BuildkitResolveRunner` is D-9's solve, `FROM` the
+  resolved base digest; `LocalResolveRunner` runs `uv` where it is called, for
+  `plane local`, and refuses to pin apt rather than lock another
+  distribution's versions.
+
 - **Every variant has a real interrupt now, and can be reached to give it.**
   `Sandbox.interrupt` is two gates — `_executing_event` must be set, then
   `_do_interrupt` must answer — and seven variants failed one of them, each in

{code_sandboxes-1.4.6 → code_sandboxes-1.7.0}/Makefile

@@ -32,10 +32,28 @@ build:
 test:
 	pytest -q
 
+## Build the datalayer-sandbox doctor as a single-file zipapp.
+doctor-zipapp:
+	python -m code_sandboxes.environments.doctor.build dist/datalayer-sandbox
+
+## Regenerate the Environment JSON Schema and the sandbox contract page.
+environments-generate:
+	python -m code_sandboxes.environments schema --write
+	python -m code_sandboxes.environments contract --markdown docs/docs/environments/contract.mdx
+
+## Fail when the Environment JSON Schema or the sandbox contract page has drifted.
+environments-check:
+	python -m code_sandboxes.environments schema --check
+	python -m code_sandboxes.environments contract --check docs/docs/environments/contract.mdx
+
 ## The Contents provider matrix against the real providers (skips those without credentials).
 live-matrix:
 	CODE_SANDBOXES_LIVE=1 pytest -q -m live tests/test_contents_live_matrix.py
 
+## Lose a sandbox on each live provider and check the harness says so.
+kill-relaunch:
+	CODE_SANDBOXES_LIVE=1 pytest -q -m live tests/test_the_kill_relaunch_drill.py
+
 clean: ## clean
 	git clean -fdx
 

{code_sandboxes-1.4.6 → code_sandboxes-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code_sandboxes
-Version: 1.4.6
+Version: 1.7.0
 Project-URL: Home, https://github.com/datalayer/code-sandboxes
 Author-email: Datalayer <info@datalayer.io>
 License: BSD 3-Clause License

{code_sandboxes-1.4.6 → code_sandboxes-1.7.0}/code_sandboxes/__version__.py

@@ -3,4 +3,4 @@
 
 """Code Sandboxes."""
 
-__version__ = "1.4.6"
+__version__ = "1.7.0"

{code_sandboxes-1.4.6 → code_sandboxes-1.7.0}/code_sandboxes/base.py

@@ -499,6 +499,7 @@ class Sandbox(ABC):
         timeout: float | None = None,
         name: str | None = None,
         environment: str | None = None,
+        environment_version: str | int | None = None,
         gpu: str | None = None,
         cpu: float | None = None,
         memory: int | None = None,
@@ -525,7 +526,12 @@ class Sandbox(ABC):
             config: Optional full configuration object (overrides individual params).
             timeout: Default timeout for code execution in seconds.
             name: Optional name for the sandbox.
-            environment: Runtime environment (e.g., "ai-agents-env").
+            environment: Runtime environment (e.g., "ai-agents-env"), or a user
+                environment as "<account-handle>/<name>" or by its uid.
+            environment_version: Which version of a user environment to launch:
+                its number, or a version uid. Without one the promoted version
+                launches, which is what a platform environment always does.
+                Only the datalayer variant has versions (PLAN_ENV.md, E1-19).
             gpu: GPU type to use (e.g., "T4", "A100", "H100"). Only for datalayer.
             cpu: CPU cores to allocate.
             memory: Memory limit in MB.
@@ -559,6 +565,7 @@ class Sandbox(ABC):
             config = SandboxConfig(
                 timeout=timeout or 30.0,
                 environment=environment or DEFAULT_ENVIRONMENT,
+                environment_version=environment_version,
                 memory_limit=memory * 1024 * 1024 if memory else None,
                 cpu_limit=cpu,
                 env_vars=env or {},

{code_sandboxes-1.4.6 → code_sandboxes-1.7.0}/code_sandboxes/datalayer_sandbox.py

@@ -475,11 +475,19 @@ class DatalayerSandbox(Sandbox):
             # Build sandbox name
             sandbox_name = self.config.name or f"sandbox-{self._sandbox_id[:8]}"
 
+            # Which VERSION of that environment, passed through as the
+            # environment is (PLAN_ENV.md, E1-19). `None` means the promoted
+            # version, which is what every platform environment launches — and
+            # what every sandbox launched before there were versions asked for.
+            # The GPU rewrite above is left exactly as it is until E4-11 (D-20).
+            environment_version = self.config.environment_version
+
             # Create the runtime (optionally from snapshot)
             if self._snapshot_name:
                 self._runtime = self._client.create_runtime(
                     name=sandbox_name,
                     environment=environment,
+                    version=environment_version,
                     time_reservation=time_reservation,
                     snapshot_name=self._snapshot_name,
                 )
@@ -487,6 +495,7 @@ class DatalayerSandbox(Sandbox):
                 self._runtime = self._client.create_runtime(
                     name=sandbox_name,
                     environment=environment,
+                    version=environment_version,
                     time_reservation=time_reservation,
                 )
 

code_sandboxes-1.7.0/code_sandboxes/environments/__init__.py

@@ -0,0 +1,119 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""Environments: define once, resolve once, build an immutable artifact per variant.
+
+An **Environment** is the stable object a person names. An **Environment
+Version** is immutable once it leaves draft: its spec, the lock resolved from
+it, and its build outcome. An **Environment Artifact** is the build output of
+one version on one variant — an OCI digest for Datalayer, a build id for E2B,
+a snapshot id for Daytona, an image id for Modal.
+
+This package holds what every party to that life shares, and nothing
+provider-specific:
+
+- :mod:`.spec` — the canonical specification and its rules;
+- :mod:`.resolve` — the lock a version is resolved into, once (D-9);
+- :mod:`.contract` — ``sandbox-contract/v1`` and the Dockerfile validator;
+- :mod:`.lifecycle` — the version states and their legal moves;
+- :mod:`.errors` — the error taxonomy every provider error maps into;
+- :mod:`.builders` — the builder interface and its neutral types;
+- :mod:`.conformance` — the checks an artifact passes before it is ready;
+- :mod:`.redact` — a build's log with its secrets taken out before it is stored;
+- :mod:`.doctor` — the in-sandbox contract checker.
+
+The builders themselves are in :mod:`.adapters`, loaded by variant.
+"""
+
+from __future__ import annotations
+
+from .bases import APPROVED_BASES, ApprovedBase
+from .builders import (
+    ArtifactReference,
+    BuildRequest,
+    CapabilityReport,
+    CapabilitySet,
+    CheckResult,
+    EnvironmentBuilder,
+    ValidationResult,
+    get_builder,
+)
+from .canonical import canonical_digest, canonical_json
+from .contract import (
+    CONTRACT_V1,
+    SANDBOX_CONTRACT_V1,
+    SUPPORTED_CONTRACTS,
+    SandboxContract,
+    check_dockerfile,
+    validate_dockerfile,
+)
+from .errors import ERROR_CODES, EnvironmentsError, ErrorCode, map_provider_error
+from .lifecycle import VersionState, build_outcome, can_transition, transition
+from .resolve import (
+    LOCK_FORMAT,
+    BuildkitResolveRunner,
+    LocalResolveRunner,
+    ResolveRunner,
+    locked_versions,
+    merge_requirements,
+    parse_resolver_failure,
+    protected_pins,
+    resolve_environment,
+)
+from .spec import (
+    API_VERSION,
+    VARIANTS,
+    Environment,
+    EnvironmentSpec,
+    parse_environment,
+    spec_digest,
+    spec_findings,
+    validate_environment,
+)
+
+__all__ = [
+    "API_VERSION",
+    "APPROVED_BASES",
+    "CONTRACT_V1",
+    "ERROR_CODES",
+    "LOCK_FORMAT",
+    "SANDBOX_CONTRACT_V1",
+    "SUPPORTED_CONTRACTS",
+    "VARIANTS",
+    "ApprovedBase",
+    "ArtifactReference",
+    "BuildkitResolveRunner",
+    "BuildRequest",
+    "CapabilityReport",
+    "CapabilitySet",
+    "CheckResult",
+    "Environment",
+    "EnvironmentBuilder",
+    "EnvironmentSpec",
+    "EnvironmentsError",
+    "ErrorCode",
+    "LocalResolveRunner",
+    "ResolveRunner",
+    "SandboxContract",
+    "ValidationResult",
+    "VersionState",
+    "build_outcome",
+    "can_transition",
+    "canonical_digest",
+    "canonical_json",
+    "check_dockerfile",
+    "get_builder",
+    "locked_versions",
+    "merge_requirements",
+    "map_provider_error",
+    "parse_environment",
+    "parse_resolver_failure",
+    "protected_pins",
+    "resolve_environment",
+    "spec_digest",
+    "spec_findings",
+    "transition",
+    "validate_dockerfile",
+    "validate_environment",
+]

code_sandboxes-1.7.0/code_sandboxes/environments/__main__.py

@@ -0,0 +1,31 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""Generate what is generated from the Environment models.
+
+python -m code_sandboxes.environments schema --write [PATH]
+python -m code_sandboxes.environments schema --check [PATH]
+python -m code_sandboxes.environments contract --markdown docs/docs/environments/contract.mdx
+python -m code_sandboxes.environments contract --check docs/docs/environments/contract.mdx
+"""
+
+from __future__ import annotations
+
+import sys
+
+from . import contract, schema
+
+_COMMANDS = {"schema": schema.main, "contract": contract.main}
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if not arguments or arguments[0] not in _COMMANDS:
+        print(__doc__.strip(), file=sys.stderr)  # noqa: T201 - a command's own output
+        return 2
+    return _COMMANDS[arguments[0]](arguments[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

code_sandboxes-1.7.0/code_sandboxes/environments/adapters/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""The provider-specific Environment builders, one module per variant.
+
+Not neutral: each module speaks its provider's SDK. They are loaded only by
+:func:`code_sandboxes.environments.builders.get_builder`, and only where the
+build runs — the durable worker — never by a service that merely describes
+or launches an Environment.
+"""

code_sandboxes-1.7.0/code_sandboxes/environments/bases.py

@@ -0,0 +1,194 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+#
+# BSD 3-Clause License
+
+"""The approved bases an Environment may start from.
+
+An Environment names a base by reference and channel — ``datalayer/python-cpu``
+at ``2026.09`` — and resolution turns the pair into a digest per variant. Only
+the bases below are approved while Environments build from packages; importing
+arbitrary images comes later, with the contract injected and verified.
+
+The Python versions are what each base's interpreter is: 3.13, measured by
+``datalayer-sandbox doctor`` inside ``jupyter-python:0.1.1`` (3.13.14 on
+2026-09-11) and again inside ``jupyter-python:0.2.0``, the image the ``2026.09``
+channel is built on (PLAN_ENV.md, E1-05).
+
+A channel's digests are written here only once its release has pushed the
+channel to ECR and printed them. Until then the channel is known and has none,
+and resolving it raises :class:`BaseChannelUnpublishedError` rather than answer
+with a digest nobody pushed.
+"""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from ..models import normalize_variant
+from .errors import ARTIFACT_MISSING, SPEC_INVALID, EnvironmentsError
+
+__all__ = [
+    "APPROVED_BASES",
+    "ECR_BASE_PREFIX",
+    "ApprovedBase",
+    "BaseChannelUnpublishedError",
+    "approved_base",
+    "approved_repositories",
+    "is_approved_repository",
+    "resolve_base",
+]
+
+#: Where the bases are published in ECR (PLAN_ENV.md, D-18).
+ECR_BASE_PREFIX = "environments/base/"
+
+_DIGEST = re.compile(r"sha256:[0-9a-f]{64}")
+
+
+class ApprovedBase(BaseModel):
+    """One approved base."""
+
+    model_config = ConfigDict(frozen=True)
+
+    ref: str
+    #: The ``major.minor`` Python versions an Environment on this base may ask for.
+    python_versions: tuple[str, ...]
+    #: Whether the base carries CUDA, which a GPU size class requires.
+    accelerator: bool = False
+    #: Channel, then variant, to the digest resolution pins. A channel with no
+    #: variant is approved and not yet published.
+    channels: dict[str, dict[str, str]] = Field(default_factory=dict)
+
+    @field_validator("channels")
+    @classmethod
+    def _digests_only(cls, channels: dict[str, dict[str, str]]) -> dict[str, dict[str, str]]:
+        for channel, digests in channels.items():
+            for variant, digest in digests.items():
+                if not _DIGEST.fullmatch(digest):
+                    raise ValueError(
+                        f"channel {channel!r} pins {variant!r} to {digest!r}, "
+                        "which is not a sha256 digest"
+                    )
+        return {
+            channel: {normalize_variant(variant): digest for variant, digest in digests.items()}
+            for channel, digests in channels.items()
+        }
+
+    @property
+    def name(self) -> str:
+        """The base's name without its namespace: ``python-cpu``."""
+        return self.ref.rsplit("/", 1)[-1]
+
+    @property
+    def repository(self) -> str:
+        """The ECR repository the base is published to: ``environments/base/python-cpu``."""
+        return ECR_BASE_PREFIX + self.name
+
+
+APPROVED_BASES: dict[str, ApprovedBase] = {
+    base.ref: base
+    for base in (
+        # E1-05: jupyter-python:0.2.0 plus the contract layer. No digest until released.
+        ApprovedBase(
+            ref="datalayer/python-cpu", python_versions=("3.13",), channels={"2026.09": {}}
+        ),
+        # E2-17: jupyter-python-cuda plus the same layer.
+        ApprovedBase(
+            ref="datalayer/python-cuda",
+            python_versions=("3.13",),
+            accelerator=True,
+            channels={"2026.09": {}},
+        ),
+    )
+}
+
+
+class BaseChannelUnpublishedError(EnvironmentsError):
+    """An approved channel that has no digest yet for the variant asked.
+
+    Raised under ``DL_ENV_ARTIFACT_MISSING`` with the reason
+    ``base_channel_unpublished``, the way D-8 gives its own reason under that
+    code: the base the variant builds from is not in the registry. A retry
+    succeeds once the channel's release has pushed it and its digest is
+    written into :data:`APPROVED_BASES`.
+    """
+
+    def __init__(self, base: ApprovedBase, channel: str, variant: str) -> None:
+        super().__init__(
+            ARTIFACT_MISSING,
+            f"`{base.ref}:{channel}` has no published digest for the {variant} variant; "
+            f"it resolves once the channel is pushed to `{base.repository}`",
+            detail={
+                "reason": "base_channel_unpublished",
+                "base": base.ref,
+                "channel": channel,
+                "variant": variant,
+                "repository": base.repository,
+            },
+        )
+
+
+def approved_base(ref: str, bases: dict[str, ApprovedBase] = APPROVED_BASES) -> ApprovedBase | None:
+    return bases.get(ref)
+
+
+def resolve_base(
+    ref: str, channel: str, variant: str, bases: dict[str, ApprovedBase] = APPROVED_BASES
+) -> str:
+    """The digest ``ref`` at ``channel`` pins for ``variant``.
+
+    A base that is not approved, or a channel it does not have, is the spec's
+    fault (``DL_ENV_SPEC_INVALID``). A channel it has, with no digest for the
+    variant, raises :class:`BaseChannelUnpublishedError`.
+    """
+    base = bases.get(ref)
+    if base is None:
+        raise EnvironmentsError(
+            SPEC_INVALID,
+            f"`{ref}` is not an approved base; approved: " + ", ".join(bases),
+            detail={"field": "spec.base.ref", "base": ref, "approved": list(bases)},
+        )
+    digests = base.channels.get(channel)
+    if digests is None:
+        raise EnvironmentsError(
+            SPEC_INVALID,
+            f"`{ref}` has no channel `{channel}`; channels: "
+            + (", ".join(base.channels) or "none"),
+            detail={
+                "field": "spec.base.channel",
+                "base": ref,
+                "channel": channel,
+                "channels": list(base.channels),
+            },
+        )
+    normalized = normalize_variant(variant)
+    digest = digests.get(normalized)
+    if digest is None:
+        raise BaseChannelUnpublishedError(base, channel, normalized)
+    return digest
+
+
+def approved_repositories(bases: dict[str, ApprovedBase] = APPROVED_BASES) -> tuple[str, ...]:
+    """Every repository name an approved base is published under."""
+    names: list[str] = []
+    for base in bases.values():
+        names.extend((base.ref, base.repository))
+    return tuple(names)
+
+
+def is_approved_repository(image: str, bases: dict[str, ApprovedBase] = APPROVED_BASES) -> bool:
+    """Whether an image reference names an approved base, in any registry.
+
+    ``ghcr.io/datalayer/python-cpu@sha256:…`` and
+    ``<account>.dkr.ecr.<region>.amazonaws.com/environments/base/python-cpu:2026.09``
+    both name ``datalayer/python-cpu``; ``python:3.12`` names nothing approved.
+    """
+    repository = image.split("@", 1)[0]
+    last = repository.rsplit("/", 1)[-1]
+    if ":" in last:
+        repository = repository[: len(repository) - len(last)] + last.split(":", 1)[0]
+    return any(
+        repository == name or repository.endswith("/" + name)
+        for name in approved_repositories(bases)
+    )