Executors

Abstract Executor

class craft_providers.Executor[source]

Bases: abc.ABC

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

abstract delete()[source]

Delete instance.

Return type: None

abstract execute_popen(command, *, cwd=None, env=None, **kwargs)[source]

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 (List[str]) – Command to execute.
env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.
kwargs – Additional keyword arguments to pass.
cwd (Optional[Path]) –

Return type

Popen

Returns

Popen instance.

abstract execute_run(command, *, cwd=None, env=None, **kwargs)[source]

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 (List[str]) – Command to execute.
env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.
kwargs – Keyword args to pass to subprocess.run().
cwd (Optional[Path]) –

Return type

CompletedProcess

Returns

Completed process.

Raises

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

abstract exists()[source]

Check if instance exists.

Return type: bool
Returns: True if instance exists.

abstract is_running()[source]

Check if instance is running.

Return type: bool
Returns: True if instance is running.

abstract mount(*, host_source, target)[source]

Mount host source directory to target mount point.

Parameters

host_source (Path) –
target (Path) –

Return type

None

abstract pull_file(*, source, destination)[source]

Copy a file from the environment to host.

Parameters

source (PurePath) – Environment file to copy.
destination (Path) – 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.

Return type

None

abstract push_file(*, source, destination)[source]

Copy a file from the host into the environment.

The destination file is overwritten if it exists.

Parameters

source (Path) – Host file to copy.
destination (PurePath) – 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.

Return type

None

abstract push_file_io(*, destination, content, file_mode, group='root', user='root')[source]

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

Parameters

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

Return type

None

temporarily_pull_file(*, source, missing_ok=False)[source]

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 (Path) – Environment file to copy.
missing_ok (bool) – 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.

Return type

Generator[Optional[Path], None, None]

LXD Executor

class craft_providers.lxd.LXDInstance(*, name, default_command_environment=None, project='default', remote='local', lxc=None)[source]

Bases: craft_providers.executor.Executor

LXD Instance Lifecycle.

Parameters

name (str) –
default_command_environment (Optional[Dict[str, Optional[str]]]) –
project (str) –
remote (str) –
lxc (Optional[LXC]) –

delete(force=True)[source]

Delete instance.

Parameters: force (bool) – Delete even if running.
Raises: LXDError – On unexpected error.
Return type: None

execute_popen(command, *, cwd=None, env=None, **kwargs)[source]

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 (List[str]) – Command to execute.
env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.
kwargs – Additional keyword arguments to pass.
cwd (Optional[Path]) –

Return type

Popen

Returns

Popen instance.

execute_run(command, *, cwd=None, env=None, **kwargs)[source]

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 (List[str]) – Command to execute.
env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.
kwargs – Keyword args to pass to subprocess.run().
cwd (Optional[Path]) –

Return type

CompletedProcess

Returns

Completed process.

Raises

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

exists()[source]

Check if instance exists.

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

is_mounted(*, host_source, target)[source]

Check if path is mounted at target.

Parameters

host_source (Path) – Host path to check.
target (PurePath) – Instance path to check.

Return type

bool

Returns

True if host_source is mounted at target.

Raises

LXDError – On unexpected error.

is_running()[source]

Check if instance is running.

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

launch(*, image, image_remote, map_user_uid=False, ephemeral=False, uid=None)[source]

Launch instance.

Parameters

image (str) – Image name to launch.
image_remote (str) – Image remote name.
map_user_id – Whether id mapping should be used.
uid (Optional[int]) – If map_user_id is True, the host user ID to map to instance root.
ephemeral (bool) – Flag to enable ephemeral instance.
map_user_uid (bool) –

Raises

LXDError – On unexpected error.

Return type

None

mount(*, host_source, target)[source]

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 (Path) – Host path to mount.
target (PurePath) – Instance path to mount to.

Raises

LXDError – On unexpected error.

Return type

None

pull_file(*, source, destination)[source]

Copy a file from the environment to host.

Parameters

source (PurePath) – Environment file to copy.
destination (Path) – 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.

Return type

None

push_file(*, source, destination)[source]

Copy a file from the host into the environment.

The destination file is overwritten if it exists.

