craft_parts.state_manager package

Submodules

• craft_parts.state_manager.build_state module
  • BuildState
    • BuildState.assets
    • BuildState.model_config
    • BuildState.overlay_hash
    • BuildState.project_options_of_interest()
    • BuildState.properties_of_interest()
    • BuildState.unmarshal()
• craft_parts.state_manager.overlay_state module
  • OverlayState
    • OverlayState.model_config
    • OverlayState.project_options_of_interest()
    • OverlayState.properties_of_interest()
    • OverlayState.unmarshal()
• craft_parts.state_manager.prime_state module
  • PrimeState
    • PrimeState.dependency_paths
    • PrimeState.model_config
    • PrimeState.primed_stage_packages
    • PrimeState.project_options_of_interest()
    • PrimeState.properties_of_interest()
    • PrimeState.unmarshal()
• craft_parts.state_manager.pull_state module
  • PullState
    • PullState.assets
    • PullState.model_config
    • PullState.outdated_dirs
    • PullState.outdated_files
    • PullState.project_options_of_interest()
    • PullState.properties_of_interest()
    • PullState.unmarshal()
• craft_parts.state_manager.reports module
  • Dependency
    • Dependency.part_name
    • Dependency.step
  • DirtyReport
    • DirtyReport.reason()
  • OutdatedReport
    • OutdatedReport.reason()
• craft_parts.state_manager.stage_state module
  • StageState
    • StageState.backstage_directories
    • StageState.backstage_files
    • StageState.model_config
    • StageState.overlay_hash
    • StageState.project_options_of_interest()
    • StageState.properties_of_interest()
    • StageState.unmarshal()
• craft_parts.state_manager.state_manager module
  • StateManager
    • StateManager.check_if_dirty()
    • StateManager.check_if_outdated()
    • StateManager.clean_part()
    • StateManager.get_outdated_dirs()
    • StateManager.get_outdated_files()
    • StateManager.get_step_state_overlay_hash()
    • StateManager.has_step_run()
    • StateManager.mark_step_updated()
    • StateManager.project_vars()
    • StateManager.set_state()
    • StateManager.should_step_run()
    • StateManager.update_state_timestamp()
• craft_parts.state_manager.states module
  • get_overlay_migration_state_path()
  • get_state_file_timestamp()
  • get_step_state_path()
  • load_overlay_migration_state()
  • load_step_state()
  • remove()
• craft_parts.state_manager.step_state module
  • MigrationContents
    • MigrationContents.directories
    • MigrationContents.files
    • MigrationContents.model_config
  • MigrationState
    • MigrationState.add()
    • MigrationState.contents()
    • MigrationState.directories
    • MigrationState.files
    • MigrationState.marshal()
    • MigrationState.model_config
    • MigrationState.partition
    • MigrationState.partitions_contents
    • MigrationState.unmarshal()
    • MigrationState.write()
  • StepState
    • StepState.diff_project_options_of_interest()
    • StepState.diff_properties_of_interest()
    • StepState.directories
    • StepState.files
    • StepState.model_config
    • StepState.part_properties
    • StepState.partition
    • StepState.partitions_contents
    • StepState.project_options
    • StepState.project_options_of_interest()
    • StepState.properties_of_interest()
    • StepState.unmarshal()
  • validate_hex_string()

Module contents

Part state management.

class craft_parts.state_manager.MigrationContents(**data)

Bases: BaseModel

Files and directories migrated.

Parameters:

data (Any)

directories: set[str]

files: set[str]

model_config: ClassVar[ConfigDict] = {}

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

class craft_parts.state_manager.MigrationState(**data)

Bases: BaseModel

State information collected when migrating steps.

The migration state contains the paths to the files and directories that have been migrated. This information is used to remove migrated files from shared areas on step cleanup.

Parameters:

data (Any)

add(*, files=None, directories=None)

Add files and directories to migrated contents.

Parameters:

• files (set[str] | None)

• directories (set[str] | None)

Return type:

None

contents(partition)

Return migrated contents for a given partition.

Parameters:

partition (str | None)

Return type:

tuple[set[str], set[str]] | None

directories: set[str]

files: set[str]

marshal()

Create a dictionary containing the part state data.

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

partition: str | None

partitions_contents: dict[str, MigrationContents]

classmethod unmarshal(data)

Create and populate a new state object from dictionary data.

Parameters:

data (dict[str, Any]) – A dictionary containing the data to unmarshal.

Return type:

MigrationState

Returns:

The state object containing the migration data.

write(filepath)

Write state data to disk.

Parameters:

filepath (Path) – The path to the file to write.

Return type:

None

class craft_parts.state_manager.StateManager(*, project_info, part_list, ignore_outdated=None)

Bases: object

Keep track of lifecycle execution state.

The State Manager tells whether a step should run based on current state information. The state database is initialized from state on disk, and after that it’s maintained only in memory.

Parameters:

• project_info (ProjectInfo) – The project information.

• part_list (list[Part]) – A list of this project’s parts.

• ignore_outdated (list[str] | None) – A list of file patterns to ignore when testing for outdated files.

check_if_dirty(part, step)

