craft_parts package

Subpackages

Submodules

Module contents

Craft a project from several parts.

class craft_parts.Action(part_name, step, action_type=ActionType.RUN, reason=None, project_vars=None, properties=ActionProperties(changed_files=None, changed_dirs=None))[source]

Bases: object

The action to be executed for a given part.

Actions correspond to the operations required to run the lifecycle for each of the parts in the project specification.

Parameters:
  • part_name (str) – The name of the part this action will be performed on.

  • step (Step) – The Step this action will execute.

  • action_type (ActionType) – Action to run for this step.

  • reason (Optional[str]) – A textual description of why this action should be executed.

  • project_vars (Optional[Dict[str, ProjectVar]]) – The values of project variables from a previous execution, used if the action type is ActionType.SKIP.

  • properties (ActionProperties) –

action_type: ActionType = 0
part_name: str
project_vars: Optional[Dict[str, ProjectVar]] = None
properties: ActionProperties = ActionProperties(changed_files=None, changed_dirs=None)
reason: Optional[str] = None
step: Step
class craft_parts.ActionProperties(changed_files=None, changed_dirs=None)[source]

Bases: object

Properties defined for an action.

Parameters:
  • changed_files (Optional[List[str]]) –

  • changed_dirs (Optional[List[str]]) –

changed_dirs: Optional[List[str]] = None
changed_files: Optional[List[str]] = None
class craft_parts.ActionType(value)[source]

Bases: IntEnum

The type of action to be executed.

Action execution can be modified according to its type:

RUN: execute the expected commands for step processing.

RERUN: clear the existing data and state before proceeding.

UPDATE: try to continue processing the step.

SKIP: don’t execute this action.

REAPPLY: run the step commands without updating its state.

REAPPLY = 4
RERUN = 1
RUN = 0
SKIP = 2
UPDATE = 3
class craft_parts.Features(enable_overlay=False, enable_partitions=False)[source]

Bases: object

Configurable craft-parts features.

Variables:
  • enable_overlay – Enables the overlay step.

  • enable_partitions – Enables the usage of partitions.

Parameters:
  • enable_overlay (bool) –

  • enable_partitions (bool) –

enable_overlay: bool = False
enable_partitions: bool = False
classmethod reset()[source]

Delete stored class instance.

Return type:

None

class craft_parts.LifecycleManager(all_parts, *, application_name, cache_dir, work_dir='.', arch='', base='', project_name=None, parallel_build_count=1, application_package_name=None, ignore_local_sources=None, extra_build_packages=None, extra_build_snaps=None, track_stage_packages=False, strict_mode=False, base_layer_dir=None, base_layer_hash=None, project_vars_part_name=None, project_vars=None, partitions=None, **custom_args)[source]

Bases: object

Coordinate the planning and execution of the parts lifecycle.

The lifecycle manager determines the list of actions that needs be executed in order to obtain a tree of installed files from the specification on how to process its parts, and provides a mechanism to execute each of these actions.

Parameters:
  • all_parts (Dict[str, Any]) – A dictionary containing the parts specification according to the parts schema. The format is compatible with the output generated by PyYAML’s yaml.load.

  • application_name (str) – A unique non-empty identifier for the application using Craft Parts. Valid application names contain upper and lower case letters, underscores or numbers, and must start with a letter.

  • project_name (Optional[str]) – name of the project being built.

  • cache_dir (Union[Path, str]) – The path to store cached packages and files. If not specified, a directory under the application name entry in the XDG base directory will be used.

  • work_dir (Union[Path, str]) – The toplevel directory for work directories. The current directory will be used if none is specified.

  • arch (str) – The architecture to build for. Defaults to the host system architecture.

  • base (str) – [deprecated] The system base the project being processed will run on. Defaults to the system where Craft Parts is being executed.

  • parallel_build_count (int) – The maximum number of concurrent jobs to be used to build each part of this project.

  • application_package_name (Optional[str]) – The name of the application package, if required by the package manager used by the platform. Defaults to the application name.

  • ignore_local_sources (Optional[List[str]]) – A list of local source patterns to ignore.

  • extra_build_packages (Optional[List[str]]) – A list of additional build packages to install.

  • extra_build_snaps (Optional[List[str]]) – A list of additional build snaps to install.

  • track_stage_packages (bool) – Add primed stage packages to the prime state.

  • strict_mode (bool) – Only allow plugins capable of building in strict mode.

  • base_layer_dir (Optional[Path]) – The path to the overlay base layer, if using overlays.

  • base_layer_hash (Optional[bytes]) – The validation hash of the overlay base image, if using overlays. The validation hash should be constant for a given image, and should change if a different base image is used.

  • project_vars_part_name (Optional[str]) – Project variables can only be set in the part matching this name.

  • project_vars (Optional[Dict[str, str]]) – A dictionary containing project variables.

  • partitions (Optional[List[str]]) – A list of partitions to use when the partitions feature is enabled. The first partition must be “default” and all partitions must be lowercase alphabetical.

  • custom_args (Any) – Any additional arguments that will be passed directly to callbacks.

