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

Bases: BaseModel

The part specification data.

Parameters:

data (Any)

after: list[str]

build_attributes: list[str]

build_environment: list[dict[str, str]]

build_packages: list[str]

build_snaps: list[str]

disable_parallel: bool

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_overlay: bool

Return whether this spec declares overlay content.

marshal()

Create a dictionary containing the part specification data.

Return type:

dict[str, Any]

Returns:

The newly created dictionary.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

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].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'after': FieldInfo(annotation=list[str], required=False, default=[], alias='after', alias_priority=1), 'build_attributes': FieldInfo(annotation=list[str], required=False, default=[], alias='build-attributes', alias_priority=1), 'build_environment': FieldInfo(annotation=list[dict[str, str]], required=False, default=[], alias='build-environment', alias_priority=1), 'build_packages': FieldInfo(annotation=list[str], required=False, default=[], alias='build-packages', alias_priority=1), 'build_snaps': FieldInfo(annotation=list[str], required=False, default=[], alias='build-snaps', alias_priority=1), 'disable_parallel': FieldInfo(annotation=bool, required=False, default=False, alias='disable-parallel', alias_priority=1), 'organize_files': FieldInfo(annotation=dict[str, str], required=False, default_factory=dict, alias='organize', alias_priority=2), 'overlay_files': FieldInfo(annotation=list[str], required=False, default_factory=<lambda>, alias='overlay', alias_priority=2), 'overlay_packages': FieldInfo(annotation=list[str], required=False, default=[], alias='overlay-packages', alias_priority=1), 'overlay_script': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='overlay-script', alias_priority=1), 'override_build': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='override-build', alias_priority=1), 'override_prime': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='override-prime', alias_priority=1), 'override_pull': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='override-pull', alias_priority=1), 'override_stage': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='override-stage', alias_priority=1), 'permissions': FieldInfo(annotation=list[Permissions], required=False, default=[], alias='permissions', alias_priority=1), 'plugin': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='plugin', alias_priority=1), 'prime_files': FieldInfo(annotation=list[Annotated[str, BeforeValidator, FieldInfo(annotation=NoneType, required=True, description='relative path', metadata=[MinLen(min_length=1), _PydanticGeneralMetadata(pattern=re.compile('^[^\\/].*'))])]], required=False, default_factory=<lambda>, alias='prime', alias_priority=2), 'source': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='source', alias_priority=1), 'source_branch': FieldInfo(annotation=str, required=False, default='', alias='source-branch', alias_priority=1), 'source_checksum': FieldInfo(annotation=str, required=False, default='', alias='source-checksum', alias_priority=1), 'source_commit': FieldInfo(annotation=str, required=False, default='', alias='source-commit', alias_priority=1), 'source_depth': FieldInfo(annotation=int, required=False, default=0, alias='source-depth', alias_priority=1), 'source_subdir': FieldInfo(annotation=str, required=False, default='', alias='source-subdir', alias_priority=1), 'source_submodules': FieldInfo(annotation=Union[list[str], NoneType], required=False, default=None, alias='source-submodules', alias_priority=1), 'source_tag': FieldInfo(annotation=str, required=False, default='', alias='source-tag', alias_priority=1), 'source_type': FieldInfo(annotation=str, required=False, default='', alias='source-type', alias_priority=1), 'stage_files': FieldInfo(annotation=list[Annotated[str, BeforeValidator, FieldInfo(annotation=NoneType, required=True, description='relative path', metadata=[MinLen(min_length=1), _PydanticGeneralMetadata(pattern=re.compile('^[^\\/].*'))])]], required=False, default_factory=<lambda>, alias='stage', alias_priority=2), 'stage_packages': FieldInfo(annotation=list[str], required=False, default=[], alias='stage-packages', alias_priority=1), 'stage_snaps': FieldInfo(annotation=list[str], required=False, default=[], alias='stage-snaps', alias_priority=1)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

organize_files: dict[str, str]

overlay_files: list[str]

overlay_packages: list[str]

overlay_script: str | None

override_build: str | None

override_prime: str | None

override_pull: str | None

override_stage: str | None

permissions: list[Permissions]

plugin: str | None

prime_files: list[Annotated[str]]

source: str | None

source_branch: str

source_checksum: str

source_commit: str

source_depth: int

source_subdir: str

source_submodules: list[str] | None

source_tag: str

source_type: str

stage_files: list[Annotated[str]]

stage_packages: list[str]

stage_snaps: list[str]

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 (Any)

Return type:

Any

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 (Optional[set[Part]]) – 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_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_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