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.

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

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