craft_providers.multipass package

Submodules

Module contents

Multipass provider support package.

class craft_providers.multipass.Multipass(*, multipass_path=PosixPath('multipass'))[source]

Bases: object

Wrapper for multipass command.

Parameters

multipass_path (Path) – Path to multipass command to use.

Variables

minimum_required_version – Minimum required version for compatibility.

delete(*, instance_name, purge=True)[source]

Passthrough for running multipass delete.

Parameters

  • instance_name (str) – The name of the instance_name to delete.

  • purge – Flag to purge the instance_name’s image after deleting.

Raises

MultipassError – on error.

Return type

None

exec(*, command, instance_name, runner=<function run>, **kwargs)[source]

Execute command in instance_name with specified runner.

Parameters

  • command (List[str]) – Command to execute in the instance.

  • instance_name (str) – Name of instance to execute in.

  • runner (Callable) – Execution function to invoke, e.g. subprocess.run or Popen. First argument is finalized command with the attached kwargs.

  • kwargs – Additional kwargs for runner.

Returns

Runner’s instance.

info(*, instance_name)[source]

Get information/state for instance.

Return type

Dict[str, Any]

Returns

Parsed json data from info command.

Raises

MultipassError – On error.

Parameters

instance_name (str) –

is_supported_version()[source]

Check if Multipass version is supported.

A helper to check if Multipass meets minimum supported version for craft-providers.

Return type

bool

Returns

True if installed version is supported.

launch(*, instance_name, image, cpus=None, mem=None, disk=None)[source]

Launch multipass VM.

Parameters

  • instance_name (str) – The name the launched instance will have.

  • image (str) – Name of image to create the instance with.

  • cpus (Optional[str]) – Amount of virtual CPUs to assign to the launched instance.

  • mem (Optional[str]) – Amount of RAM to assign to the launched instance.

  • disk (Optional[str]) – Amount of disk space the launched instance will have.

Raises

MultipassError – on error.

Return type

None

list()[source]

List names of VMs.

Return type

List[str]

Returns

Data from stdout if instance exists, else None.

Raises

MultipassError – On error.

minimum_required_version = '1.7'
mount(*, source, target, uid_map=None, gid_map=None)[source]

Mount host source path to target.

Parameters

  • source (Path) – Path of local directory to mount.

  • target (str) – Target mount points, in <name>[:<path>] format, where <name> is an instance name, and optional <path> is the mount point. If omitted, the mount point will be the same as the source’s absolute path.

  • uid_map (Optional[Dict[str, str]]) – A mapping of user IDs for use in the mount of the form <host-id> -> <instance-id>. File and folder ownership will be mapped from <host-id> to <instance-id> inside the instance.

  • gid_map (Optional[Dict[str, str]]) – A mapping of group IDs for use in the mount of the form <host-id> -> <instance-id>. File and folder ownership will be mapped from <host-id> to <instance-id> inside the instance.

Return type

None

start(*, instance_name)[source]

Start VM instance.

Parameters

instance_name (str) – the name of the instance to start.

Raises

MultipassError – on error.

Return type

None

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

Stop VM instance.

Parameters

  • instance_name (str) – the name of the instance_name to stop.

  • delay_mins (int) – Delay shutdown for specified number of minutes.

Raises

MultipassError – on error.

Return type

None

transfer(*, source, destination)[source]

Transfer to destination path with source IO.

Parameters

  • source (str) – The source path, prefixed with <name:> for a path inside the instance.

  • destination (str) – The destination path, prefixed with <name:> for a path inside the instance.

Raises

MultipassError – On error.

Return type

None

transfer_destination_io(*, source, destination, chunk_size=4096)[source]

Transfer from source file to destination IO.

Note that this can’t use std{in,out}=open(…) due to LP #1849753.

Parameters

  • source (str) – The source path, prefixed with <name:> for a path inside the instance.

  • destination (BufferedIOBase) – An IO stream to write to.

  • chunk_size (int) – Number of bytes to transfer at a time. Defaults to 4096.

Raises

MultipassError – On error.

Return type

None

transfer_source_io(*, source, destination, chunk_size=4096)[source]

Transfer to destination path with source IO.

Note that this can’t use std{in,out}=open(…) due to LP #1849753.

Parameters

  • source (BufferedIOBase) – An IO stream to read from.

  • destination (str) – The destination path, prefixed with <name:> for a path inside the instance.

  • chunk_size (int) – Number of bytes to transfer at a time. Defaults to 4096.

