craft_providers package
Subpackages
- craft_providers.actions package
- craft_providers.bases package
- craft_providers.lxd package
- Submodules
- craft_providers.lxd.errors module
- craft_providers.lxd.installer module
- craft_providers.lxd.launcher module
- craft_providers.lxd.lxc module
- craft_providers.lxd.lxd module
- craft_providers.lxd.lxd_instance module
- craft_providers.lxd.lxd_provider module
- craft_providers.lxd.project module
- craft_providers.lxd.remotes module
- Module contents
- Submodules
- craft_providers.multipass package
- craft_providers.util package
Submodules
Module contents
Craft Providers base package.
- class craft_providers.Base[source]
Bases:
abc.ABCInterface for providers to configure instantiated environments.
Defines how to setup/configure an environment that has been instantiated by a provider and prepare it for some operation, e.g. execute build. It must account for:
the OS type and version.
(2) the provided image that was launched, e.g. bootstrapping a minimal image versus a more fully featured one.
(3) any dependencies that are required for the operation to complete, e.g. installed applications, networking configuration, etc. This includes any environment configuration that the application will assume is available.
- Variables
compatibility_tag – Tag/Version for variant of build configuration and setup. Any change to this version would indicate that prior [versioned] instances are incompatible and must be cleaned. As such, any new value should be unique to old values (e.g. incrementing). It is suggested to extend this tag, not overwrite it, e.g.: compatibility_tag = f”{appname}-{Base.compatibility_tag}.{apprevision}” to ensure base compatibility levels are maintained.
- compatibility_tag: str = 'base-v0'
- abstract get_command_environment()[source]
Get command environment to use when executing commands.
- Return type
Dict[str,Optional[str]]- Returns
Dictionary of environment, allowing None as a value to indicate that a value should be unset.
- abstract setup(*, executor, retry_wait=0.25, timeout=None)[source]
Prepare base instance for use by the application.
Wait for environment to become ready and configure it. At completion of setup, the executor environment should have networking up and have all of the installed dependencies required for subsequent use by the application.
Setup should not be called more than once in a given instance to refresh/update the environment, use warmup for that.
If timeout is specified, abort operation if time has been exceeded.
- Parameters
executor (
Executor) – Executor for target container.retry_wait (
float) – Duration to sleep() between status checks (if required).timeout (
Optional[float]) – Timeout in seconds.
- Raises
BaseCompatibilityError – if instance is incompatible.
BaseConfigurationError – on other unexpected error.
- Return type
None
- abstract wait_until_ready(*, executor, retry_wait=0.25, timeout=None)[source]
Wait until base instance is ready.
Ensure minimum-required boot services are running. This would be used when starting an environment’s container/VM after already [recently] running setup(), e.g. rebooting the instance. Allows the environment to be used without the cost incurred by re-executing the steps unnecessarily.
If timeout is specified, abort operation if time has been exceeded.
- Parameters
executor (
Executor) – Executor for target container.retry_wait (
float) – Duration to sleep() between status checks (if required).timeout (
Optional[float]) – Timeout in seconds.
- Raises
BaseCompatibilityError – if instance is incompatible.
BaseConfigurationError – on other unexpected error.
- Return type
None
- abstract warmup(*, executor, retry_wait=0.25, timeout=None)[source]
Prepare a previously created and setup instance for use by the application.
Ensure the instance is still valid and wait for environment to become ready.
If timeout is specified, abort operation if time has been exceeded.
- Parameters
executor (
Executor) – Executor for target container.retry_wait (
float) – Duration to sleep() between status checks (if required).timeout (
Optional[float]) – Timeout in seconds.
- Raises
BaseCompatibilityError – if instance is incompatible.
BaseConfigurationError – on other unexpected error.
- Return type
None
- class craft_providers.Executor[source]
Bases:
abc.ABCInterfaces to execute commands and move data in/out of an environment.
- abstract execute_popen(command, *, cwd=None, 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.
cwd (
Optional[Path]) –
- Return type
Popen- Returns
Popen instance.
- abstract execute_run(command, *, cwd=None, 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().
cwd (
Optional[Path]) –
- Return type
CompletedProcess- Returns
Completed process.
- Raises
subprocess.CalledProcessError – if command fails and check is True.
- abstract exists()[source]
Check if instance exists.
- Return type
bool- Returns
True if instance exists.
- abstract is_running()[source]
Check if instance is running.
- Return type
bool- Returns
True if instance is running.
- abstract mount(*, host_source, target)[source]
Mount host source directory to target mount point.
- Parameters
host_source (
Path) –target (
Path) –
- Return type
None
- abstract 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.
ProviderError – On error copying file.
- Return type
None
- abstract 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.
ProviderError – On error copying file.
- Return type
None
- abstract push_file_io(*, destination, content, file_mode, group='root', user='root')[source]
Create or replace a file with specified content and file mode.
- Parameters
destination (
PurePath) – 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
- temporarily_pull_file(*, source, missing_ok=False)[source]
Copy a file from the environment to a temporary file in the host.
This is mainly a layer above pull_file that pulls the file into a temporary path which is cleaned later.
Works as a context manager, provides the file path in the host as target.
The temporary file is stored in the home directory where Multipass has access.
- Parameters
source (
Path) – Environment file to copy.missing_ok (
bool) – Do not raise an error if the file does not exist in the environment; in this case the target will be None.
- Raises
FileNotFoundError – If source file or destination’s parent directory does not exist (and missing_ok is False).
ProviderError – On error copying file content.
- Return type
Generator[Optional[Path],None,None]
- class craft_providers.Provider[source]
Bases:
abc.ABCBuild environment provider.
- clean_project_environments(*, instance_name)[source]
Clean the provider environment.
- Parameters
instance_name (
str) – name of the instance to clean- Return type
None
- abstract create_environment(*, instance_name)[source]
Create a bare environment for specified base.
No initializing, launching, or cleaning up of the environment occurs.
- Parameters
instance_name (
str) – name of the instance to create- Return type
- abstract classmethod ensure_provider_is_available()[source]
Ensure provider is available, prompting the user to install it if required.
- Raises
ProviderError – if provider is not available.
- Return type
None
- abstract classmethod is_provider_installed()[source]
Check if provider is installed.
- Return type
bool- Returns
True if installed.
- abstract 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.
- exception craft_providers.ProviderError(brief: str, details: Optional[str] = None, resolution: Optional[str] = None)[source]
Bases:
ExceptionUnexpected error.
- Parameters
brief (
str) – Brief description of error.details (
Optional[str]) – Detailed information.resolution (
Optional[str]) – Recommendation, if any.
- brief: str
- details: Optional[str] = None
- resolution: Optional[str] = None