craft_parts.infos module

Project, part and step information classes.

class craft_parts.infos.PartInfo(project_info, part)

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)

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_dependencies: Sequence[str]

Return the names of the parts that this part depends on.

property part_export_dir: Path

Return the subdirectory for internal artifact output.

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 plugin_name: str

Return the name of the part’s plugin.

property project_info: ProjectInfo

Return the project information.

set_project_var(name, value, *, raw_write=False)

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

class craft_parts.infos.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, filesystem_mounts=None, base_layer_dir=None, base_layer_hash=None, usrmerged_by_default=False, **custom_args)

Bases: object

Project-level information containing project-specific fields.

Parameters:

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

• project_name (str | None) – 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 (ProjectDirs | None) – The project work directories.

• project_name – The name of the project.

• project_vars_part_name (str | None) – Project variables can be set only if the part name matches this name.

• project_vars (dict[str, str] | ProjectVarInfo | None) – A nested dictionary containing project variables and the part that can update each variable. Project variables can also be defined with a deprecated API where project_vars must be a flat (not-nested) dictionary and project_vars_part_name defines the part that can update all project variables.

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

• partitions (list[str] | None) – A list of partitions.

• filesystem_mounts (FilesystemMounts | None) – A dict of filesystem_mounts.

• usrmerged_by_default (bool) – Whether the parts’ install dirs should be filled with usrmerge-safe directories and symlinks prior to a part’s build.

• base (str)

• base_layer_dir (Path | None)

• base_layer_hash (bytes | None)

property alias_partition_dir: Path | None

Partition directory for the default alias partition.

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 default_filesystem_mount: FilesystemMount

Return the project’s default filesystem mount.

property default_partition: str | None

Get the “default” partition from a partition list.

property dirs: ProjectDirs

Return the project’s work directories.

property filesystem_mounts: FilesystemMounts | None

Return the project’s filesystem mounts.

get_project_var(name, *, raw_read=False)

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.

is_default_partition(partition)

Check if given partition is the default one.

Parameters:

partition (str | None)

Return type:

bool

property is_default_partition_aliased: bool

Check if the default partition is aliased.

property overlay_alias_symlink: Path | None

Overlay directory for the default alias partition.

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 parts_alias_symlink: Path | None

Parts directory for the default alias partition.

property prime_alias_symlink: Path | None

Prime directory for the default alias partition.

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

Return the project vars.

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)

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 (str | None) – 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 stage_alias_symlink: Path | None

Stage directory for the default alias partition.

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.

property usrmerged_by_default: bool

Return whether parts should be usrmerged by default.

class craft_parts.infos.ProjectOptions(**data)

Bases: BaseModel

A collection of project-wide options.

Parameters:

• application_name – A unique identifier for the application using Craft Parts.

• arch_triplet – Concatenated cpu-vendor-os platform.

• target_arch – The architecture to build for.

• project_vars – A dictionary containing the project variables.

• project_vars_part_name – Project variables can be set only if the part name matches this name.

• data (Any)

application_name: str

arch_triplet: str

classmethod from_project_info(project_info)

Construct a ProjectOptions instance from a ProjectInfo instance.

Parameters:

project_info (ProjectInfo) – The project information.

Return type:

Self

model_config: ClassVar[ConfigDict] = {}

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

project_vars: ProjectVarInfo

project_vars_part_name: str | None

target_arch: str

class craft_parts.infos.ProjectVar(**data)

Bases: BaseModel

A project variable that can be updated using craftctl.

Parameters:

data (Any)

marshal(attr=None)

Create a dictionary containing the project var data.

Parameters:

attr (str | None) – If provided, return the bare attribute instead of a dictionary of all attributes.

Return type:

dict[str, Any] | str | bool | None

Returns:

The newly created dictionary or a specific attribute.

model_config: ClassVar[ConfigDict] = {'alias_generator': <function ProjectVar.<lambda>>, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}

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

part_name: str | None

The name of the part that can update the project variable.

classmethod unmarshal(data)

Create and populate a new ProjectVar object from a dict.

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

Parameters:

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

Return type:

ProjectVar

Returns:

The newly created object.

Raises:

• TypeError – If data is not a dict.

• pydantic.ValidationError – If the data fails validation.

updated: bool

Whether the variable has already been updated.

value: Annotated[str | None, pydantic.Field(coerce_numbers_to_str=True)]

The value of the project variable.

class craft_parts.infos.ProjectVarInfo(root=PydanticUndefined, **data)

Bases: RootModel[dict[str, str]]

Project variables that can be updated using craftctl.

This class wraps a nested dictionary of project variables. Data is accessed with structured paths.

Parameters:

root (TypeVar(RootModelRootType))

get(*keys)

Get the ProjectVar at a given path.

Parameters:

keys (str) – A structured path to the value.

Return type:

ProjectVar

Returns:

The value for the key.

Raises:

• KeyError – If an item in the path doesn’t exist.

• KeyError – If an item in the path isn’t a dictionary.

• KeyError – If no keys are provided.

• ValueError – If the keys don’t lead to a ProjectVar.

has_key(*keys)

Check if a key exists.

Parameters:

keys (str) – A structured path to the value.

Return type:

bool

Returns:

True if the key exists in the dictionary.

Raises:

KeyError – If no keys are provided.

marshal(attr=None)

Create a dictionary containing the project var info data.

Parameters:

attr (str | None) – The name of a ProjectVar attribute to return in place of the ProjectVar itself. This is useful for: - the StateManager in craft-parts which only needs part names - a PackageService in a downstream application which only needs values

Return type:

dict[str, Any]

Returns:

The newly created dictionary.

model_config: ClassVar[ConfigDict] = {}

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

root: dict[str, ProjectVar | ProjectVarInfo]

A nested dictionary of ProjectVars.

set(*keys, value, overwrite=False)

Set a ProjectVar at a given path.

Parameters:

• keys (str) – A structured path to the value.

• value (str) – The value to set.

• overwrite (bool) – Allow overwriting existing values.

Raises:

• KeyError – If an item in the path isn’t a dictionary.

• KeyError – If no keys are provided.

• ValueError – If the ProjectVar has already been updated and ‘overwrite’ is false.

• ValueError – If the keys don’t lead to a ProjectVar.

Return type:

None

classmethod unmarshal(data)

Create and populate a new ProjectVarInfo object from a dict.

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

Parameters:

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

Return type:

ProjectVarInfo

Returns:

The newly created object.

Raises:

• TypeError – If data is not a dict.

• pydantic.ValidationError – If the data fails validation.

update_from(other, part_name)

Update ProjectVars from another ProjectVarInfo instance for a particular part.

This is useful when updating the Lifecycle’s ProjectVarInfo with data from a state file.

Parameters:

• part_name (str) – Only ProjectVars with this part name are updated.

• other (ProjectVarInfo)

Raises:

TypeError – If the structure is not identical.

Return type:

None

values()

Get values of the project vars.

Return type:

ValuesView[ProjectVar | ProjectVarInfo]

class craft_parts.infos.StepInfo(part_info, step)

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.