action_executor()[source]

Return a context manager for action execution.

Return type:

ExecutionContext

clean(step=Step.PULL, *, part_names=None)[source]

Clean the specified step and parts.

Cleaning a step removes its state and all artifacts generated in that step and subsequent steps for the specified parts.

Parameters:
  • step (Step) – The step to clean. If not specified, all steps will be cleaned.

  • part_names (Optional[List[str]]) – The list of part names to clean. If not specified, all parts will be cleaned and work directories will be removed.

Return type:

None

get_primed_stage_packages(*, part_name)[source]

Return the list of primed stage packages.

Parameters:

part_name (str) – The name of the part to get primed stage packages from.

Return type:

Optional[List[str]]

Returns:

The sorted list of primed stage packages, or None if no state found.

get_pull_assets(*, part_name)[source]

Return the part’s pull state assets.

Parameters:

part_name (str) – The name of the part to get assets from.

Return type:

Optional[Dict[str, Any]]

Returns:

The dictionary of the part’s pull assets, or None if no state found.

plan(target_step, part_names=None)[source]

Obtain the list of actions to be executed given the target step and parts.

Parameters:
  • target_step (Step) – The final step we want to reach.

  • part_names (Optional[Sequence[str]]) – The list of parts to process. If not specified, all parts will be processed.

Return type:

List[Action]

Returns:

The list of Action objects that should be executed in order to reach the target step for the specified parts.

property project_info: ProjectInfo

Obtain information about this project.

Return type:

ProjectInfo

refresh_packages_list()[source]

Update the available packages list.

The list of available packages should be updated before planning the sequence of actions to take. To ensure consistency between the scenarios, it shouldn’t be updated between planning and execution.

Return type:

None

reload_state()[source]

Reload the ephemeral state from disk.

Return type:

None

class craft_parts.Part(name, data, *, project_dirs=None, plugin_properties=None, partitions=None)[source]

Bases: object

Each of the components used in the project specification.

During the craft-parts lifecycle each part is processed through different steps in order to obtain its final artifacts. The Part class holds the part specification data and additional configuration information used during step processing.

Parameters:
  • name (str) – The part name.

  • data (Dict[str, Any]) – A dictionary containing the part properties.

  • partitions (Optional[Sequence[str]]) – A Sequence of partition names if partitions are enabled, or None

  • project_dirs (Optional[ProjectDirs]) – The project work directories.

  • plugin_properties (Optional[PluginProperties]) – An optional PluginProperties object for this plugin.

Raises:

PartSpecificationError – If part validation fails.

property base_prime_dir: Path

Return the primed tree containing the artifacts to deploy.

If partitions are enabled, this is the directory containing those partitions.

Return type:

Path

property base_stage_dir: Path

Return the base staging area.

If partitions are enabled, this is the directory containing those partitions.

Return type:

Path

check_partition_usage(partitions)[source]

Check if partitions are properly used in a part.

Parameters:

partitions (List[str]) – The list of valid partitions.

Return type:

List[str]

Returns:

A list of invalid uses of partitions in the part.

property dependencies: List[str]

Return the list of parts this part depends on.