Parameters

source (Path) – Host file to copy.
destination (PurePath) – 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.

Return type

None

push_file_io(*, destination, content, file_mode, group='root', user='root')[source]

Create or replace file with content and file mode.

Parameters

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

Raises

LXDError – On unexpected error.

Return type

None

start()[source]

Start instance.

Raises: LXDError – on unexpected error.
Return type: None

stop()[source]

Stop instance.

Raises: LXDError – on unexpected error.
Return type: None

supports_mount()[source]

Check if instance supports mounting from host.

Return type: bool
Returns: True if mount is supported.

unmount(target)[source]

Unmount mount target shared with host.

Parameters: target (Path) – Target shared with host to unmount.
Raises: LXDError – On failure to unmount target.
Return type: None

unmount_all()[source]

Unmount all mounts shared with host.

Raises: LXDError – On failure to unmount target.
Return type: None

Multipass Executor

class craft_providers.multipass.MultipassInstance(*, name, multipass=None)[source]

Bases: craft_providers.executor.Executor

Multipass Instance Lifecycle.

Parameters

name (str) – Name of multipass instance.
multipass (Optional[Multipass]) –

delete()[source]

Delete instance and purge.

Return type: None

execute_popen(command, *, cwd=None, env=None, **kwargs)[source]

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 (List[str]) – Command to execute.
cwd (Optional[Path]) – working directory to execute the command
env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.
kwargs – Additional keyword arguments for subprocess.Popen().

Return type

Popen

Returns

Popen instance.

execute_run(command, *, cwd=None, env=None, **kwargs)[source]

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.

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 (List[str]) – Command to execute.
cwd (Optional[Path]) – working directory to execute the command
env (Optional[Dict[str, Optional[str]]]) – Additional environment to set for process.
kwargs – Keyword args to pass to subprocess.run().

Return type

CompletedProcess

Returns

Completed process.

Raises

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

exists()[source]

Check if instance exists.

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

is_mounted(*, host_source, target)[source]

Check if path is mounted at target.

Parameters

host_source (Path) – Host path to check.
target (PurePath) – Instance path to check.

Return type

bool

Returns

True if host_source is mounted at target.

Raises

MultipassError – On unexpected failure.

is_running()[source]

Check if instance is running.

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

launch(*, image, cpus=2, disk_gb=256, mem_gb=2)[source]

Launch instance.

Parameters

image (str) – 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.
cpus (int) –
disk_gb (int) –
mem_gb (int) –

Raises

MultipassError – On unexpected failure.

Return type

None

mount(*, host_source, target)[source]

Mount host host_source directory to target mount point.

Checks first to see if already mounted.

Parameters

host_source (Path) – Host path to mount.
target (PurePath) – Instance path to mount to.

Raises

MultipassError – On unexpected failure.

Return type

None

pull_file(*, source, destination)[source]

Copy a file from the environment to host.

Parameters

source (PurePath) – Environment file to copy.
destination (Path) – 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.

Return type

None

push_file(*, source, destination)[source]

Copy a file from the host into the environment.

The destination file is overwritten if it exists.

Parameters

source (Path) – Host file to copy.
destination (PurePath) – 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.
MultipassError – On unexpected error copying file.

Return type

None

push_file_io(*, destination, content, file_mode, group='root', user='root')[source]

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 (PurePath) – Path to file.
content (BytesIO) – Contents of file.
file_mode (str) – File mode string (e.g. ‘0644’).
group (str) – File group owner/id.
user (str) – File user owner/id.

Return type

None

start()[source]

Start instance.

Raises: MultipassError – On unexpected failure.
Return type: None

stop(*, delay_mins=0)[source]

Stop instance.

Parameters: delay_mins (int) – Delay shutdown for specified minutes.
Raises: MultipassError – On unexpected failure.
Return type: None

unmount(target)[source]

Unmount mount target shared with host.

Parameters: target (Path) – Target shared with host to unmount.
Raises: MultipassError – On failure to unmount target.
Return type: None

unmount_all()[source]

Unmount all mounts shared with host.

Raises: MultipassError – On failure to unmount target.
Return type: None