Executors¶

Abstract Executor¶

class craft_providers.Executor¶

Bases: ABC

Interfaces to execute commands and move data in/out of an environment.

abstract delete() → None¶: Delete instance.

abstract execute_popen(command: List[str], *, cwd: PurePath | None = None, env: Dict[str, str | None] | None = None, timeout: float | None = None, **kwargs) → Popen¶

Execute a command in instance, using subprocess.Popen().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

Parameters:

command – Command to execute.
cwd – Working directory for the process inside the instance.
env – Additional environment to set for process.
timeout – Timeout (in seconds) for the command.
kwargs – Additional keyword arguments to pass.

Returns:

Popen instance.

abstract execute_run(command: List[str], *, cwd: PurePath | None = None, env: Dict[str, str | None] | None = None, timeout: float | None = None, check: bool = False, **kwargs) → CompletedProcess¶

Execute a command using subprocess.run().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

Parameters:

command – Command to execute.
cwd – Working directory for the process inside the instance.
env – Additional environment to set for process.
timeout – Timeout (in seconds) for the command.
check – Raise an exception if the command fails.
kwargs – Keyword args to pass to subprocess.run().

Returns:

Completed process.

Raises:

subprocess.CalledProcessError – if command fails and check is True.

abstract exists() → bool¶

Check if instance exists.

Returns:: True if instance exists.

abstract is_running() → bool¶

Check if instance is running.

Returns:: True if instance is running.

abstract mount(*, host_source: Path, target: PurePath) → None¶: Mount host source directory to target mount point.

abstract pull_file(*, source: PurePath, destination: Path) → None¶

Copy a file from the environment to host.

Parameters:

source – Environment file to copy.
destination – Host file path to copy to. Parent directory (destination.parent) must exist.

Raises:

FileNotFoundError – If source file or destination’s parent directory does not exist.
ProviderError – On error copying file.

abstract push_file(*, source: Path, destination: PurePath) → None¶

Copy a file from the host into the environment.

The destination file is overwritten if it exists.

Parameters:

source – Host file to copy.
destination – Target environment file path to copy to. Parent directory (destination.parent) must exist.

Raises:

FileNotFoundError – If source file or destination’s parent directory does not exist.
ProviderError – On error copying file.

abstract push_file_io(*, destination: PurePath, content: BytesIO, file_mode: str, group: str = 'root', user: str = 'root') → None¶

Create or replace a file with specified content and file mode.

Parameters:

destination – Path to file.
content – Contents of file.
file_mode – File mode string (e.g. ‘0644’).
group – File owner group.
user – File owner user.

temporarily_pull_file(*, source: PurePath, missing_ok: bool = False) → Generator[Path | None, None, None]¶

Copy a file from the environment to a temporary file in the host.

This is mainly a layer above pull_file that pulls the file into a temporary path which is cleaned later.

Works as a context manager, provides the file path in the host as target.

The temporary file is stored in the home directory where Multipass has access.

Parameters:

source – Environment file to copy.
missing_ok – Do not raise an error if the file does not exist in the environment; in this case the target will be None.

Raises:

FileNotFoundError – If source file or destination’s parent directory does not exist (and missing_ok is False).
ProviderError – On error copying file content.

LXD Executor¶

class craft_providers.lxd.LXDInstance(*, name: str, default_command_environment: Dict[str, str | None] | None = None, project: str = 'default', remote: str = 'local', lxc: LXC | None = None)¶

Bases: Executor

LXD Instance Lifecycle.

config_get(key: str) → str¶

Get instance configuration value.

Parameters:: key – Configuration key to get.
Returns:: Configuration value.
Raises:: LXDError – On unexpected error.

config_set(key: str, value: str) → None¶

Set instance configuration value.

Parameters:

key – Configuration key to set.
value – Configuration key to the value.

Returns:

None.

Raises:

LXDError – On unexpected error.

delete(force: bool = True) → None¶

Delete instance.

Parameters:: force – Delete even if running.
Raises:: LXDError – On unexpected error.

execute_popen(command: List[str], *, cwd: PurePath | None = None, env: Dict[str, str | None] | None = None, timeout: float | None = None, **kwargs) → Popen¶

Execute a command in instance, using subprocess.Popen().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

Parameters:

command – Command to execute.
cwd – Working directory for the process inside the instance.
env – Additional environment to set for process.
timeout – Timeout (in seconds) for the command.
kwargs – Additional keyword arguments to pass.

