Sandbox - The build sandbox

Element plugins which want to interface with the sandbox need only understand this interface, while it may be given a different sandbox implementation, any sandbox implementation it is given will conform to this interface.

See also: Sandboxing.

exception SandboxCommandError(message, *, detail=None, collect=None, reason='command-failed')

Bases: SandboxError

Raised by Sandbox implementations when a command fails.

Parameters:

  • message (str) – The error message to report to the user

  • detail (str) – The detailed error string

  • collect (str) – An optional directory containing partial install contents

  • reason (str) – An optional reason string (defaults to ‘command-failed’)

class Sandbox

Bases: object

Sandbox programming interface for Element plugins.

get_virtual_directory() → Directory

Fetches the sandbox root directory as a virtual Directory.

The root directory is where artifacts for the base runtime environment should be staged.

Returns:

The sandbox root directory

set_environment(environment: Dict[str, str]) → None

Sets the environment variables for the sandbox

Parameters:

environment – The environment variables to use in the sandbox

set_work_directory(directory: str) → None

Sets the work directory for commands run in the sandbox

Parameters:

directory – An absolute path within the sandbox

mark_directory(directory: str) → None

Marks a sandbox directory and ensures it will exist

Parameters:

directory – An absolute path within the sandbox to mark

Note

Any marked directories will be read-write in the sandboxed environment, only the root directory is allowed to be readonly.

run(command: List[str], *, root_read_only: bool = False, cwd: str | None = None, env: Dict[str, str] | None = None, label: str | None = None) → int | None

Run a command in the sandbox.

If this is called outside a batch context, the command is immediately executed.

If this is called in a batch context, the command is added to the batch for later execution. If the command fails, later commands will not be executed. Command flags must match batch flags.

Parameters:

  • command – The command to run in the sandboxed environment, as a list of strings starting with the binary to run.

  • root_read_only – Whether the sandbox root should be readonly.

  • cwd – The sandbox relative working directory in which to run the command.

  • env – A dictionary of string key, value pairs to set as environment variables inside the sandbox environment.

  • label – An optional label for the command, used for logging.

Returns:

The program exit code, or None if running in batch context.

:raises (ProgramNotFoundError): If a host tool which the given sandbox implementation requires is not found.

Note

The optional cwd argument will default to the value set with set_work_directory() and this function must make sure the directory will be created if it does not exist yet, even if a workspace is being used.

batch(*, root_read_only: bool = False, label: str | None = None, collect: str | None = None) → Generator[None, None, None]

Context manager for command batching

This provides a batch context that defers execution of commands until the end of the context. If a command fails, the batch will be aborted and subsequent commands will not be executed.

Command batches may be nested. Execution will start only when the top level batch context ends.

Parameters:

  • root_read_only – Whether the sandbox root should be readonly.

  • label – An optional label for the batch group, used for logging.

  • collect – An optional directory containing partial install contents on command failure.

:raises (SandboxCommandError): If a command fails.