craft_parts.parts module

Definitions and helpers to handle parts.

class craft_parts.parts.Part(name, data, *, project_dirs=None, plugin_properties=None, partitions=None)

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 (Sequence[str] | None) – A Sequence of partition names if partitions are enabled, or None

• project_dirs (ProjectDirs | None) – The project work directories.

• plugin_properties (PluginProperties | None) – An optional PluginProperties object for this plugin.

Raises:

PartSpecificationError – If part validation fails.

property backstage_dir: Path

Return the backstage area containing internal artifacts from all parts.

property default_partition: str

Get the “default” partition from a partition list.

property dependencies: list[str]

Return the list of parts this part depends on.

property has_chisel_as_build_snap: bool

Return whether this part has chisel in its build-snaps.

property has_overlay: bool

Return whether this part declares overlay content.

property has_slices: bool

Return whether this part has slices in its stage-packages.

property organizes_to_overlay: bool

Return whether this part organizes files to overlay.

property overlay_dir: Path

Return the overlay directory.

property overlay_dirs: Mapping[str | None, Path]

A mapping of partition name to partition overlay directory.

If partitions are disabled, the only key is None.

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_export_dir: Path

Return the subdirectory to install internal part build artifacts.

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_layer_dirs: Mapping[str | None, Path]

Return a mapping of partition names to layer directories.

With partitions disabled, the only partition name is None

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.parts.PartSpec(**data)

Bases: BaseModel

The part specification data.

Parameters:

data (Any)

after: list[str]

The parts to process before starting this part’s build.

During the build step, this part waits for all of the listed parts to reach the stage step before it begins building.

The purpose of this key is to stagger the part processing order so that interrelated parts can provide data to each other.

When this key is set, the part queue follows modified rules during the lifecycle:

• Parts are processed alphabetically by name.

• When the build reaches a part that another depends on, the dependent part will only start its build and stage steps after the initial part finishes its stage step.

• After the string of dependent parts completes their lifecycles, the queue continues to the next part in alphabetical order.

build_attributes: list[str]

Special identifiers that change some features and behaviors during the build.

Values

Value	Description
enable-usrmerge	Fills the ${CRAFT_PART_INSTALL} directory with a merged /usr directory before running the part’s build step.
disable-usrmerge	Prevents a merged /usr directory from being assembled for the build step. Available in lifecycles in which the directory would be merged by default.

build_environment: list[dict[str, str]]

build_packages: list[str]

The packages to install during the build step, before the build starts. The part installs them into the build environment using the host’s native package manager.

Build packages must be listed by their name on the host system.

build_snaps: list[str]

The snaps to install during the build step, before the build starts. The part makes them available in the build environment.

Entries can be listed in one of three formats.

• <snap-name>

• <snap-name>/<channel-name>

• <snap-name>/<channel-name>/<version-name>

If no version or channel is provided, latest/stable is used.

disable_parallel: bool

Whether to disable CPU multithreading during the build step.

If unset, the build defaults to multithreading.

get_scriptlet(step)

Return the scriptlet contents, if any, for the given step.

Parameters:

step (Step) – the step corresponding to the scriptlet to be retrieved.

Return type:

str | None

Returns:

The scriptlet for the given step, if any.

property has_chisel_as_build_snap: bool

Return whether the part has chisel as build snap.

property has_overlay: bool

Return whether this spec declares overlay content.

property has_slices: bool

Return whether the part contains chisel slices.

marshal()

Create a dictionary containing the part specification data.

Return type:

dict[str, Any]

Returns:

The newly created dictionary.

