Executors¶
Abstract Executor¶
- class craft_providers.Executor[source]¶
Bases:
abc.ABC
Interfaces to execute commands and move data in/out of an environment.
- abstract execute_popen(command, 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.
- Return type
Popen
- Returns
Popen instance.
- abstract execute_run(command, 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().
- Return type
CompletedProcess
- Returns
Completed process.
- Raises
subprocess.CalledProcessError – if command fails and check is True.
- abstract pull_file(*, source, destination)[source]¶
Copy a file from the environment to host.
- Parameters
source (
Path
) – 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.
- Parameters
source (
Path
) – Host file to copy.destination (
Path
) – 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 a file with specified content and file mode.
- Parameters
destination (
Path
) – 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
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, 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.
- Return type
Popen
- Returns
Popen instance.
- execute_run(command, 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().
- 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 (
Path
) – 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)[source]¶
Launch instance.
- Parameters
image (
str
) – Image name to launch.image_remote (
str
) – Image remote name.uid – 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, device_name=None)[source]¶
Mount host source directory to target mount point.
Checks first to see if already mounted. If no device name is given, it will be generated with the format “disk-{target.as_posix()}”.
- Parameters
host_source (
Path
) – Host path to mount.target (
Path
) – Instance path to mount to.device_name (
Optional
[str
]) – Name for disk device.
- Raises
LXDError – On unexpected error.
- Return type
None
- pull_file(*, source, destination)[source]¶
Copy a file from the environment to host.
- Parameters
source (
Path
) – 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.
- Parameters
source (
Path
) – Host file to copy.destination (
Path
) – 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 file with content and file mode.
- Parameters
destination (
Path
) – 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
- supports_mount()[source]¶
Check if instance supports mounting from host.
- Return type
bool
- Returns
True if mount is supported.
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
]) –
- execute_popen(command, 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().
- Return type
Popen
- Returns
Popen instance.
- execute_run(command, 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().
- 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 (
Path
) – 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 (
Path
) – 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 (
Path
) – 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 (
Path
) – 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 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 (
Path
) – 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
- stop(*, delay_mins=0)[source]¶
Stop instance.
- Parameters
delay_mins (
int
) – Delay shutdown for specified minutes.- Raises
MultipassError – On unexpected failure.
- Return type
None