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 process 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 for subprocess.Popen().
cwd (Optional[Path]) –

Return type

Popen

Returns

Popen instance.

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

Execute 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: 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