Raises

MultipassError – On error.

Return type

None

umount(*, mount)[source]

Unmount target in VM.

Parameters

mount (str) – Mount point in <name>[:<path>] format, where <name> are instance names, and optional <path> are mount points. If omitted, all mounts will be removed from the named instance.

Raises

MultipassError – On error.

Return type

None

version()[source]

Get multipass and multipassd versions.

Return type

Tuple[str, Optional[str]]

Returns

Tuple of parsed versions (multipass, multipassd). multipassd may be None if Multipass is not yet ready.

wait_until_ready(*, retry_wait=0.25, timeout=None)[source]

Wait until Multipass is ready (upon install/startup).

Parameters

  • retry_wait (float) – Time to sleep between retries.

  • timeout (Optional[float]) – Timeout in seconds.

Return type

Tuple[str, Optional[str]]

Returns

Tuple of parsed versions (multipass, multipassd). multipassd may be None if Multipass is not ready and the timeout limit is reached.

exception craft_providers.multipass.MultipassError(brief: str, details: Optional[str] = None, resolution: Optional[str] = None)[source]

Bases: craft_providers.errors.ProviderError

Unexpected Multipass error.

Parameters

  • brief (str) –

  • details (Optional[str]) –

  • resolution (Optional[str]) –

brief: str
exception craft_providers.multipass.MultipassInstallationError(reason, *, details=None)[source]

Bases: craft_providers.multipass.errors.MultipassError

Multipass Installation Error.

Parameters

  • reason (str) – Reason for install failure.

  • details (Optional[str]) – Optional details to include.

brief: str
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

class craft_providers.multipass.MultipassProvider(instance=<craft_providers.multipass.multipass.Multipass object>)[source]

Bases: craft_providers.provider.Provider

Multipass build environment provider.

This class is not stable and is likely to change. This class will be stable and recommended for use in the release of craft-providers 2.0.

Parameters

  • multipass – Optional Multipass client to use.

  • instance (Multipass) –

create_environment(*, instance_name)[source]

Create a bare environment for specified base.

No initializing, launching, or cleaning up of the environment occurs.

Parameters

  • name – Name of the instance.

  • instance_name (str) –

Return type

Executor

classmethod ensure_provider_is_available()[source]

Ensure provider is available, prompting the user to install it if required.

Raises

MultipassError – if provider is not available.

Return type

None

classmethod is_provider_installed()[source]

Check if provider is installed.

Return type

bool

Returns

True if installed.

launched_environment(*, project_name, project_path, base_configuration, build_base, instance_name)[source]

Configure and launch environment for specified base.

When this method loses context, all directories are unmounted and the environment is stopped. For more control of environment setup and teardown, use create_environment() instead.

Parameters

  • project_name (str) – Name of the project.

  • project_path (Path) – Path to project.

  • base_configuration (Base) – Base configuration to apply to instance.

  • build_base (str) – Base to build from.

  • instance_name (str) – Name of the instance to launch.

Return type

Generator[Executor, None, None]

craft_providers.multipass.ensure_multipass_is_ready(*, multipass=<craft_providers.multipass.multipass.Multipass object>)[source]

Ensure Multipass is ready for use.

Raises

MultipassError – on error.

Parameters

multipass (Multipass) –

Return type

None

craft_providers.multipass.install()[source]

Install Multipass.

Return type

str

Returns

Multipass version.

Raises

MultipassInstallationError – on error.

craft_providers.multipass.is_installed()[source]

Check if Multipass is installed (and found on PATH).

Return type

bool

Returns

True if multipass is installed.

craft_providers.multipass.launch(name, *, base_configuration, image_name, cpus=2, disk_gb=64, mem_gb=2, auto_clean=False)[source]

Create, start, and configure instance.

If auto_clean is enabled, automatically delete an existing instance that is deemed to be incompatible, rebuilding it with the specified environment.

Parameters

  • name (str) – Name of instance.

  • base_configuration (Base) – Base configuration to apply to instance.

  • image_name (str) – Multipass image to use, e.g. snapcraft:core20.

  • cpus (int) – Number of CPUs.

  • disk_gb (int) – Disk allocation in gigabytes.

  • mem_gb (int) – Memory allocation in gigabytes.

  • auto_clean (bool) – Automatically clean instance, if incompatible.

Return type

MultipassInstance

Returns

Multipass instance.

Raises