Returns:

Popen instance.

execute_run(command: List[str], *, cwd: PurePath | None = None, env: Dict[str, str | None] | None = None, timeout: float | None = None, check: bool = False, **kwargs) → CompletedProcess¶

Execute a command using subprocess.run().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

Parameters:

command – Command to execute.
cwd – Working directory for the process inside the instance.
env – Additional environment to set for process.
timeout – Timeout (in seconds) for the command.
check – Raise an exception if the command fails.
kwargs – Keyword args to pass to subprocess.run().

Returns:

Completed process.

Raises:

subprocess.CalledProcessError – if command fails and check is True.

exists() → bool¶

Check if instance exists.

Returns:: True if instance exists.
Raises:: LXDError – On unexpected error.

info() → Dict[str, Any]¶: Get info for an instance.

is_mounted(*, host_source: Path, target: PurePath) → bool¶

Check if path is mounted at target.

Parameters:

host_source – Host path to check.
target – Instance path to check.

Returns:

True if host_source is mounted at target.

Raises:

LXDError – On unexpected error.

is_running() → bool¶

Check if instance is running.

Returns:: True if instance is running.
Raises:: LXDError – On unexpected error.

launch(*, image: str, image_remote: str, map_user_uid: bool = False, ephemeral: bool = False, uid: int | None = None) → None¶

Launch instance.

Parameters:

image – Image name to launch.
image_remote – Image remote name.
map_user_uid – Whether id mapping should be used.
uid – If map_user_uid is True, the host user ID to map to instance root.
ephemeral – Flag to enable ephemeral instance.

Raises:

LXDError – On unexpected error.

mount(*, host_source: Path, target: PurePath) → None¶

Mount host source directory to target mount point.

Checks first to see if already mounted. The source will be mounted as a disk named “disk-{target.as_posix()}”.

Parameters:

host_source – Host path to mount.
target – Instance path to mount to.

Raises:

LXDError – On unexpected error.

pull_file(*, source: PurePath, destination: Path) → None¶

Copy a file from the environment to host.

Parameters:

source – Environment file to copy.
destination – Host file path to copy to. Parent directory (destination.parent) must exist.

Raises:

FileNotFoundError – If source file or destination’s parent directory does not exist.
LXDError – On unexpected error copying file.

push_file(*, source: Path, destination: PurePath) → None¶

Copy a file from the host into the environment.

The destination file is overwritten if it exists.

Parameters:

source – Host file to copy.
destination – Target environment file path to copy to. Parent directory (destination.parent) must exist.

Raises:

FileNotFoundError – If source file or destination’s parent directory does not exist.
LXDError – On unexpected error copying file.

push_file_io(*, destination: PurePath, content: BytesIO, file_mode: str, group: str = 'root', user: str = 'root') → None¶

Create or replace file with content and file mode.

Parameters:

destination – Path to file.
content – Contents of file.
file_mode – File mode string (e.g. ‘0644’).
group – File group owner/id.
user – File user owner/id.

Raises:

LXDError – On unexpected error.

restart() → None¶

Restart instance.

Raises:: LXDError – on unexpected error.

start() → None¶

Start instance.

Raises:: LXDError – on unexpected error.

stop() → None¶

Stop instance.

Raises:: LXDError – on unexpected error.

supports_mount() → bool¶

Check if instance supports mounting from host.

Returns:: True if mount is supported.

unmount(target: PurePath) → None¶

Unmount mount target shared with host.

Parameters:: target – Target shared with host to unmount.
Raises:: LXDError – On failure to unmount target.

unmount_all() → None¶

Unmount all mounts shared with host.

Raises:: LXDError – On failure to unmount target.

Multipass Executor¶

class craft_providers.multipass.MultipassInstance(*, name: str, multipass: Multipass | None = None)¶

Bases: Executor

Multipass Instance Lifecycle.

Parameters:: name – Name of multipass instance.

delete() → None¶: Delete instance and purge.

execute_popen(command: List[str], *, cwd: PurePath | None = None, env: Dict[str, str | None] | None = None, timeout: float | None = None, **kwargs) → Popen¶

Execute a process in the instance using subprocess.Popen().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

The command is run as root via sudo. Running as root may be required even when the command itself does not require root permissions, because the instance’s working directory may be a directory that the default ubuntu user does not have access to.