model_config: ClassVar[ConfigDict] = {'alias_generator': <function PartSpec.<lambda>>, 'coerce_numbers_to_str': True, 'extra': 'forbid', 'frozen': True, 'validate_assignment': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

organize_files: dict[str, str]

A map of files from the build directory to their destinations in the stage directory.

Each pair of source and destination paths is represented as a nested key of the form <source-path>: <destination-path>.

At the end of the build step, the files at the source paths are copied to their destination paths in the stage directory.

property organizes_to_overlay: bool

Return whether the part organizes file to the overlay.

overlay_files: list[str]

overlay_packages: list[str]

The packages to install in the part’s overlay filesystem.

During the overlay step, these packages are installed into the part’s overlay filesystem using the base layer’s package manager.

overlay_script: str | None

The commands to run after the part’s overlay packages are installed.

If unset, the part’s overlay filesystem will only contain the packages specified in overlay-packages.

override_build: str | None

The commands to run instead of the default behavior of the build step.

The standard build step actions can be performed by calling craftctl default.

Excluding craftctl default, these commands don’t respect the source-subdir value and are executed on the source’s root directory.

override_prime: str | None

The commands to run instead of the default behavior of the prime step.

The standard prime step actions can be performed by calling craftctl default.

override_pull: str | None

The commands to run instead of the default behavior of the pull step.

The standard pull step actions can be performed by calling craftctl default.

override_stage: str | None

The commands to run instead of the default behavior of the stage step.

The standard stage step actions can be performed by calling craftctl default.

permissions: list[Permissions]

The ownership and permission settings for a set of files in the part’s prime directory.

The files at path will be assigned an owner and a group, with the read, write, and execute permissions of each being determined by the value of mode.

plugin: str | None

The plugin to build the part with.

During the build step, the plugin prepares the part’s files with the build system of its language or framework.

prime_files: list[Annotated[str]]

During the prime step, any specified files are copied from the stage directory to the final payload.

Paths support wildcards (*) and must be relative to the working directory where they will be used.

source: str | None

The location of the source files for the part.

During the pull step, these files are placed in the part’s build environment.

Enter either an HTTP/HTTPS URL or the path to the local project directory.

source_branch: str

If the source is a Git repository, this key specifies the target branch.

During the pull step, the part fetches the repository from the earliest available commit up to the tip of this branch.

The commit history can be truncated by specifying a source-depth.

This key is mutually incompatible with source-commit and source-tag.

source_channel: str | None

source_checksum: str

The checksum of the downloaded source, to ensure integrity.

During the pull step, the part compares the checksum against that of the downloaded files.

Checksums can be generated with any of the hashing algorithms supported by Python’s hashlib.

source_commit: str

If the source is a Git repository, this key specifies the target commit. Both short and long SHA hashes are supported.

During the pull step, the part fetches the repository from the earliest available commit up to this commit.

The commit history can be truncated by specifying a source-depth.

This key is mutually incompatible with source-branch and source-tag.

source_depth: int

If the source is a Git repository, this key specifies how far back in the commit history to fetch.

During the pull step, the part fetches the repository from the specified commit up to the target commit, the target tag, or the tip of the target branch.

Equivalent to the --depth parameter of git fetch.

If unset, the part fetches the full repository history up to the target commit, the target tag, or the tip of the target branch.

source_subdir: str

The subdirectory of the unpacked source where the build will occur.

During the build step, build commands are restricted to the specified path.

If unset, the build can access the entire file tree of the source.

This key does not affect commands specified with override-build.

source_submodules: list[str] | None

If the source is a Git repository, this key specifies the registered Git submodules that the project also needs.

During the pull step, the part fetches these submodules.

Equivalent to the --recurse-submodules parameter of git clone.

If unset, the part will fetch all of the repository’s submodules.

source_tag: str

If the source is a Git repository, this key specifies the target tag.

During the pull step, the part fetches the repository from the earliest available commit up to the commit with this tag.

The commit history can be truncated by specifying a source-depth.

This key is mutually incompatible with source-branch and source-commit.

source_type: str

The format of the part’s source.

During the pull step, the part expects the source to behave like the specified format.

If unset, the part attempts to auto-detect the format.

Supported formats include container types like .tar files and Debian packages, version-controlled directories like Git repositories, and local files.

Values

Value	Description
deb	Debian package
git	Git repository
rpm	Red Hat package
snap	Snap container format
tar	Tarball archive
zip	ZIP file
local	Local directory or file in the project directory
file	A “plain” file retrieved from the internet

stage_files: list[Annotated[str]]

During the stage step, any specified files are copied from the build directory to the stage directory.

Paths support wildcards (*) and must be relative to the working directory where they will be used.

stage_packages: list[str]

During the stage step, these packages are included in the stage environment alongside the build artifacts.

Chisel slices can be listed using the <package-name>_<slice-name> syntax.

Listing both packages and slices in the same stage-packages key is not currently supported.

stage_snaps: list[str]

During the stage step, these snaps are included in the stage environment.

Entries can be in one of three formats:

• <snap-name>

• <snap-name>/<channel-name>

• <snap-name>/<channel-name>/<version-name>

If an entry contains no version or channel, latest/stable is used.

classmethod unmarshal(data)

Create and populate a new PartSpec object from dictionary data.

The unmarshal method validates entries in the input dictionary, populating the corresponding fields in the data object.

Parameters:

data (dict[str, Any]) – The dictionary data to unmarshal.

Return type:

PartSpec

Returns:

The newly created object.

Raises:

TypeError – If data is not a dictionary.

classmethod validate_overlay_feature(item)

Check if overlay attributes specified when feature is disabled.

Parameters:

item (TypeVar(_T_validate))

Return type:

TypeVar(_T_validate)

classmethod validate_root(values)

Check if the part spec has a valid configuration of packages and slices.

Parameters:

values (dict[str, Any])

Return type:

dict[str, Any]

craft_parts.parts.get_parts_with_overlay(*, part_list)

Obtain a list of parts that declare overlay parameters.

Parameters:

part_list (list[Part]) – A list of all parts in the project.

Return type:

list[Part]

Returns:

A list of parts with overlay parameters.

craft_parts.parts.has_overlay_visibility(part, *, part_list, viewers=None)

Check if a part can see the overlay filesystem.

A part that declares overlay parameters and all parts depending on it are granted permission to see overlay filesystem.

Parameters:

• part (Part) – The part whose overlay visibility will be checked.

• viewers (set[Part] | None) – Parts that are known to have overlay visibility.

• part_list (list[Part]) – A list of all parts in the project.

Return type:

bool

Returns:

Whether the part has overlay visibility.

craft_parts.parts.part_by_name(name, part_list)

Obtain the part with the given name from the part list.

Parameters:

• name (str) – The name of the part to return.

• part_list (list[Part]) – The list of all known parts.

Return type:

Part

Returns:

The part with the given name.

craft_parts.parts.part_dependencies(part, *, part_list, recursive=False)

Return a set of all the parts upon which the named part depends.

Parameters:

• part (Part) – The dependent part.

• part_list (list[Part])

• recursive (bool)

Return type:

set[Part]

Returns:

The set of parts the given part depends on.

craft_parts.parts.part_has_chisel_as_build_snap(data)

Whether the part described by data has chisel in build-snaps.

Parameters:

data (dict[str, Any]) – The part data to query.

Return type:

bool

craft_parts.parts.part_has_overlay(data)

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.parts.part_has_slices(data)

Whether the part described by data contains slices.

Parameters:

data (dict[str, Any]) – The part data to query.

Return type:

bool

craft_parts.parts.part_list_by_name(names, part_list)

Return a list of parts from part_list that are named in names.

Parameters:

• names (Sequence[str] | None) – The list of part names. If the list is empty or not defined, return all parts from part_list.

• part_list (list[Part]) – The list of all known parts.

Return type:

list[Part]

Returns:

The list of parts corresponding to the given names.

Raises:

InvalidPartName – if a part name is not defined.

craft_parts.parts.sort_parts(part_list)

Perform an inefficient but easy to follow sorting of parts.

Parameters:

part_list (list[Part]) – The list of parts to sort.

Return type:

list[Part]

Returns:

The sorted list of parts.

Raises:

PartDependencyCycle – if there are circular dependencies.

craft_parts.parts.validate_part(data)

Validate the given part data against common and plugin models.

Parameters:

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

Return type:

None