Return type:

List[str]

property has_overlay: bool

Return whether this part declares overlay content.

Return type:

bool

property overlay_dir: Path

Return the overlay directory.

Return type:

Path

property part_base_install_dir: Path

The base of the part’s install directories.

With partitions disabled, this is the install directory. With partitions enabled, this is the directory containing the partitions.

A full path to an install location can always be found with: part.part_base_install_dir / get_partition_compatible_filepath(location)

Return type:

Path

property part_build_dir: Path

Return the subdirectory containing the part build tree.

Return type:

Path

property part_build_subdir: Path

Return the subdirectory in build containing the source subtree (if any).

Parts that have a source subdirectory and do not support out-of-source builds will have a build subdirectory.

Return type:

Path

property part_cache_dir: Path

Return the subdirectory containing the part cache directory.

Return type:

Path

property part_install_dir: Path

Return the subdirectory to install the part build artifacts.

With partitions disabled, this is the install directory and is the same as part_base_install_dir With partitions enabled, this is the install directory for the default partition

Return type:

Path

property part_install_dirs: Mapping[Optional[str], Path]

Return a mapping of partition names to install directories.

With partitions disabled, the only partition name is None

Return type:

Mapping[Optional[str], Path]

property part_layer_dir: Path

Return the subdirectory containing the part overlay files.

Return type:

Path

property part_packages_dir: Path

Return the subdirectory containing the part stage packages directory.

Return type:

Path

property part_run_dir: Path

Return the subdirectory containing the part plugin scripts.

Return type:

Path

property part_snaps_dir: Path

Return the subdirectory containing the part snap packages directory.

Return type:

Path

property part_src_dir: Path

Return the subdirectory containing the part source code.

Return type:

Path

property part_src_subdir: Path

Return the subdirectory in source containing the source subtree (if any).

Return type:

Path

property part_state_dir: Path

Return the subdirectory containing the part lifecycle state.

Return type:

Path

property parts_dir: Path

Return the directory containing work files for each part.

Return type:

Path

property prime_dir: Path

Return the primed tree containing the artifacts to deploy.

If partitions are enabled, this is the prime directory for the default partition

Return type:

Path

property prime_dirs: Mapping[Optional[str], Path]

A mapping of partition name to partition prime directory.

If partitions are disabled, the only key is None.

Return type:

Mapping[Optional[str], Path]

property stage_dir: Path

Return the staging area containing the installed files from all parts.

If partitions are enabled, this is the stage directory for the default partition

Return type:

Path

property stage_dirs: Mapping[Optional[str], Path]

A mapping of partition name to partition staging directory.

If partitions are disabled, the only key is None.

Return type:

Mapping[Optional[str], Path]

class craft_parts.PartInfo(project_info, part)[source]

Bases: object

Part-level information containing project and part fields.

Parameters:
  • project_info (ProjectInfo) – The project information.

  • part (Part) – The part we want to obtain information from.

get_project_var(name, *, raw_read=False)[source]

Get the value of a project variable.

Variables must be consumed by the application only after the lifecycle execution ends to prevent unexpected behavior if steps are skipped.

Parameters:
  • name (str) – The project variable name.

  • raw_read (bool) – Whether the variable is read without access verifications.

Return type:

str

Returns:

The value of the variable.

Raises:
  • ValueError – If there is no project variable with the given name.

  • RuntimeError – If the variable is consumed during the lifecycle execution.

property part_build_dir: Path

Return the subdirectory containing the part’s build tree.

Return type:

Path

property part_build_subdir: Path

Return the subdirectory in build containing the source subtree (if any).

Return type:

Path

property part_cache_dir: Path

Return the subdirectory containing this part’s cache directory.

Return type:

Path

property part_install_dir: Path

Return the subdirectory to install the part’s build artifacts.

Return type:

Path

property part_name: str

Return the name of the part we’re providing information about.

Return type:

str

property part_src_dir: Path

Return the subdirectory containing the part’s source code.

Return type:

Path

property part_src_subdir: Path

Return the subdirectory in source containing the source subtree (if any).

Return type:

Path

property part_state_dir: Path