Verify whether a step is dirty.

A step is considered to be dirty if relevant properties or project options have changed since the step was executed. This means the step needs to be cleaned and run again. This is in contrast to an “outdated” step, which typically doesn’t need to be cleaned, just updated with files from an earlier step in the lifecycle.

Parameters:

• part (Part) – The part the step to be checked belongs to.

• step (Step) – The step to be checked.

Return type:

DirtyReport | None

Returns:

A class:DirtyReport if the step is outdated, None otherwise.

check_if_outdated(part, step)

Verify whether a step is outdated.

A step is considered to be outdated if an earlier step in the lifecycle has been run more recently, or if the source code changed on disk. This means the step needs to be updated by taking modified files from the previous step. This is in contrast to a “dirty” step, which must be cleaned and run again.

Parameters:

• part (Part) – The part the step to be checked belongs to.

• step (Step) – The step to be checked.

Return type:

OutdatedReport | None

Returns:

An class:OutdatedReport if the step is outdated, None otherwise.

clean_part(part, step)

Remove the state for this and later steps in the given part.

Parameters:

• part (Part) – The part corresponding to the state to remove.

• step (Step) – The step corresponding to the state to remove.

Return type:

None

get_outdated_dirs(part)

Get the list of outdated directories for this part.

Parameters:

part (Part) – The part being processed.

Return type:

list[str] | None

Returns:

The list of outdated directories from the part’s pull step.

get_outdated_files(part)

Get the list of outdated files for this part.

Parameters:

part (Part) – The part being processed.

Return type:

list[str] | None

Returns:

The list of outdated files from the part’s pull step.

get_step_state_overlay_hash(part, step)

Get the overlay hash from the step state.

Parameters:

• part (Part) – The part being processed.

• part – The step being processed.

• step (Step)

Return type:

bytes

Returns:

The hash value for the layer corresponding to the part being processed.

has_step_run(part, step)

Determine if a given step of a given part has already run.

Parameters:

• part (Part) – The part the step to be verified belongs to.

• step (Step) – The step to verify.

Return type:

bool

Returns:

Whether the step has already run.

mark_step_updated(part, step)

Mark the given part and step as updated.

Parameters:

• part (Part) – The part being processed.

• part – The step being processed.

• step (Step)

Return type:

None

project_vars(part, step)

Obtain the project variables for a given part and step.

Parameters:

• part (Part) – The part corresponding to the state to retrieve.

• part – The step corresponding to the state to retrieve.

• step (Step)

Return type:

ProjectVarInfo | None

Returns:

The project variables from the last execution.

set_state(part, step, *, state)

Set the state of the given part and step.

Parameters:

• part (Part) – The part corresponding to the state to be set.

• step (Step) – The step corresponding to the state to be set.

• state (StepState)

Return type:

None

should_step_run(part, step)

Determine if a given step of a given part should run.

A given step should run if:

1. it hasn’t already run

2. it’s dirty

3. it’s outdated

4. either (1), (2), or (3) apply to any earlier steps in the part’s lifecycle.

Parameters:

• part (Part) – The part the step to be verified belongs to.

• step (Step) – The step to verify.

Return type:

bool

Returns:

Whether the step should run.

update_state_timestamp(part, step)

Mark the step as recently modified.

Parameters:

• part (Part) – The part corresponding to the state to update.

• step (Step) – The step corresponding to the state to update.

Return type:

None

class craft_parts.state_manager.StepState(**data)

Bases: MigrationState, ABC

Contextual information collected when a step is executed.

The step state contains environmental and project-specific configuration data collected at step run time. Those properties are used to decide whether the step should run again on a new lifecycle execution.

Parameters:

data (Any)

diff_project_options_of_interest(other_project_options)

Return project options that differ.

Take a dictionary of project_options and compare to our own, returning the set of project option names that are different. Both dictionaries are filtered prior to comparison, only relevant options are compared.

Parameters:

other_project_options (ProjectOptions) – The project options to compare to the project options stored in this state.

Return type:

set[str]

diff_properties_of_interest(other_properties, also_compare=None)

Return properties of interest that differ.

Take a dictionary of properties and compare to our own, returning the set of property names that are different. Both dictionaries are filtered prior to comparison, only relevant properties are compared.

Parameters:

• other_properties (dict[str, Any]) – The properties to compare to the project options stored in this state.

• also_compare (list[str] | None)

Return type:

set[str]

model_config: ClassVar[ConfigDict] = {'alias_generator': <function StepState.<lambda>>, 'extra': 'ignore', 'frozen': True, '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_properties: dict[str, Any]

project_options: ProjectOptions

abstract project_options_of_interest(project_options)

Return relevant project options concerning this step.

Parameters:

project_options (ProjectOptions)

Return type:

dict[str, Any]

abstract properties_of_interest(part_properties, *, extra_properties=None)

Return relevant properties concerning this step.

Parameters:

• part_properties (dict[str, Any])

• extra_properties (list[str] | None)

Return type:

dict[str, Any]

classmethod unmarshal(data)

Create and populate a new state object from dictionary data.

Parameters:

data (dict[str, Any])

Return type:

StepState