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
]) –
- 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
- 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.
- 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
- Returns
Multipass instance.
- Raises
BaseConfigurationError – on unexpected error configuration base.
MultipassError – on unexpected Multipass error.