Return the subdirectory containing this part’s lifecycle state.

Return type:

Path

property project_info: ProjectInfo

Return the project information.

Return type:

ProjectInfo

set_project_var(name, value, *, raw_write=False)[source]

Set the value of a project variable.

Variable values can be set once. Project variables are not intended for logic construction in user scripts, setting it multiple times is likely to be an error.

Parameters:
  • name (str) – The project variable name.

  • value (str) – The new project variable value.

  • raw_write (bool) – Whether the variable is written without access verifications.

Raises:
  • ValueError – If there is no custom argument with the given name.

  • RuntimeError – If a write-once variable is set a second time, or if a part name is specified and the variable is set from a different part.

Return type:

None

exception craft_parts.PartsError(brief, details=None, resolution=None)[source]

Bases: Exception

Unexpected 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
class craft_parts.ProjectDirs(*, partitions=None, work_dir='.')[source]

Bases: object

The project’s main work directories.

Parameters:
  • work_dir (Union[Path, str]) – The parent directory containing the parts, prime and stage subdirectories. If not specified, the current directory will be used.

  • partitions (Optional[Sequence[str]]) – If partitions are enabled, the list of partitions.

Variables:
  • work_dir – The root of the work directories used for project processing.

  • parts_dir – The directory containing work subdirectories for each part.

  • overlay_dir – The directory containing work subdirectories for overlays.

  • overlay_mount_dir – The mountpoint for the overlay filesystem.

  • overlay_packages_dir – The cache directory for overlay packages.

  • overlay_work_dir – The work directory for the overlay filesystem.

  • stage_dir – The staging area containing installed files from all parts.

  • prime_dir – The primed tree containing the final artifacts to deploy.

get_prime_dir(partition=None)[source]

Get the stage directory for the given partition.

Parameters:

partition (Optional[str]) –

Return type:

Path

get_stage_dir(partition=None)[source]

Get the stage directory for the given partition.

Parameters:

partition (Optional[str]) –

Return type:

Path

class craft_parts.ProjectInfo(*, application_name, cache_dir, arch='', base='', parallel_build_count=1, strict_mode=False, project_dirs=None, project_name=None, project_vars_part_name=None, project_vars=None, partitions=None, **custom_args)[source]

Bases: object

Project-level information containing project-specific fields.

Parameters:
  • application_name (str) – A unique identifier for the application using Craft Parts.

  • project_name (Optional[str]) – Name of the project being built.

  • cache_dir (Path) – The path to store cached packages and files. If not specified, a directory under the application name entry in the XDG base directory will be used.

  • arch (str) – The architecture to build for. Defaults to the host system architecture.

  • parallel_build_count (int) – The maximum number of concurrent jobs to be used to build each part of this project.

  • strict_mode (bool) – Only allow plugins capable of building in strict mode.

  • project_dirs (Optional[ProjectDirs]) – The project work directories.

  • project_name – The name of the project.

  • project_vars_part_name (Optional[str]) – Project variables can be set only if the part name matches this name.

  • project_vars (Optional[Dict[str, str]]) – A dictionary containing the project variables.

  • custom_args (Any) – Any additional arguments defined by the application when creating a LifecycleManager.

  • partitions (Optional[List[str]]) – A list of partitions.

  • base (str) –

property application_name: str

Return the name of the application using craft-parts.

Return type:

str

property arch_build_for: str

The architecture we are building for.

Return type:

str

property arch_build_on: str

The architecture we are building on.

Return type:

str

property arch_triplet: str

Return the machine-vendor-os platform triplet definition.

Return type:

str

property arch_triplet_build_for: str

The machine-vendor-os triplet for the platform we are building for.

Return type:

str

property arch_triplet_build_on: str

The machine-vendor-os triplet for the platform we are building on.

Return type:

str

property base: str

Return the project build base.

Return type:

str

property cache_dir: Path

Return the directory used to store cached files.

Return type:

Path

property custom_args: List[str]

Return the list of custom argument names.

Return type:

List[str]

property dirs: ProjectDirs

Return the project’s work directories.

Return type:

ProjectDirs

