craft_providers.multipass.multipass module

API provider for Multipass.

This implementation interfaces with multipass using the multipass command-line utility.

class craft_providers.multipass.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.