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: dict[str, ProjectVar] | None = None
properties: ActionProperties = ActionProperties(changed_files=None, changed_dirs=None)
reason: str | None = 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: list[str] | None = None
changed_files: list[str] | None = 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 (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 (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”. Partitions may have an optional namespace prefix separated by a forward slash. Partition names must contain one or more lowercase alphanumeric characters or hyphens (“-“), and may not begin or end with a hyphen. Namespace names must consist of only lowercase alphanumeric characters.

  • 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:

list[str] | None

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:

dict[str, Any] | None

Returns:

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

plan(target_step, part_names=None, *, rerun=False)[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.

  • rerun (bool)

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.

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 dependencies: list[str]

Return the list of parts this part depends on.

property has_overlay: bool

Return whether this part declares overlay content.

property overlay_dir: Path

Return the overlay directory.

property part_build_dir: Path

Return the subdirectory containing the part build tree.

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.

property part_cache_dir: Path

Return the subdirectory containing the part cache directory.

property part_install_dir: Path

Return the subdirectory to install the part build artifacts.

property part_install_dirs: Mapping[str | None, Path]

Return a mapping of partition names to install directories.

With partitions disabled, the only partition name is None

property part_layer_dir: Path

Return the subdirectory containing the part overlay files.

property part_packages_dir: Path

Return the subdirectory containing the part stage packages directory.

property part_run_dir: Path

Return the subdirectory containing the part plugin scripts.

property part_snaps_dir: Path

Return the subdirectory containing the part snap packages directory.

property part_src_dir: Path

Return the subdirectory containing the part source code.

property part_src_subdir: Path

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

property part_state_dir: Path

Return the subdirectory containing the part lifecycle state.

property parts_dir: Path

Return the directory containing work files for each part.

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

property prime_dirs: Mapping[str | None, Path]

A mapping of partition name to partition prime directory.

If partitions are disabled, the only key is None.

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

property stage_dirs: Mapping[str | None, Path]

A mapping of partition name to partition staging directory.

If partitions are disabled, the only key is None.

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.

property part_build_subdir: Path

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

property part_cache_dir: Path

Return the subdirectory containing this part’s cache directory.

property part_install_dir: Path

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

property part_name: str

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

property part_src_dir: Path

Return the subdirectory containing the part’s source code.

property part_src_subdir: Path

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

property part_state_dir: Path

Return the subdirectory containing this part’s lifecycle state.

property project_info: ProjectInfo

Return the project information.

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, doc_slug=None)[source]

Bases: Exception

Unexpected error.

Parameters:

  • brief (str) – Brief description of error.

  • details (Optional[str]) – Detailed information.

  • resolution (Optional[str]) – Recommendation, if any.

  • doc_slug (Optional[str]) – Reusable documentation slug for consumers adopting the Craft Parts documentation.

brief: str
details: str | None = None
doc_slug: str | None = None
resolution: str | None = None
class craft_parts.ProjectDirs(*, partitions=None, work_dir='.')[source]

Bases: object

The project’s main work directories.

Parameters:

  • work_dir (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 prime 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, base_layer_dir=None, base_layer_hash=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)

  • base_layer_dir (Optional[Path])

  • base_layer_hash (Optional[bytes])

property application_name: str

Return the name of the application using craft-parts.

property arch_build_for: str

The architecture we are building for.

property arch_build_on: str

The architecture we are building on.

property arch_triplet: str

Return the machine-vendor-os platform triplet definition.

property arch_triplet_build_for: str

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

property arch_triplet_build_on: str

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

property base: str

Return the project build base.

property base_layer_dir: Path | None

Return the directory containing the base layer (if any).

property base_layer_hash: bytes | None

Return the hash of the base layer (if any).

property cache_dir: Path

Return the directory used to store cached files.

property custom_args: list[str]

Return the list of custom argument names.

property dirs: ProjectDirs

Return the project’s work directories.

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.

property is_cross_compiling: bool

Whether the target and host architectures are different.

property parallel_build_count: int

Return the maximum allowable number of concurrent build jobs.

property partitions: list[str] | None

Return the project’s partitions.

property project_name: str | None

Return the name of the project using craft-parts.

property project_options: dict[str, Any]

Obtain a project-wide options dictionary.

property project_vars_part_name: str | None

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

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.

property target_arch: str

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

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