get_project_var(name, *, raw_read=False)[source]

Get the value of a project variable.

Variables must be consumed by the application only after the lifecycle execution ends to prevent unexpected behavior if steps are skipped.

Parameters:
  • name (str) – The project variable name.

  • raw_read (bool) – Whether the variable is read without access verifications.

Return type:

str

Returns:

The value of the variable.

Raises:
  • ValueError – If there is no project variable with the given name.

  • RuntimeError – If the variable is consumed during the lifecycle execution.

property host_arch: str

Return the host architecture used for debs, snaps and charms.

Return type:

str

property is_cross_compiling: bool

Whether the target and host architectures are different.

Return type:

bool

property parallel_build_count: int

Return the maximum allowable number of concurrent build jobs.

Return type:

int

property partitions: Optional[List[str]]

Return the project’s partitions.

Return type:

Optional[List[str]]

property project_name: Optional[str]

Return the name of the project using craft-parts.

Return type:

Optional[str]

property project_options: Dict[str, Any]

Obtain a project-wide options dictionary.

Return type:

Dict[str, Any]

property project_vars_part_name: Optional[str]

Return the name of the part that can set project vars.

Return type:

Optional[str]

set_project_var(name, value, raw_write=False, *, part_name=None)[source]

Set the value of a project variable.

Variable values can be set once. Project variables are not intended for logic construction in user scripts, setting it multiple times is likely to be an error.

Parameters:
  • name (str) – The project variable name.

  • value (str) – The new project variable value.

  • part_name (Optional[str]) – If not None, variable setting is restricted to the named part.

  • raw_write (bool) – Whether the variable is written without access verifications.

Raises:
  • ValueError – If there is no custom argument with the given name.

  • RuntimeError – If a write-once variable is set a second time, or if a part name is specified and the variable is set from a different part.

Return type:

None

property strict_mode: bool

Return whether this project must be built in ‘strict’ mode.

Return type:

bool

property target_arch: str

Return the target architecture used for debs, snaps and charms.

Return type:

str

class craft_parts.Step(value)[source]

Bases: IntEnum

All the steps needed to fully process a part.

Steps correspond to the tasks that must be fulfilled in order to process each of the parts in the project specification. In the PULL step sources for a part are retrieved and unpacked. The OVERLAY step is used to change the underlying filesystem. In the BUILD step artifacts are built and installed. In the STAGE step installed build artifacts from all parts and overlay contents are added to a staging area. These files are further processed in the PRIME step to obtain the final tree with the final payload for deployment.

BUILD = 3
OVERLAY = 2
PRIME = 5
PULL = 1
STAGE = 4
next_steps()[source]

List the steps that should happen after the current step.

Return type:

List[Step]

Returns:

The list of next steps.

previous_steps()[source]

List the steps that should happen before the current step.

Return type:

List[Step]

Returns:

The list of previous steps.

class craft_parts.StepInfo(part_info, step)[source]

Bases: object

Step-level information containing project, part, and step fields.

Parameters:
  • part_info (PartInfo) – The part information.

  • step (Step) – The step we want to obtain information from.

craft_parts.expand_environment(data, *, info, skip=None)[source]

Replace global variables with their values.

Global variables are defined by craft-parts and are the subset of the CRAFT_* step execution environment variables that don’t depend on the part or step being executed. The list of global variables include CRAFT_ARCH_TRIPLET, CRAFT_PROJECT_DIR, CRAFT_STAGE and CRAFT_PRIME. Additional global variables can be defined by the application using craft-parts.

Parameters:
  • data (Dict[str, Any]) – A dictionary whose values will have variable names expanded.

  • info (ProjectInfo) – The project information.

  • skip (Optional[List[str]]) – Keys to skip when performing expansion.

Return type:

None

craft_parts.part_has_overlay(data)[source]

Whether the part described by data employs the Overlay step.

Parameters:

data (Dict[str, Any]) – The part data to query for overlay use.

Return type:

bool

craft_parts.validate_part(data)[source]

Validate the given part data against common and plugin models.

Parameters:

data (Dict[str, Any]) – The part data to validate.

Return type:

None