craft_parts.plugins package

Submodules

Module contents

Craft Parts plugins subsystem.

class craft_parts.plugins.Plugin(*, properties, part_info)[source]

Bases: ABC

The base class for plugins.

Variables:

  • properties_class – The plugin properties class.

  • validator_class – The plugin environment validator class.

Parameters:

  • part_info (PartInfo) – The part information for the applicable part.

  • properties (PluginProperties) – Part-defined properties.

abstract get_build_commands()[source]

Return a list of commands to run during the build step.

Return type:

list[str]

abstract get_build_environment()[source]

Return a dictionary with the environment to use in the build step.

Return type:

dict[str, str]

abstract get_build_packages()[source]

Return a set of required packages to install in the build environment.

Return type:

set[str]

abstract get_build_snaps()[source]

Return a set of required snaps to install in the build environment.

Return type:

set[str]

classmethod get_out_of_source_build()[source]

Return whether the plugin performs out-of-source-tree builds.

Return type:

bool

get_pull_commands()[source]

Return the commands to retrieve dependencies during the pull step.

Return type:

list[str]

properties_class: type[PluginProperties]
set_action_properties(action_properties)[source]

Store a copy of the given action properties.

Parameters:

action_properties (ActionProperties) – The properties to store.

Return type:

None

supports_strict_mode = False

Plugins that can run in ‘strict’ mode must set this classvar to True.

validator_class

alias of PluginEnvironmentValidator

class craft_parts.plugins.PluginEnvironmentValidator(*, part_name, env, properties)[source]

Bases: object

Base class for plugin environment validators.

Plugins may require certain environment elements to be present in order to build a part, regardless of how these elements were installed on the system. For example, a compiler may have been installed from a deb package, a snap, built from sources or even built by a different part. Plugin environment validators allow a plugin to ensure its execution environment is correct before building a part.

Parameters:

  • part_name (str) – The part whose build environment is being validated.

  • env (str) – A string containing the build step environment setup.

  • properties (PluginProperties)

validate_dependency(dependency, plugin_name, part_dependencies, argument='--version')[source]

Validate that the environment has a required dependency.

<dependency-name> –version is executed to confirm the dependency is valid.

Parameters:

  • dependency (str) – name of the dependency to validate.

  • plugin_name (str) – used to generate the part name that would satisfy the dependency.

  • part_dependencies (list[str] | None) – A list of the parts this part depends on.

  • argument (str) – argument to call with the dependency. Default is –version.

Raises:

PluginEnvironmentValidationError – If the environment is invalid.

Return type:

str

Returns:

output from executed dependency

validate_environment(*, part_dependencies=None)[source]

Ensure the plugin execution environment is valid.

The environment is verified twice: during the execution prologue after build packages and snaps are installed (to provide an early error message if the environment is invalid), and before running the build step for the part. During the prologue validation the environment may be incomplete, so we pass a list of the part dependencies as a hint of which parts may be used to build the environment.

Parameters:

part_dependencies (Optional[list[str]]) – A list of the parts this part depends on, so the validator can check if the required environment elements are supplied by another part when the method is called from the execution prologue. If the validation fails and list is empty, the error is final (the missing elements can’t be supplied by a different part). The plugin may require a specific part name as a hint that the part will attempt to supply missing environment elements.

Raises:

PluginEnvironmentValidationError – If the environment is invalid.

Return type:

None

class craft_parts.plugins.PluginProperties(**data)[source]

Bases: BaseModel

Options specific to a plugin.

PluginProperties should be subclassed into plugin-specific property classes and populated from a dictionary containing part properties.

By default all plugin properties will be compared to check if the build step is dirty. This can be overridden in each plugin if needed.

Parameters:

data (Any)

classmethod get_build_properties()[source]

Obtain the list of properties affecting the build stage.

Return type:

list[str]

classmethod get_pull_properties()[source]

Obtain the list of properties affecting the pull stage.

Return type:

list[str]

marshal()[source]

Obtain a dictionary containing the plugin properties.

Return type:

dict[str, Any]

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 PluginProperties.<lambda>>, '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]] = {'plugin': FieldInfo(annotation=str, required=False, default='', alias='plugin', alias_priority=1), 'source': FieldInfo(annotation=Union[str, NoneType], required=False, default=None, alias='source', 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.

classmethod model_properties(cls)[source]

Get the properties for this model from the JSON schema.

Return type:

dict[str, dict[str, Any]]

plugin: str
source: str | None
classmethod unmarshal(data)[source]

Populate class attributes from the part specification.

Parameters:

data (dict[str, Any]) – A dictionary containing part properties.

Return type:

Self

Returns:

The populated plugin properties data object.

craft_parts.plugins.extract_part_properties(data, *, plugin_name)[source]

Get common part properties without plugin-specific entries.

Parameters:

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

  • plugin_name (str) – The name of the plugin.

Return type:

dict[str, Any]

Returns:

A dictionary containing only common part properties.

craft_parts.plugins.get_plugin(*, part, part_info, properties)[source]

Obtain a plugin instance for the specified part.

Parameters:

  • part (Part) – The part requesting the plugin.

  • part_info (PartInfo) – The part information data.

  • properties (PluginProperties) – The plugin properties.

Return type:

Plugin

Returns:

The plugin instance.

craft_parts.plugins.get_plugin_class(name)[source]

Obtain a plugin class given the name.

Parameters:

name (str) – The plugin name.

Return type:

type[Plugin]

Returns:

The plugin class.

Raises:

ValueError – If the plugin name is invalid.

craft_parts.plugins.get_registered_plugins()[source]

Return the list of currently registered plugins.

Return type:

dict[str, type[Plugin]]

craft_parts.plugins.register(plugins)[source]

Register part handler plugins.

Parameters:

plugins (dict[str, type[Plugin]]) – a dictionary where the keys are plugin names and values are plugin classes. Valid plugins must subclass class:Plugin.

Return type:

None

craft_parts.plugins.unregister(*plugins)[source]

Unregister plugins by name.

Parameters:

plugins (str)

Return type:

None

craft_parts.plugins.unregister_all()[source]

Unregister all user-registered plugins.

Return type:

None