Parameters:

command – Command to execute.
cwd – working directory to execute the command
env – Additional environment to set for process.
timeout – Timeout (in seconds) for the command.
kwargs – Additional keyword arguments for subprocess.Popen().

Returns:

Popen instance.

execute_run(command: List[str], *, cwd: PurePath | None = None, env: Dict[str, str | None] | None = None, timeout: float | None = None, check: bool = False, **kwargs) → CompletedProcess¶

Execute a command in the instance using subprocess.run().

The process’ environment will inherit the execution environment’s default environment (PATH, etc.), but can be additionally configured via env parameter.

Parameters:

command – Command to execute.
cwd – working directory to execute the command
env – Additional environment to set for process.
timeout – Timeout (in seconds) for the command.
check – Raise an exception if the command fails.
kwargs – Keyword args to pass to subprocess.run().

Returns:

Completed process.

Raises:

subprocess.CalledProcessError – if command fails and check is True.

exists() → bool¶

Check if instance exists.

Returns:: True if instance exists.
Raises:: MultipassError – On unexpected failure.

is_mounted(*, host_source: Path, target: PurePath) → bool¶

Check if path is mounted at target.

Parameters:

host_source – Host path to check.
target – Instance path to check.

Returns:

True if host_source is mounted at target.

Raises:

MultipassError – On unexpected failure.

is_running() → bool¶

Check if instance is running.

Returns:: True if instance is running.
Raises:: MultipassError – On unexpected failure.

launch(*, image: str, cpus: int = 2, disk_gb: int = 256, mem_gb: int = 2) → None¶

Launch instance.

Parameters:

image – Name of image to create the instance with.
instance_cpus – Number of CPUs.
instance_disk_gb – Disk allocation in gigabytes.
instance_mem_gb – Memory allocation in gigabytes.
instance_name – Name of instance to use/create.
instance_stop_time_mins – Stop time delay in minutes.

Raises:

MultipassError – On unexpected failure.

mount(*, host_source: Path, target: PurePath) → None¶

Mount host host_source directory to target mount point.

Checks first to see if already mounted.

Parameters:

host_source – Host path to mount.
target – Instance path to mount to.

Raises:

MultipassError – On unexpected failure.

pull_file(*, source: PurePath, destination: Path) → None¶

Copy a file from the environment to host.

Parameters:

source – Environment file to copy.
destination – Host file path to copy to. Parent directory (destination.parent) must exist.

Raises:

FileNotFoundError – If source file or destination’s parent directory does not exist.
MultipassError – On unexpected error copying file.

push_file(*, source: Path, destination: PurePath) → None¶

Copy a file from the host into the environment.

The destination file is overwritten if it exists. File permissions are retained but the ownership is changed to the default user ubuntu.

The source cannot be a directory because multipass transfer –recursive is not supported. The parent directories of the destination must exist because multipass transfer –parents is not supported.

Parameters:

source – Host file to copy.
destination – Target environment file path to copy to. Parent directory (destination.parent) must exist.

Raises:

FileNotFoundError – If source file or destination’s parent directory does not exist or if the source is not a regular file.
IsADirectoryError – If source is a directory.
MultipassError – If the file cannot be pushed into the instance.

push_file_io(*, destination: PurePath, content: BytesIO, file_mode: str, group: str = 'root', user: str = 'root') → None¶

Create or replace file with content and file mode.

Multipass transfers data as “ubuntu” user, forcing us to first copy a file to a temporary location before moving to a (possibly) root-owned location and with appropriate permissions.

Parameters:

destination – Path to file.
content – Contents of file.
file_mode – File mode string (e.g. ‘0644’).
group – File group owner/id.
user – File user owner/id.

Raises:

MultipassError – If the content cannot be pushed into the instance.

start() → None¶

Start instance.

Raises:: MultipassError – On unexpected failure.

stop(*, delay_mins: int = 0) → None¶

Stop instance.

Parameters:: delay_mins – Delay shutdown for specified minutes.
Raises:: MultipassError – On unexpected failure.

unmount(target: Path) → None¶

Unmount mount target shared with host.

Parameters:: target – Target shared with host to unmount.
Raises:: MultipassError – On failure to unmount target.

unmount_all() → None¶

Unmount all mounts shared with host.

Raises:: MultipassError – On failure to unmount target.