API Reference¶

class Sandbox:
    def __init__(
        self,
        max_duration_sec: float | None = None,
        max_memory_mb: int | None = None,
        max_cpus: float | None = None,
        enable_network: bool | None = None,
        enable_package_cache: bool | None = None,
        tmpfs_size_mb: int | None = None,
        image_name: str | None = None,
        workspace: list[Path | str] | None = None,
        sandbox_type: SandboxType | str | None = None,
        readonly: bool | None = None,
        max_output_bytes: int | None = None,
        progress_callback: ReplayProgressCallback | None = None,
    )

class MontySandbox:
    def __init__(
        self,
        max_duration_sec: float | None = 10.0,
        max_memory_mb: int | None = 64,
        max_recursion_depth: int | None = 1_000,
        workspace: list[Path] | None = None,
        readonly: bool = False,
    )

class ContainerSandbox:
    IMAGE_NAME: str = "backyard-sandbox"

    def __init__(
        self,
        max_duration_sec: float = 10.0,
        max_memory_mb: int | None = 128,
        max_cpus: float | None = 1.0,
        enable_network: bool | None = False,
        enable_package_cache: bool | None = False,
        image_name: str | None = None,
        workspace: list[Path | str] | None = None,
        readonly: bool = False,
        tmpfs_size_mb: int = 16,
        max_output_bytes: int = 10 * 1024 * 1024,
    )

@dataclass
class SandboxExecution:
    stdout: str
    stderr: str
    errors: list[SandboxError] | None = None
    files: list[MemoryFile] | None = None
    rich_outputs: list[RichOutput] | None = None
    file_changes: FileChanges | None = None
    is_valid_python: bool = True
    exit_code: int = 0
    start_time: datetime.datetime
    end_time: datetime.datetime
    duration_sec: float = 0.0
    timed_out: bool = False
    memory_limit_hit: bool = False
    inputs: SandboxInput | None = None
    result: Any | None = None

    @property
    def success(self) -> bool: ...

    @property
    def failed(self) -> bool: ...

@dataclass
class SandboxInput:
    code: str
    env_vars: dict[str, str] | None = None
    input_files: list[Path] | None = None
    dependencies: list[str] | None = None  # Container
    external_functions: dict[str, Callable] | None = None  # Monty
    inputs: dict[str, Any] | None = None  # Monty
    type_check: bool = False  # Monty
    type_check_stubs: str | None = None  # Monty
    dataclass_registry: list[type[Any]] | None = None  # Monty
    max_duration_sec: float | None = None  # Per-call override
    max_memory_mb: int | None = None  # Per-call override

@dataclass
class SandboxConfig:
    max_duration_sec: float | None = 10.0
    max_memory_mb: int | None = 128
    max_cpus: float | None = 1.0  # Container only
    enable_network: bool | None = False  # Container only
    enable_package_cache: bool | None = False  # Container only
    tmpfs_size_mb: int = 16  # Container only
    image_name: str | None = None  # Container only
    max_recursion_depth: int | None = 1_000  # Monty only
    workspace: list[Path | str] | None = None

@dataclass
class FileChanges:
    added: list[Path]
    modified: list[Path]
    deleted: list[Path]
    all_changes: list[FileChange]

    @property
    def has_changes(self) -> bool: ...

@dataclass
class FileChange:
    path: Path
    timestamp: datetime.datetime
    change_type: str  # "added", "modified", or "deleted"

@dataclass
class InstallResult:
    success: bool
    output: str = ""
    error: str | None = None

@dataclass
class RichOutput:
    mime_type: str  # e.g. "image/png", "text/html"
    content: str | bytes  # Raw text or base64 encoded bytes

from backyard.errors import (
    SandboxError,
    SandboxTimeoutError,
    SandboxMemoryError,
    SandboxSyntaxError,
    SandboxRuntimeError,
    SandboxNotSupportedError,
    SandboxPermissionError,
)

class SandboxError(Exception):
    def __init__(self, message: str, traceback: str | None = None)

class SandboxTimeoutError(SandboxError): ...      # Exit code 124
class SandboxMemoryError(SandboxError): ...        # Exit code 137
class SandboxSyntaxError(SandboxError): ...
class SandboxRuntimeError(SandboxError): ...
class SandboxNotSupportedError(SandboxError): ...  # Monty incompatibility
class SandboxPermissionError(SandboxError): ...    # Read-only violation

class SandboxType(StrEnum):
    CONTAINER = "container"
    MONTY = "monty"
    AUTO = "auto"

from backyard.utils import (
    ALWAYS_IGNORED,             # frozenset of always-hidden directory names
    STD_LIB,                    # set of standard library module names
    FileChangesTracker,         # Helper for tracking file changes
    GitIgnorePattern,           # Gitignore-style pattern matching
    check_gvisor_available,     # Check if runsc runtime is available
    detect_container_runtime,   # Detect podman or docker
    detect_dependencies,        # AST-based dependency detection
    env_bool,                   # Read bool from BACKYARD_* env var
    env_float,                  # Read float from BACKYARD_* env var
    env_int,                    # Read int from BACKYARD_* env var
    env_str,                    # Read str from BACKYARD_* env var
    get_background_loop,        # Get/create the background event loop
    get_directory_snapshot,     # Recursive directory scan
    get_file_changes,           # Compare two snapshots
    get_logger,                 # Get structured logger
    is_binary,                  # Check if file is binary
    is_readonly_error,          # Check if error message indicates read-only
    load_module_mapping,        # Load module→PyPI name mapping
    parse_gitignore,            # Parse .gitignore files
    run_sync,                   # Run async function synchronously
    split_workspace_paths,      # Split paths into dirs and files
)